Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3166 bytes --]

Hi Ingo,

On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote:
>   MANUAL STRUCTURE
>   [...]
>            NAME
>            The name(s) and a one line description of the documented material.
>            The syntax for this as follows:
> 
>                  .Nm name0 ,
>                  .Nm name1 ,
>                  .Nm name2
>                  .Nd a one line description
>   [...]
>   MACRO REFERENCE
>   [...]
>      Nd line
>           A one line description of the manual's content.  This is the
>           mandatory last macro of the NAME section and not appropriate
>           for other sections.
> 
>           Examples:
>                 .Nd mdoc language reference
>                 .Nd format and display UNIX manuals
> 
>           The Nd macro technically accepts child macros and terminates with
>           a subsequent Sh invocation.  Do not assume this behaviour: some
>           whatis(1) database generators are not smart enough to parse more
>           than the line arguments and will display macros verbatim.
> 
> So the behaviour is more or less documented to be undefined for your
> input.  Maybe the manual should discourage child macros below .Nd in
> even stronger terms.
> 
> The decision to not attempt formatting in the apropos(1) output module
> but simply print the one-line strings verbatim is deliberate.  There are
> two reasons for this decision.
> 
> First, simplicity and maintainability.  The database lookup code in
> apropos(1) is already quite complex.  Hooking into the full mdoc(7)
> and man(7) formatting modules, which are even more complex, would
> send complexity through the roof.  In general, for a small UNIX-style
> program, its a good idea to have no more than one source of complexity
> to not risk losing track of what is going on.  Besides, fancy
> formatting is really beside the point of the apropos(1) program,
> it's all about providing a simple, straighforward index.
> 
> Second point, robustness.  A small number of crazy piople do all
> kinds of crazy stuff below the .Nd macro.  In extreme cases, i
> have even seen paragraph breaks and the like in there.  If apropos(1)
> would try to honour such madness in formatting, that might utterly
> mess up the formatting of the apropos(1) output, which is supposed
> to be a simple list of one-line entries.  Where to draw the line?
> Which macros should be honoured here, which shouldn't?  Even if you
> make such set of a decisions, it is very hard to implement because
> the renderes are recursive and you will have a hard time passing in
> information from the outside where to stop processing at which lower
> level.

Do you have similar limitations for the NAME section in man(7)?  I'm
wondering if some of the pages in the Linux man-pages would cause
problems.

(I'm not maintaining them at the moment[1], but I should have a look at
 this in case I come back to the project.)

[1]  <https://lore.kernel.org/linux-man/CACKs7VB_GEt_u463R4JvWveghBBscQeqaWtKrMmxNSQ2mn+-VA@mail.gmail.com/T/#t>


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]