Re: man page bug in addr2line

[Russ Allbery]

Eric S Raymond <address@hidden> writes:

> I'm working on a program that automatically translates manual page
> sources to DocBook markup.  You can find out more about this program at

>       http://www.tuxedo.org/~esr/doclifter/

> If you are not already considering it, please think about moving your
> documentation masters to DocBook.  Tools to generate man pages
> (docbook2man) HTML (docbook2html) and PostScript (docbook2ps) from
> DocBook masters are open source and generally available.  My program,
> doclifter, should make moving your masters to dicbook a pretty painless
> process.

DocBook is an ugly and difficult-to-write documentation format that wastes
time for documentation maintainers and makes it more difficult to get
people to contribute documentation fixes, as far as I'm concerned.  I'm
not one of the people who works on the binutils documentation, but I
definitely have no intention of ever using DocBook as anything other than
an output format.

In any event, if you're applying tools to manual page source with current
versions of binutils, I believe you're working with significantly
downstream output.  IIRC, current versions of binutils use texi2pod to
generate POD manual pages from texinfo and then use my pod2man tool to
generate manual pages from that.

> I have found some markup bugs on a manual page you maintain.  Please fix
> these in your next release.

> In addr2line.1, use of the macro .TP in the "Synopsis" section confuses
> my synopsis parser.  Please don't use paragraph requests in that
> section,

This is not a bug in the manual page.  This is a bug in your synopsis
parser.  There is nothing about the manual page format that disallows
paragraph requests in the synopsis.

-- 
Russ Allbery (address@hidden)             <http://www.eyrie.org/~eagle/>