Re: [docbook-apps] man page generation: numbering and paragraphing of examples

["Bob Stayton" <bobs@sagehill.net>]

Hi,
The problem with the missing line break was fixed sometime between 
stylesheet versions 1.72 and 1.74, so upgrading your DocBook XSL should fix 
that one.  It will put a .PP before the example.

Eliminating the number for example labels requires changing the generated 
text.  Add something like this to your customization layer:

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0";>
  <l:l10n language="en">
   <l:context name="title">
      <l:template name="example" text="Example.&#160;%t"/>
   </l:context>
   <l:context name="title-numbered">
      <l:template name="example" text="Example.&#160;%t"/>
   </l:context>
  </l:l10n>
</l:i18n>

The general process for customizing generated text is described here:

http://www.sagehill.net/docbookxsl/CustomGentext.html

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Ralph Böhme" <ralph@rsrc.de>
To: <docbook-apps@lists.oasis-open.org>
Sent: Sunday, January 25, 2009 5:23 AM
Subject: [docbook-apps] man page generation: numbering and paragraphing of 
examples


Hello list,

I'm trying to reconstruct the docbook toolchain and config for the
documentation of the Netatalk OS project. The toolchain and config
that was in use the last time the documentation was generated from the
docbook xml files was lost due to a hd crash. The person who did the
processing is not particapating any longer in the project. I'm trying
to bring us back online.

So far I've succesfully regenerated the html and man pages docs and
they mostly have the same appearance as the original one.

Currently I'm trying to solve some minor glitches:
- examples are numbered dispite all my attempts to turn that off
- an example following a para is appended without newlines

I'm using `xmlto man` and am injecting XSL fragements via -m switch:
$ xmlto man -m man.xsl manual.xml

$ cat man.xsl
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
xmlns:fo="http://www.w3.org/1999/XSL/Format";
version="1.0">
<xsl:param name="refentry.version.suppress">1</xsl:param>
<xsl:param name="chapter.autolabel" select="0"></xsl:param>

With chapter.autolabel I was able to change the numbering scheme form
x.y to x, but I couldn't find and apply any parameter to turn it off.
I've tried all of the online documented ones [1] without success.

Example of the unwanted numbering:
---8<---
        Example 14. afpd.conf default configuration

           - -transall -uamlist uams_clrtxt.so,uams_dhx.so
        Example 15. afpd.conf MacCyrillic setup / UTF8 unix locale
---8<---

It's also missing a newline befor Example 15. The code is [2]:
---8<---
<example>
<title>afpd.conf default configuration</title>
<programlisting>- -transall -uamlist uams_clrtxt.so,uams_dhx.so</
programlisting>
</example>

<example>
<title>afpd.conf MacCyrillic setup / UTF8 unix locale</title>
<programlisting>- -transall -maccodepage mac_cyrillic -unixcodepage
utf8</programlisting>
</example
---8<---

Example of missing leading newline:
---8<---
Daemon loglevels: LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE, LOG_INFO,
LOG_DEBUG, LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8,
  LOG_DEBUG9, LOG_MAXDEBUG Example 13. Some ways to change afpd’s
logging behaviour via -[un]setuplogExample:
---8<---

Code:
---8<---
<para>Daemon loglevels: LOG_SEVERE, LOG_ERROR, LOG_WARN, LOG_NOTE,
LOG_INFO, LOG_DEBUG, LOG_DEBUG6, LOG_DEBUG7, LOG_DEBUG8, LOG_DEBUG9,
LOG_MAXDEBUG</para>
<example>
<title>Some ways to change afpd's logging behaviour via -
[un]setuplog</title>
<para>Example:
<programlisting>-setuplog "logger log_maxdebug /var/log/netatalk-
logger.log"
-setuplog "afpdaemon log_maxdebug /var/log/netatalk-afp.log"
-unsetuplog "default level file"
-setuplog "default log_maxdebug"</programlisting>
</para>
</example>
---8<---

Can anybody help fix this ? While the numbering might actually be
acceptable or even better, the paragraphing would require fixing all
man pages. I have ~35 of them... :-O

Thanks and regards
-Ralph

[1]
http://docbook.sourceforge.net/release/xsl/current/doc/html/labels.html

[2]
<http://netatalk.cvs.sourceforge.net/viewvc/netatalk/netatalk-docs/manual/man/man5/afpd.conf.5.xml?revision=1.18&view=markup
 >
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org