pw.conf.5: Make the .Nd more informative

[ziaee]

usr.sbin/pw/pw.conf.5

30–31

1. Document descriptions should not have crossreferences especially, but really any child macros. Manpage compiler upstream has said (quite strongly and hilariously actually) it's wrong.

2. Multiline Nd is not portable, our compiler does work with it but, but it's kinda never appropriate because Nd is "one line about what it does".

3. Basic manual search includes the Nm and Nd. So, self referential descriptions are not just bad for eloquence but also mechanically wasteful and useless.

How's this? It follows more closely the description set by pw(8) so there will be a narrative consistency and it will show up in more of the same searches like "group".

[temcbun_gmail.com]

Thank you for the review!

Document descriptions should not have crossreferences especially, but really any child macros.

Oh, yeah, I found a warning about it in mdoc(7) (though it says that child macros are technically not wrong):

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.

Manpage compiler upstream has said (quite strongly and hilariously actually) it's wrong.

But where exactly does it say this? I tried to lint the page with mandoc(1), but I see no errors or warnings regarding .Nd:

$ mandoc -T lint usr.sbin/pw/pw.conf.5 
mandoc: usr.sbin/pw/pw.conf.5:70:2: STYLE: useless macro: Tn
mandoc: usr.sbin/pw/pw.conf.5:162:2: STYLE: useless macro: Tn

How's this? It follows more closely the description set by pw(8) so there will be a narrative consistency and it will show up in more of the same searches like "group".

Your variant looks good to me, I will now update the revision.

[temcbun_gmail.com]

Get rid of .Xr in .Nd and make the .Nd itself more informative.

[ziaee]

In D58329#1338905, @temcbun_gmail.com wrote:

Document descriptions should not have crossreferences especially, but really any child macros.
Manpage compiler upstream has said (quite strongly and hilariously actually) it's wrong.

But where exactly does it say this?

https://marc.info/?l=mandoc-tech&m=172624249227999&w=2