ubuntu-manual team mailing list archive

[John Cave <john.cave5@xxxxxxxxxxx>]

I would be interested in contributing to a Lubuntu manual.

John C

On Mon, Jun 3, 2013, at 02:00 AM, Kevin Godby wrote:
> Hello, Steve.
> 
> On Sun, Jun 2, 2013 at 2:58 PM, Yorvyk <yorvik.ubunto@xxxxxxxxxxxxxx>
> wrote:
> >> Are you considering proposing some type of partnership with the
> >> Ubuntu Manual Project?
> >
> > Yes, no, maybe, but I'd like the opinions of the current manual team on
> > this. Could the Lubuntu part be part of the current book or should it be
> > a separate entity. I think the later. I see no point in creating an
> > entirely separate structure when there is already one we could latch on
> > to, but again I would like the opinions of those already involved.
> 
> I think it'd be best if the Lubuntu material were in a separate
> manual. Otherwise the reader would constantly have to determine if the
> information their reading is for Ubuntu or Lubuntu.
> 
> You're welcome to use our toolchain and I'm happy to help you get
> started.  We could even host PDFs of the Lubuntu manual on our website
> if you like.
> 
> Phill forwarded one of the messages from the Lubuntu-users mailing
> list to the Ubuntu-docs mailing list when you guys were discussing
> markup languages.  I wrote a response to Phill with my thoughts. I've
> included the text of that email below. You're welcome to forward it
> along if you like.
> 
> ———
> I skimmed through the thread on the lubuntu-users list.  I'm the
> primary LaTeX guy on the Ubuntu Manual project. If you're interested
> in using our toolchain to built a Lubuntu manual I'm happy to help out
> with that or answer any questions.
> 
> I'm not too clear on the goal or desired form of the Lubuntu manual,
> so here are some general notes.
> 
> LaTeX is a great typesetting system for generating PDFs and printed
> documents. It's fairly useless when it comes to generating any other
> formats, though.  If you only want to have a PDF or printed book, then
> using LaTeX for the source format will serve you just fine.  If you
> want to generate ebooks, web sites, or other formats (in addition to
> or instead of the PDF or printed book), then I would recommend
> *against* using LaTeX as your primary source format. LaTeX is quite
> difficult to parse and there aren't any good parsers out there to
> convert LaTeX reliably to other formats.
> 
> The Ubuntu docs project uses Mallard as its source format.  Mallard is
> an XML-based markup language.  The Mallard files are used in Yelp (the
> desktop documentation viewer) and are converted to HTML for the
> help.ubuntu.com website.  Mallard is a decent format for writing
> technical documentation as it was designed with that specific goal in
> mind.  Since Mallard is XML-based, it can be parsed easily by many
> tools and converted to other formats.
> 
> The Ubuntu docs project used to use Docbook as its source format and
> the other derivative documentation projects and the Ubuntu server
> guide still use Docbook.  Docbook, like Mallard, is XML-based. It's
> considerably more complex than Mallard but you can stick to a smaller
> subset of its markup if you like.  As with Mallard, Docbook can be
> parsed by a number of tools and converted to other formats fairly
> easily.
> 
> To generate the Ubuntu server guide PDF, the Docbook sources are run
> through Apache FOP instead of LaTeX.  I'm not all that familiar with
> Apache FOP.  I do generally prefer LaTeX's PDFs to those that FOP
> generates, however. I think the output looks a lot nicer.  This may
> simply be because the default stylesheets used by Apache FOP aren't
> very good, though.
> 
> To sum up my recommendations:
> 
> If you're looking to generate topic-based help similar to the current
> documentation on help.ubuntu.com, then I recommend starting with
> Mallard markup. Mallard is designed specifically for this purpose.
> Mallard doesn't appear to be suitable for books, however.
> 
> If you're looking to generate *only* a printed book or PDF, then you
> can start with LaTeX as the Ubuntu Manual project has.  LaTeX is not
> easily converted to other formats but is specifically designed to
> typeset printed books.
> 
> If you're looking to generate a printed book and an ebook and a
> website, then I'd suggest starting with Docbook. While Docbook is more
> complicated than Mallard (there are a lot more tags to learn), it's
> also more flexible and is geared toward generating longer-form
> documents like books.  Since it's XML-based, it can be converted
> fairly easily to other formats such as HTML and even LaTeX.
> 
> Incidentally, if you do choose to go the Docbook → LaTeX → PDF route,
> I would suggest tweaking the LaTeX to improve it's formatting as
> Docbook doesn't specify all the nitpicky typographical tweaks that
> LaTeX can take advantage of.  (But that's just me being a bit of a
> perfectionist.)
> 
> Please feel free to forward this email to the lubuntu-users list and
> anyone else you like. And I'm happy to answer any questions about
> LaTeX, the Ubuntu Manual tools and processes, or other markup
> languages (though I'm not quite as familiar with them).
> ———
> 
> —Kevin Godby
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~ubuntu-manual
> Post to     : ubuntu-manual@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~ubuntu-manual
> More help   : https://help.launchpad.net/ListHelp


-- 
Look! No paper!