[Openswan dev] problems in several man pages you maintain

[D. Hugh Redelmeier]

| From: Eric S. Raymond <esr at thyrsus.com>

| > Note that there are even more duplicates when you realize that many of
| > these files are just symlinks to others.  It is conventional in man
| > pages to document related entries in one page but have several names
| > for that page; I take it that docbook is incapable of handling this
| > useful convention.
| 
| It's not DocBook that has the problem -- one can make symlinks to simulate
| the .so behavior.  It's just my bug-tracking tools not being as smart as 
| they should be.

Let's get this straight: your tool said:

    1. There are multiple name lines.  This makes it impossible to
    translate the page to DocBook.  It may also confuse some
    implementations of man -k.

Part of the convention of having multiple names for the file is also
to have multiple name lines.  So docbook does not support this.

That your tool reports for every filename of the file is a separate,
less important, and more easily solved problem.

Would it be easy to fix the docbook problem?  I certainly think that
documenting closely related names in one page is a Good Thing.

| > I have some more substantive comments, but I will await a revised
| > report from you.
| 
| Revised how?  Can you not just throw out the duplicate patches?

I could, but since I presume that you will send a revised version, I
intended not to bother duplicating your effort.  Consider this mutual
debugging: you tell us what is wrong with our stuff and we tell you
what is wrong with yours (for some meaning of "wrong").

Thanks again,

Hugh Redelmeier
hugh at mimosa.com  voice: +1 416 482-8253