Date: Tue, 10 Oct 2017 15:32:37 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Alan Somers <asomers@freebsd.org> 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 Message-ID: <20171010142321.Q1134@besplex.bde.org> In-Reply-To: <201710092227.v99MRcFV016141@repo.freebsd.org> References: <201710092227.v99MRcFV016141@repo.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20171010142321.Q1134>