Hello, Steve. On Sun, Jun 2, 2013 at 2:58 PM, Yorvyk <yorvik.ubu...@googlemail.com> 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@lists.launchpad.net Unsubscribe : https://launchpad.net/~ubuntu-manual More help : https://help.launchpad.net/ListHelp
