Re: here is a skeletal docbook "template" with makefile

[Grant Taylor <gtaylor@picante.com>]

>>>>> Grant Taylor <gtaylor@picante.com> writes:

> The "kit" is at http://www.picante.com/~gtaylor/dbskel.tar.gz

Whee!  Not even a day later, and I've squashed a few bugs in the
makefile and/or my own document:

In the Makefile, adding -Vtex-backend -i output.print to the jade
command line for the $(NAME).tex rule corrects two buglets:

 - Figures now float as expected with my (mangled) ldp.dsl that turns
   this feature on.

 - SimpleLists as table entries do not exhibit a problem like the
   below indentation problem, where the first line is indented for no
   good reason.

I've modified my tarball to have this fixed.  This option is lifted
from the FreeBSD handbook makefile.


I also found a subtle error or two in my input files that cause an
output ugliness.  Two different, but similar things are described
below:


GOTCHA ONE:

>  - In print output, a few things like lists have a funky leading
>    indentation that is not appealing.  There seems to be no variable
>    to tweak this easily.

This turns out to be due to a subtlety around ListItem tags.  If you
do:

  <ListItem>
    <Para>
      This is some stuff...
    </Para>

    <Para>
      This is other stuff...
    </Para>
  </ListItem>

  <ListItem>
    <Para>
      This is more stuff...
    </Para>
  </ListItem>

You'll see:

 *  This is some stuff.  Dum de dum de dum de dum
   the paragraph wraps and aligns at the right place
   except for the first line

   This is other stuff.  This para is all fine, with
   the second line wrapped flush just like the first

 *  This is more stuff.  This para is indented funny
   again.  It looks wrong.

A similar thing happens to ListItems in VariableLists.

The solution is to write instead:

  <ListItem>
    <Para>This is some stuff.
    </Para>

    <Para>
      This is other stuff.
    </Para>
  </ListItem>

  <ListItem>
    <Para>This is more stuff.
    </Para>
  </ListItem>

IE, the first para (or simpara) after a listitem opening tag won't
have leading whitespace ignored the way most other paras seem to.


GOTCHA TWO:

Given:

   <OrderedList>
    <ListItem>
     <SimPara>The user submits a job along with his selection of
      options.  The job data is usually, but not always, Postscript.
     </SimPara>
    </ListItem>

    <ListItem id="background-filtering">
    <indexterm><primary>filtering</primary></indexterm>
     <SimPara>The spooling system applies the user's selected options
      to the job, and translates the job data into the printer's
      native language, which is usually not Postscript.  This step is
      called <emphasis>filtering</emphasis>; most of the work in
      setting things up lies in getting the proper filtering to happen.
     </SimPara>
    </ListItem>
   <OrderedList>

You get:

 1. The user submits a job along with...
    This lines up nicely on the right.

 2.
    The spooling system applies the user's selected options to...
    This lines up with the line above, but not horizontally with the 
    number!


Moving the <indexterm> tag outside the ListItem fixes this:

   <OrderedList>
    <ListItem>
     <SimPara>The user submits a job along with his selection of
      options.  The job data is usually, but not always, Postscript.
     </SimPara>
    </ListItem>

    <indexterm><primary>filtering</primary></indexterm>
    <ListItem id="background-filtering">
     <SimPara>The spooling system applies the user's selected options
      to the job, and translates the job data into the printer's
      native language, which is usually not Postscript.  This step is
      called <emphasis>filtering</emphasis>; most of the work in
      setting things up lies in getting the proper filtering to happen.
     </SimPara>
    </ListItem>
   <OrderedList>

I don't know if this is a bug or what, but there it is.  Don't do
that ;)

--
Grant Taylor - gtaylor@picante.com - http://www.picante.com/~gtaylor/
    Linux Printing Website and HOWTO:  http://www.linuxprinting.org/
    I do consulting in most things Unix/Linux/*BSD/Perl/C/C++


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org