Dash escaping in man pages

[Jeff Johnson]

tracker

[devzero2000 (pinto-elia)]

The bug is confirmed by these threads, just for example

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=297133 in replay to
http://lists.debian.org/debian-devel/2005/02/msg01320.html

Also help2man escape -- in -\-., also the coreutils escape -- in comand line argument in -\-

[Jeff Johnson (n3npq)]

Note that real source for rpm man pages is in the max-rpm checkout from @rpm5.org cvs in DocBook.

[devzero2000 (pinto-elia)]

In reply to #2

Ok, noted. But I can not rebuild the man pages, also BEFORE to do any change. I have tried to solve it but can not find what is missing: the problem manifest itself both on Ubuntu(with a minor fix a configure.ac) and FC12. All the docbook package are installed. Any hint ?

export SHELL="bash -x"
./configure

......

make
rm -rf html
mkdir -p html/stylesheet-images
cp /usr/share/sgml/docbook/dsssl-stylesheets/images/*.gif html/stylesheet-images
touch generated-index.sgml
touch setup
( cd html ; \
          /usr/bin/jade -d ../redhat-html.dsl -t sgml -ihtml -V html-index ../max-rpm.sgml ; \
          /usr/bin/perl /usr/bin/collateindex.pl -o ../temp-index.sgml HTML.index ; \
        )
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/docbookx.dtd:116:17:E: "X20AC" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:42:29:E: "X021B6" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:43:29:E: "X021B7" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:44:29:E: "X021D3" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:45:29:E: "X021CA" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:46:29:E: "X021C3" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:47:29:E: "X021C2" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:48:29:E: "X02199" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:49:29:E: "X02198" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:50:29:E: "X021D4" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:51:29:E: "X02194" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:52:29:E: "X021AD" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:53:29:E: "X021DA" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:54:29:E: "X0219E" is not a function name
/usr/bin/jade:/usr/share/sgml/docbook/xml-dtd-4.5-1.0-48.fc12/ent/isoamsa.ent:55:29:E: "X021C7" is not a function name
...................

[Jeff Johnson (n3npq)]

My comment #2 was largely FYI. Getting docbook setup to use the maxrpm
sources for man pages has always been hugely painful.

So just fix the troff directly. There are tags in cvs that can/will be used
to pull modifications into the maxrpm docbook eventually.

But if there are major rewrites (rather than spot fixes) of rpm man pages that
are going to be attempted, then docbook -> troff transforms are likely a
beetter approach because docbook can also hit other targets like XSLFO or
TeX seamlessly.

[Eric MSP Veith (eveith)]

How about using ASCIIDoc or something similar? Git uses it for man pages generation, too. It's worth a look I'd say, and could be used for other documentation pourposes on RPM5, too.

[Jeff Johnson (n3npq)]

Anything is possible. DocBook was chosen as "best available"
and "most widely deployed" and "what max-rpm uses" at the time.