svn commit: r324457 - in head/sys/dev: pccbb pci

[Bruce Evans]

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