lubuntu-wiki-docs team mailing list archive

[Phill Whiteside <PhillW@xxxxxxxxxx>]

Right people, can we have a call on who wants what of the three
projects[1]? Jason is away fora  week, so I'd really like this sorted for
when he gets back as we have to give the devs some sort of idea of what
will happen.

Thanks,

Phill.
1. https://wiki.ubuntu.com/Lubuntu/DocumentationTeam#Sub_Teams
---------- Forwarded message ----------
From: Kevin Godby <godbyk@xxxxxxxxx>
Date: 1 June 2013 06:26
Subject: Re: Lubuntu Manual - Getting Started With Lubuntu
To: Phill Whiteside <PhillW@xxxxxxxxxx>


Hello, Phill.

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



-- 
https://wiki.ubuntu.com/phillw