Re: manpage generation questions

Am Dienstag, 15. März 2005 01:54 schrieb Steve Cheng:
> On Fri, Mar 11, 2005 at 10:58:52PM +0100, Hendrik Sattler wrote:
> > there are some strange things with docbook2x-0.8.3 (Debian Sarge):
> > - When I choose an encoding with --encode, it is only honored for UTF-8,
> > ISO-8859-15 still gets "\(:a" instead of "ä". The problem with "\(:a" is
> > that the man program in Debian does only show an 'a', not an 'ä'.
>
> The problem is that the mappings "ä" --> "\(:a"
> etc. are executed before the encoding conversion.
> I had thought this did no harm, but apparently not :(

Actually, I do like it but the man program in Debian Sarge does not. It only 
shows an "a" in an ISO-8859-15 locale but the "ä" in an UTF-8 locale.

> You can override this behavior as follows.
> Copy roff.charmap in the docbook2X charmaps/ directory
> to some other file, say, roff.iso-8859-15.charmap.
> Go edit that file and dike out all the undesired mappings.
> Then run docbook2man (or db2x_manxml)
> with the
>
> --utf8trans-charmap=/path/roff.iso-8859-15.charmap
> --encoding=iso-8859-15
>
> options.
> This should do it.
>
> (How I wish people would just switch to UTF-8, then there won't be
> these annoying problems...)

Sadly, UTF-8 brings some other problems with many programs, e.g. GTK1 based 
programs cannot handle UTF-8 at all.

> > - the .TH macro has some more parameters (the 4th is displayed at the
> > bottom left of a manpage) that cannot be used, or maybe I missed how.
>
> Actually, you can use write
> <refentry>
> ...
> <refmeta>
> <refmiscinfo>4th parameter text</refmiscinfo>
> </refmeta>
> </refentry>
>
> or the header-4 string XSLT parameter to specify it.
> (I think I only documented this in docbook2X 0.8.5,
> but you can read all about the details in xslt/man/refentry.xsl.)

Thanks, works even with 0.8.3 from Debian Sarge.
However, the 
file /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
from the docbook-xsl package uses another location:
  refentry/refentryinfo/productname
Another program like yours, xmlto, uses this layout. Additional, this place 
seems to make more sense since the date is also located, there. Maybe 
docbook2x can also choose this as second possible location?

Additionally, the synopsis part from the nwalsh XSL has this nice intedation:
 command option ........ more options
         more options .......
and yours does not. You also seem to add an implicit space for [ and ] 
(instead of [and]).

Both make it not possible to get something like
.TP 20
into the manpage when using a variablelist. However, variablelist has an 
attribute termlength that could be used for this (or maybe I missed the point 
of it). The current situation is an implizit value of (looks like) 7.

It's sad, though, that the debian package renamed the docbook2man script to 
docbook2x-man because another (SGML-only) package (docbook-utils) already 
ships a docbook2man script.
If I now use docbook2man in my Makefile, it will work with many distributions 
but not with Debian :-(
So I guess, I'll still have to see how xmllint, xsltproc and your utf8trans 
really work together :)

HS

-- 
Mein GPG-Key ist auf meiner Homepage verfügbar: http://www.hendrik-sattler.de
        oder über pgp.net

PingoS - Linux-User helfen Schulen: http://www.pingos.org

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.5 (GNU/Linux)

iD8DBQBCNrpKzvr6q9zCwcERAuhiAKCJPpCVYgg1qSdz+IWSoCLgwjUCtACeKKXb
840CKt2oQ5BIvvYNevASoA8=
=5sq6
-----END PGP SIGNATURE-----