[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: Starting a fresh documentation project
Hi, I authored using SGML Docbook at work for about two and a half years. For that previous project (about 4 years ago we started that one) we converted a bunch of word docs via rtf and a perl script to basic docbook, then cleaned it up over a couple of months (100's of pages). I'm new to the lists, so please forgive me if this question has recently been posted. I am now in the luxurious position of starting to write some documentation for my new company, but from scratch this time. It's been a couple of years since I did any serious doco, and of course I'm going to use docbook again. Now there are some decisions to make, for which I seek some comments on the tradeoffs/ advantages of the options available: - sgml or xml docbook? - toolchain? - stylesheets/ addons that might be useful? - what do I need to read to get control over my output (eg. section indents, fonts, spacing) - as I never solved this one in the DSSSL days (ie I found DSSSL too arcane, and/ or didn't find a book or tutorial) - images What is given is my environment and requirements: - Debian GNU/Linux exclusively ("testing") (i386) - output to HTML, and either PDF or RTF, for distribution, and Postscript (I assume) for printing - large documentation set - perhaps four or five books (2 years?) - many images in DIA ---- I spent most of this last weekend attempting to get back up to speed, trying out docbook xml. Problems I expect to come across soonish, and would like some pointers to doco to help me get it right first time, include the following: 1) On the weekend, I found a post mentioning how to create lists without the full line of excess space after each list item in the HTML output (use simpara). But this doesn't work if you use two simparas, one after the other. I want spacing at 3pt or else 0pt, but not a full blank line after every para. This is an example that I never solved in my first docbook excursion years ago (I never figured out even simpara at the time, so we put up with spaced out lists). 2) Images - I have created a simple image in DIA for my introduction, and could not get jw (I'm on debian) to include the image in the pdf output. I tried png, jpeg, eps, ps, even tif (converted the png output of dia using the gimp). Getting good images in printed output was something we all but gave up on perfecting last time around too. I'll be creating all images from scratch, so I'd be happy to learn to use XFig or something else than Dia, as long as it is Free Software (as in freedom)! As mentioned, I have the luxury of starting from scratch. 3) Tables - didn't try one on the weekend, but this was another thing that caused us a lot of grief first time round, particularly with the rtf output. Perhaps it was a problem with pdf too, I can't remember. ---- I am quite happy to learn whatever I have to learn - get pointed to books, tutorials, whatever. But I want to know if these three main problems above can be handled with reasonable output quality nowadays. Thanks Zen -- Mr Zenaan Harkness, Manager, VIDC Phone: +678 25 151 Fax: +678 25 178 Mobile: +678 45 179 Please respect the confidentiality of this email.
Powered by eList eXpress LLC