Re: [docbook-apps] Some issues regarding the manpages stylesheet

[Michael Smith <smith@xml-doc.org>]

Hi Costin,

> The new manpages stylesheet of 1.69.0 is great.  The output
> quality is impressive.

Thanks. I made the changes for 1.69.0, so I am responsible for
both the good stuff and the bad :)

(By the way, most (or all) of the great stuff was in there before
the 1.69.0 release.)

> But I have some remarks to make.
>
> 1. There should be some way to specify the output directory, something 
> like 'base.dir' used in html chunking.

I agree. There is an open feature request for that -

  http://sourceforge.net/tracker/index.php?func=detail&aid=1170317&group_id=21935&atid=516914

But I will not be able to implement that until some time next
month (September). If anybody cares to submit a patch in the mean
time, it would be welcome. Once it has been checked in, I will try
to post a note here. It will be available in the next snapshot
that is automatically built after the checkin.

It won't be available in an official release until the 1.70.0
release, which will be in October at the very earliest (most
likely later).

> 2. Some useless code should not be generated. For example, the following 
> xml code (perhaps these long lines will be truncated) ...
> 
> <term><option>--alev=<replaceable 
> class="option">level</replaceable></option></term>
> 
> ...produces the next output:
> 
> \fB\-\-alev=\fR\fB\fIlevel\fR\fR

[...]

> I know, there is no simple solution for it. :(

There is a solution for everything. :) The question is whether the
benefits the change would provide would justify the time needed to
make it. In this case, the page renders fine even with the extra
junk in there, so the visible benefits of making the change are
exactly zero.

If you can find a case where the redundant \fB stuff is causing
pages to be rendered differently than you'd expect, that would be
another story...

> 3. When <screen>...</screen> is used, before '.nf' and after '.fi' there 
> are empty lines. These lines ARE NOT IGNORED by groff.

No need to shout :) I am aware of that one already. I decided to
deal with it by making a change that "normalizes" line space
around output of Screen and other such DocBook elements ("verbatim
environments" in DocBook ling).  You can try it out by testing
with the latest snapshot:

  http://docbook.sourceforge.net/snapshot/

If you try that and find that it is not giving you the output
you'd expect, please post another message here describing what you
think the output should look like.

> 
> 4. When the next syntax is used ...
> <para>
>   <command>blabla</command>
> </para>
> 
> ...in the output code there is one space (' ') before the '\fBblabla\fR', 
> at the beginning of the line. This one is NOT DISCARDED by groff. That 

hmm, more shouting... I'm old, but not that old. I can hear you OK
without the shouting, I think. Maybe. You might even try whispering.

> space character is absent when the following syntax is used:
> <para><command>blabla</command></para>

Then perhaps you ought to use that syntax instead :)

Seriously, <para><command>... is how I would personally mark it
up, and how I think may others would as well.

The Command element is an inline element, not a block element. So
the whitespace between the end of the <para> tag and the <command>
tag is significant whitespace as far as XSLT output is concerned.

The HTML stylesheet also preserves that space. Run your source
doc through the html/docbook.xsl or html/chunk.xsl and then open
the resulting HTML file in a text editor. You will see that same
space between the <p> tag and the <span> tag that is wrapped
around the <command> output. Actually, you will see that your line
breaks are also preserved there.

The difference is that your browser strips that leading space and
line break after the <p> and before the <span>.

groff, on the other hand, treats the corresponding space in your
man-page output as a literal space.

I suppose I could have the manpages stylesheet strip spaces after
.PP macros. If it is important to you to have that space stripped,
please file a feature request here:

  http://sourceforge.net/tracker/?atid=516914&group_id=21935&func=browse

  --Mike

-- 
Michael Smith
http://sideshowbarker.net/

smime.p7s