svn commit: r333494 - head/share/man/man7

[Rodney W. Grimes]

> On Sun, May 13, 2018 at 8:14 PM, Rodney W. Grimes <
> freebsd at pdx.rh.cn85.dnsmgr.net> wrote:
> >
> > It did take me some time to track down this "crazy concept you all
> > think I just invented", but it is infact in the GNU groff info
> > documentaton (found on my 5.4 systems in /usr/share/info/groff.info.gz):
> 
> Just to be clear, I don't think these rules apply to FreeBSD. We use
> mandoc. See mandoc(1) for the rules that apply to us.

That is a rather fine line.  mandoc is a replacement set for groff -man,
which is a replacement for troff/nroff man.  What I found are helpful
guidelines for anyone writting groff type input, they still apply to
mandoc.

> 
> And, again, just to be clear, I am also pretty sure the following rule
> doesn't apply:
> 
> >    * In keeping with this, it is helpful to begin a new line after every
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Again, these are helpful things that have been around for a very decades,
and for someone who has worked on a good deal of *roff input, it is truely
helpful in many ways to do this.

As one sample of helpful it makes it usually easier to find things in the
*roff sources when trying to edit a manpage,  Another is it minimizes
diffs when making changes.


> >      comma or phrase, since common corrections are to add or delete
> >      sentences or phrases.
> 
> OTOH, I believe we do have a rule about beginning each sentence on a new
> line. (Again, see mandoc(1).)

Yes

> 
> And, it is easy to figure out whether your page complies with the style
> using mandoc's checkers.

Comply with and being of good style and design are not one and the same.

> For example:
> 
> $ mandoc -W all,stop /usr/share/man/man9/tcp_functions.9.gz
> mandoc: /usr/share/man/man9/tcp_functions.9.gz:284:16: WARNING: new
> sentence, new line
> 
> Jonathan
> 
> PS: I'm happy to be corrected by one of the man page experts, which I most
> certainly am not.

I would encoruage the man page expects to adopt this set of helpful guidelines,
not necessarily making them hard rules,
but at least suggesting one knows about them.


-- 
Rod Grimes                                                 rgrimes at freebsd.org