ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

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