man page bug in addr2line

[Eric S. Raymond]

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.

Many major open source projects (including the Linux Documentation
Project, GNOME, KDE, and FreeBSD) have moved to DocBook or are in the
process of doing so.  The format has many advantages over man, info,
texinfo, or HTML; by moving everybody to it, we should be able to
support unified browsing of all system documentation with Web-like 
hypertext capabilities, automatic indexing, and rich search facilities.

In the process of debugging doclifter, I have discovered many bugs in 
man page layout.  These are significant because thdey make automated
translation to DocBook more difficult, and often confuse other document-
mining tools (such as indexers).

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,

The underlying problem is that DocBook can't handle running text in a
Synopsis section, and there is no good way to tell running text from 
certain kinds of synopsis line.
-- 
                <a href="http://www.tuxedo.org/~esr/";>Eric S. Raymond</a>

It is proper to take alarm at the first experiment on our
liberties. We hold this prudent jealousy to be the first duty of
citizens and one of the noblest characteristics of the late
Revolution. The freemen of America did not wait till usurped power had
strengthened itself by exercise and entangled the question in
precedents. They saw all the consequences in the principle, and they
avoided the consequences by denying the principle. We revere this
lesson too much ... to forget it
        -- James Madison.