Re: [docbook-apps] Manpages, cmdsynopsis and sbr

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

Costin Stroie <cstroie@bitdefender.com> writes:

> I have found the following formatting error when using <sbr/> in 
> cmdsynopsis, for manpages.
> 
> <cmdsynopsis>
>   <command>bdmond</command>
>   <arg choice="opt">-s, --start</arg><sbr/>
>   <arg choice="opt">-k, --stop</arg><sbr/>
[...]
> When processed, the text is this one:
> 
> SYNOPSIS
>        bdmond [-s, --start]
>                [-k, --stop]
> 
> From the second argument the text is one column to the right.

Thanks for catching this and reporting it. It looks like this bug
has been around since v1.68.0 or v1.68.1. I didn't catch it
because I neglected to test with <sbr/> ...

> The explanation is in file synop.xsl, the template <xsl:template 
[...]
> <xsl:if test="position()>1"><xsl:value-of select="$sepchar"/></xsl:if>
> 
> The possible solution would be to move this line after the child has been 
> processed and to check if position is last. If not, write the sepchar.

I just checked in fix. The stylesheet now outputs the sepchar
before and Arg only if the first preceding sibling of the Arg is
not an Sbr. See patch below or just download the latest snapshot:

  http://docbook.sourceforge.net/snapshots/

> A related problem would be the same sepchar after the 'command'. In my 
> opinion, this should be blank, not the same sepchar.

hmm, I guess I agree that that it'd be best to have the sepchar
after the command be different than the character that separates
Args. But I don't think the stylesheets should be hardcoded to
output a blank after the Command.

The reason is that the stylesheets determine the value of $sepchar
based on your DocBook source. When processing each Arg, they check
to see if that Arg or one of its ancestor elements has a Sepchar
attribute. If it finds a Sepchar attribute, it uses the value of
that as both the separator between the Command and the first Arg,
and between each Arg and its sibling Args.

I think that's the correct behavior, because according to the
documentation (TDG), the only place where a Sepchar attribute is
valid is with Cmdsynopsis. And the doc for Cmdsynopsis says:

  SepChar specifies the character (a space by default) that should
  separate the Command and its top-level arguments.

  http://docbook.org/tdg/en/html/cmdsynopsis.html

It seems like the intent was actually that the value of Sepchar
should be used once: just as the separator between the Command the
Args _as a set_. So I guess it could be argued that the
stylesheets should not be using the value of Sepchar as the
separator between Args.

But it's clear at the very least that the value Sepchar should at
least be used before the first Arg, to separate it from the
Command. It would definitely be wrong to hard-code to be a blank.

  --Mike

Index: synop.xsl
===================================================================
RCS file: /cvsroot/docbook/xsl/manpages/synop.xsl,v
retrieving revision 1.21
diff -u -r1.21 synop.xsl
--- synop.xsl	13 Jul 2005 03:48:44 -0000	1.21
+++ synop.xsl	5 Oct 2005 05:25:25 -0000
@@ -36,7 +36,9 @@
       </xsl:otherwise>
     </xsl:choose>
   </xsl:variable>
-  <xsl:if test="position()>1"><xsl:value-of select="$sepchar"/></xsl:if>
+  <xsl:if test="position()>1 and
+                not(preceding-sibling::*[1][self::sbr])"
+          ><xsl:value-of select="$sepchar"/></xsl:if>
   <xsl:choose>
     <xsl:when test="$choice='plain'">
       <!-- * do nothing -->

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

smime.p7s