[Openswan dev] problems in several man pages you maintain

[Eric S. Raymond]

D. Hugh Redelmeier <hugh at mimosa.com>:
> | 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 is my error and I have just fixed the message.  What it should have
said is that multiple *description sections of name lines* are the problem.  
DocBook supports having more than one name associated with a refentry, but
only one description line.

So, you can't do this:

NAME
   fee - first iteration of giant's complaint 
   fie - second iteration of giant's complaint 
   foe - third iteration of giant's complaint 
   fum - fourth iteration of giant's complaint 

But you can do this:

NAME
   fee, fie, foe, fum -- tools for giant-style complaining

and all but one of the copies can be symlinks or hardlinks.

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

Yes, it is.

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

It's very hard to change the DocBook DTD, and doing it tends to break
the stylesheets.
 
> | 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").

OK.  I will try to fix the report generator this afternoon.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>