From owner-svn-src-head@freebsd.org Tue Oct 10 04:32:42 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 59147E484FB; Tue, 10 Oct 2017 04:32:42 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail106.syd.optusnet.com.au (mail106.syd.optusnet.com.au [211.29.132.42]) by mx1.freebsd.org (Postfix) with ESMTP id E1FC86AC8B; Tue, 10 Oct 2017 04:32:41 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from [192.168.0.102] (c110-21-101-228.carlnfd1.nsw.optusnet.com.au [110.21.101.228]) by mail106.syd.optusnet.com.au (Postfix) with ESMTPS id 8B2C93C36B3; Tue, 10 Oct 2017 15:32:38 +1100 (AEDT) Date: Tue, 10 Oct 2017 15:32:37 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Alan Somers cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r324457 - in head/sys/dev: pccbb pci In-Reply-To: <201710092227.v99MRcFV016141@repo.freebsd.org> Message-ID: <20171010142321.Q1134@besplex.bde.org> References: <201710092227.v99MRcFV016141@repo.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.2 cv=LI0WeNe9 c=1 sm=1 tr=0 a=PalzARQSbocsUSjMRkwAPg==:117 a=PalzARQSbocsUSjMRkwAPg==:17 a=kj9zAlcOel0A:10 a=Iau21ub-UXeGsUTFskIA:9 a=pNLrUVhz5m34pnmG:21 a=gw8T9opGQSYv2c5R:21 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 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, 10 Oct 2017 04:32:42 -0000 On Mon, 9 Oct 2017, Alan Somers wrote: > Log: > Remove embedded newlines from sysctl variable descriptions This doesn't fix the main bug of writing man pages in sysctl descriptions. > Modified: head/sys/dev/pccbb/pccbb_isa.c > ============================================================================== > --- head/sys/dev/pccbb/pccbb_isa.c Mon Oct 9 22:19:58 2017 (r324456) > +++ head/sys/dev/pccbb/pccbb_isa.c Mon Oct 9 22:27:38 2017 (r324457) > @@ -75,11 +75,11 @@ static SYSCTL_NODE(_hw, OID_AUTO, pcic, CTLFLAG_RD, 0, > > static int isa_intr_mask = EXCA_INT_MASK_ALLOWED; > SYSCTL_INT(_hw_pcic, OID_AUTO, intr_mask, CTLFLAG_RDTUN, &isa_intr_mask, 0, > - "Mask of allowable interrupts for this laptop. The default is generally\n\ > -correct, but some laptops do not route all the IRQ pins to the bridge to\n\ > -save wires. Sometimes you need a more restrictive mask because some of the\n\ > -hardware in your laptop may not have a driver so its IRQ might not be\n\ > -allocated."); > + "Mask of allowable interrupts for this laptop. The default is generally" > + " correct, but some laptops do not route all the IRQ pins to the bridge to" > + " save wires. Sometimes you need a more restrictive mask because some of" > + " the hardware in your laptop may not have a driver so its IRQ might not be" > + " allocated."); More low quality sysctl messages can be found using sysctl -da | grep -v ': ' # Sloppy check for embedded newlines sysctl -da | grep '^[^ ]*: [^A-Z]' # Uncapitalized messages previous | grep '^dev.*%'' # Auto-generated spam for dev tree sysctl -da | grep '[^.]*\.$' # Terminating period sysctl -da | grep '^[^ ]*: .*\..*\.$' # Multiple sentence, term. period sysctl -da | grep '^[^ ]*: .*\..*[^.]$' # Period, but not terminating sysctl -da | grep '\. ' # Normal sentence break sysctl -da | grep '\. [^.]' # Misformatted sentence break sysctl -da | grep '......' # (Really 80 dots). Long lines Results on freefall: - 3294 lines of output - 7 lines with embedded newlines - 1041 lines with uncapitalized messages - 637 lines with previous bug auto-generated for dev tree. Approx 5 lines duplicated for each device - 109 lines with a terminating period but no other periods - 5 lines with multiple sentences and a terminating period - 43 lines with a period but not a terminating period. This is a sloppy check for multiple sentences. It finds a few correct descriptions with periods in sysctl names - 7 lines with normal sentence breaks. Half for man pages in sysctls in this commit - 17 lines with single-space sentence breaks - 359 long lines. Not counting the sysctl name or ': ', only 30 lines are too long. These lines and ones up to about 10 shorter are also too long for source lines. Another type of search finds inconsistent spellings of booleans. grep -i for literal "disable" shows 63 lines with the following inconsistencies and verboseness: - often "disable" in the description echoes "disable" in the sysctl name. But sometimes the sysctl uses "control", or the sysctl name uses "disable" but the description uses "disallow" - when the description uses "Enable/disable" (10 instances), the name uses "allow" (2 instances), "use" (1 instance), "enable "(1 instance) or is not clearly boolean (6 instances), - often (in usb cloned descriptions), "Disable is spelled verbosely as "Set to disable". This is still not verbose enough to say that unset means "enable" or even "don't disable". Disable/enable is never used. For integer variables, there are lots of inconsistences and verboseness involving "number/number of/num/n". Bruce