From owner-svn-src-head@freebsd.org Tue May 15 18:01:33 2018 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 17E3CEEC543; Tue, 15 May 2018 18:01:33 +0000 (UTC) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (br1.CN84in.dnsmgr.net [69.59.192.140]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 6636D6B62E; Tue, 15 May 2018 18:01:31 +0000 (UTC) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: from pdx.rh.CN85.dnsmgr.net (localhost [127.0.0.1]) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3) with ESMTP id w4FI1S0v096721; Tue, 15 May 2018 11:01:28 -0700 (PDT) (envelope-from freebsd@pdx.rh.CN85.dnsmgr.net) Received: (from freebsd@localhost) by pdx.rh.CN85.dnsmgr.net (8.13.3/8.13.3/Submit) id w4FI1S4w096720; Tue, 15 May 2018 11:01:28 -0700 (PDT) (envelope-from freebsd) From: "Rodney W. Grimes" Message-Id: <201805151801.w4FI1S4w096720@pdx.rh.CN85.dnsmgr.net> Subject: Re: svn commit: r333494 - head/share/man/man7 In-Reply-To: To: Jonathan Looney Date: Tue, 15 May 2018 11:01:28 -0700 (PDT) CC: rgrimes@freebsd.org, araujo@freebsd.org, "Conrad E. Meyer" , src-committers , svn-src-all@freebsd.org, svn-src-head@freebsd.org Reply-To: rgrimes@freebsd.org X-Mailer: ELM [version 2.4ME+ PL121h (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 15 May 2018 18:01:33 -0000 > 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