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
_______________________________________________
svn-src-head@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
