OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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
 - 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:

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).

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.

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.


Mr Zenaan Harkness, Manager, VIDC
Phone: +678 25 151  Fax: +678 25 178  Mobile: +678 45 179
Please respect the confidentiality of this email.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC