Re: DOCBOOK: Starting a fresh documentation project

[Adam DiCarlo <adam at onshored dot com>]

Zenaan Harkness <zen@getsystems.com> writes:

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

I would never suggest tagging a certain way just to achieve a visual
effect or to work-around a bug in the stylesheets.

I would suggest that if this is a common enough issue, if there isn't
already a way, that it is something that should be fixed or
parameterized in the stylesheets themselves.  Towards that end I would
suggest checking the open bugs on the stylesheet you're using and
filing one if not.

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

I use dia and it works great.  For PDF output, you need your figures
in PDF.

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

Well, for one, table rendering is rather complex, and for two, the
styling issues in the DSSSL toolchain or stylesheets are often quite
different from those in the newer XSLT chain.  Again, check for the
existance of the issue, whether the bug is filed, and if not, files a
bug, including as an example the simplest possible XML file that
causes the problem.

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

I'm quite sure they *can* be handled.  You can just try to focus on
the content, make sure that the styling issues are identified and
filed, trusting they will be fixed by the "elves"; you can do your own
customization layers; you can provide patches so everyone has the
benefits of the better styling (provided the patches are general
enough).  So many options, isn't it fun.

Don't expect it to look beautiful out of the box.  This is a free
software project after all.

-- 
...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>