lubuntu-desktop team mailing list archive

[Phillip Whiteside <phillw@xxxxxxxxxx>]

Hi gang !!

I'm on the documents mailing list and much is going on with the various
formats. As such, does anyone have any preferences re:

"I think Xfce may be willing to adopt Mallard, but I'm not sure what the

situation is with KDE. The others I have even less idea about."


in [1]


How much do distributions like kubuntu, xubuntu and lubuntu derive their

docs from the ubuntu team? Will it mean that they have to also convert

to mallard? Or will they be converting the mallard back to docbook?


As for the translations I think that until we know how much we risk

messing up, we should not start doing too much. There are a lot of

translators that have put in hard work, and it would be very annoying

for them to have to do it again.


[1] https://lists.ubuntu.com/archives/ubuntu-doc/2010-July/014908.html

Oddly enough in this instance, we're in a better position as there is not
hundreds of pages of lubuntu documentation. I'd like to suggest that lubuntu
will follow the main ubuntu in the document format, which will be Mallard.

Your thoughts on the subject, please.

Regards,

Phill.


---------- Forwarded message ----------
From: Luke-Jennings <ubuntujenkins@xxxxxxxxxxxxxx>
Date: Thu, Jul 8, 2010 at 10:20 AM
Subject: Re: Using Mallard for Ubuntu docs
To: Jim Campbell <jwcampbell@xxxxxxxxx>
Cc: Manual mailing list <ubuntu-manual@xxxxxxxxxxxxxxxxxxx>, Ubuntu Doc <
ubuntu-doc@xxxxxxxxxxxxxxxx>


Hello,

On Mon, 2010-07-05 at 10:48 -0500, Jim Campbell wrote:
> Hi all,
>
> On Thu, Jul 1, 2010 at 3:31 PM, Kyle Nitzsche
> <kyle.nitzsche@xxxxxxxxxxxxx> wrote:
>         Hi All,
>
>         Just chiming in with my two cents for your consideration...
>
>         Wondering how this plan coordinates with the (lofty) goal that
>         was
>         discussed with great enthusiasm at Maverick UDS of creating a
>         common
>         pool for documentation source, where the Ubuntu Manual project
>         and the
>         Ubuntu Docs project can house doc source material, thereby
>         supporting
>         common usage and enabling all the good bits that derive from
>         that, such
>         as single-source maintenance, reusability, higher quality
>         (since errors
>         need to be corrected only once), but most importantly,
>         improving the
>         user experience through support of remixed content into
>         exciting new
>         contexts.
>
> From what I understand, the manual team was looking to do this for
> Maverick+1.  There was much discussion initially, but things seem to
> have quieted down, at least on their mailing list.  I'm not sure what
> is going on with that project now, but I'm copying their list in hopes
> that we'll get a reply here.
>
>         Since there is currently no docbook -> mallard converter (be
>         it through xslt or whatever), then that goal is made more
>         problematic
>         and distant, it would seem. Since this was a topic of high
>         interest at
>         UDS, this deserves some explicit consideration here, it would
>         seem.
>
>
> With regards to docbook -> mallard conversions, from my experience,
> creating topic stubs in Mallard makes it very easy to "stub-out"
> documentation, allowing new contributors to easily see what needs to
> be done, and to dig in.  This helps to alleviate the, "Where can I
> start?  What needs to be done?" question that confronts new
> contributors.  I think we'd be able to get a lot of new content fairly
> quickly using Mallard, even w/o conversion scripts.
>
>
>         There were discussions previously on this list about the
>         impacts
>         (regressions) that conversion from docbook to mallard would
>         have on
>         existing Ubuntu Docs translations, namely that inline tags are
>         often
>         different (between docbook and mallard), which means the
>         source strings
>         are different, which means existing translations break. So
>         that is a
>         potential regression that probably should be identified up
>         front with
>         some kind of fact-based analysis (5% of strings, or 50%?) that
>         gives
>         some idea of the extent of translation regression that may
>         occur, at
>         least to enable Ubuntu Translators to understand what kind of
>         additional
>         work to expect. If much of this can be avoided by writing a
>         clever
>         conversion script, then that should be identified as an
>         important piece
>         of work, it would seem.
>
> Others have commented on this over the past several days.
>
>
>         Also, see below...
>
>         On 06/30/2010 11:10 AM, Phil Bull wrote:
>
>         > Hi Jim,
>         >
>         > On Wed, 2010-06-30 at 09:51 -0500, Jim Campbell wrote:
>         >
>         >> So did we want to go ahead with using Mallard for this
>         release of
>         >> Ubuntu docs?  Phil, if I recall correctly, didn't you have
>         a branch of
>         >> Ubuntu docs containing page stubs from our prior release?
>         >>
>         > I think we should go ahead with the Mallard conversion. I
>         looked around
>         > for a branch containing stubs, but I didn't find one. Who
>         knows what I
>         > did with it?
>         >
>         > Ideally, we would coordinate with the GNOME doc team; we
>         should slot our
>         > docs into their Desktop Help. That's in a very early stage
>         of
>         > development at the moment, though. For now, we should
>         probably just
>         > identify clearly Ubuntu-specific areas of our own docs and
>         convert
>         > those.
>         >
>         >
>
>         The Ubuntu desktop experience is sometimes different from a
>         pure Gnome
>         one, at least until Ubuntu innovations like notifications,
>         window
>         buttons, and panel items like networking, about me, and power
>         management
>         are adopted in gnome (I think I got that list right...). So
>         this idea of
>         "slotting in" of ubuntu docs into gnome docs may result in two
>         explanations in such areas: if on Gnome, it's like this, if on
>         Ubuntu,
>         like this, which seems less than ideal. I continue to wonder
>         whether it
>         makes more sense to have an Ubuntu Docs framework that "slots
>         in" gnome
>         docs as appropriate, which, I realize, is how it is currently
>         done.
>         There is no technical barrier to including mallard content in
>         docbook
>         source that I know of.
>
> Let's tell Mark that Ubuntu has to use vanilla Gnome from here on
> out!  :-P
>
> Kyle makes a good point, but it is one that we will need to be mindful
> of at a topic-by-topic level regardless of what syntax is being
> used.
>
>
>         > It would be helpful to convert all of the existing DocBook
>         into plain
>         > text first. I find that much easier to deal with when doing
>         a
>         > conversion. I'll set-up a branch with Mallard .page stubs
>         and dump the
>         > text-only topics into the .page files. That should provide a
>         good
>         > starting point.
>         >
>         > To help the process along, would anyone be interested in a
>         Mallard
>         > training session on IRC?
>         >
>         > Thanks,
>         >
>         > Phil
>         >
>         >
>
>         Cheers,
>         Kyle
>
>
> I'm in favor of having a content pool in place for Ubuntu, but
> realistically . . .  would something be ready for Maverick+1?  I'm not
> so sure.  With a content pool, we're essentially talking about
> creating a CMS for Ubuntu docs.  I do think it is a good idea, and I
> do think we should plan for it, but I also think it is easier said
> than done, and I'm wary of trying to roll our own.
>
> Given that we have no CMS at this point, and that we don't have a
> concrete plan in place as to when we will have one (*and* when it will
> be production ready for all workflows, including translations), at
> this point I don't think it would be good to stay with the status quo
> until the CMS is ready.  I say that even with Kyle's caveats (which I
> appreciate) in mind.
>
> Please feel free to share other comments.  Thanks, all.
>
> Jim
>
Having read back through this thread I thought I would add my 2 cents.
It appears we have a bit of a problem, the docs team would like to
convert to mallard, which will have to be done by hand as there is no
tool. But there is no tool to convert to mallard to latex, but there is
a docbook to latex converter. So its a bit of a toss up, I would think
one of the teams can write a tool to convert to the other format, I am
sure there is someone with the skills.

Phill Bull said

"I think Xfce may be willing to adopt Mallard, but I'm not sure what the
situation is with KDE. The others I have even less idea about."

in [1]

How much do distributions like kubuntu, xubuntu and lubuntu derive their
docs from the ubuntu team? Will it mean that they have to also convert
to mallard? Or will they be converting the mallard back to docbook?

As for the translations I think that until we know how much we risk
messing up, we should not start doing too much. There are a lot of
translators that have put in hard work, and it would be very annoying
for them to have to do it again.

Regards

Luke



[1] https://lists.ubuntu.com/archives/ubuntu-doc/2010-July/014908.html



--
ubuntu-doc mailing list
ubuntu-doc@xxxxxxxxxxxxxxxx
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc