Date: Tue, 15 May 2018 11:01:28 -0700 (PDT) From: "Rodney W. Grimes" <freebsd@pdx.rh.CN85.dnsmgr.net> To: Jonathan Looney <jonlooney@gmail.com> Cc: rgrimes@freebsd.org, araujo@freebsd.org, "Conrad E. Meyer" <cem@freebsd.org>, src-committers <src-committers@freebsd.org>, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r333494 - head/share/man/man7 Message-ID: <201805151801.w4FI1S4w096720@pdx.rh.CN85.dnsmgr.net> In-Reply-To: <CADrOrms%2B7gwbuTgn2LLff4qe%2BSo2qLB4JNFV7mB6rKyqamKHjQ@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> On Sun, May 13, 2018 at 8:14 PM, Rodney W. Grimes <
> freebsd@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@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201805151801.w4FI1S4w096720>