docs/85097: [patch] devd.conf.5 lacks a lot of vital information.

[Gary W. Swearingen]

The following reply was made to PR docs/85097; it has been noted by GNATS.

From: garys at opusnet.com (Gary W. Swearingen)
To: Fredrik Lindberg <fli+freebsd at shapeshifter.se>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital
 information.
Date: Thu, 18 Aug 2005 16:48:17 -0700

 Fredrik Lindberg <fli+freebsd at shapeshifter.se> writes:
 
 > +.It Ic notify
 > +specifies various matching criteria and actions to perform when the kernel
 > +sends an event notification to user land.
 
 Your other item descriptions begin with a capital letter.
 
 My grep of 5.4 manpages found no "user land" and many "userland".
 
 >  .Pp
 > +Each statement, except 
 > +.Ql options
 
 Some fonts don't show a single "`" well and .Dq seems to be more
 popular (and I don't like either one).  That is, it's OK.
 
 > +has a priority (arbitrary number) associated with it, where
 
 "an arbitrary number"
 
 > +0 is defined as the lowest priority.
 
 I would quote "0"; can't say why.
 
 > +If two statements matches the same event, only the action of the statement with
 > +highest priority will be carried out. In this way generic statements can be
 > +overridden for devices/notifications that requires special attention. 
 
 "matches" > "match"
 "carried out" > "used"  ?
 "/" > " or "
 "requires" > "require"
 
 IIRC, two sentences should not share the same line.
 
 > +.Pp
 > +The general syntax to create a statement is as follows
 
 "to create" > "of"
 " as follows" > ":"  ?
 
 > +.Pp
 > +.Bd -literal
 > +statement priority {
 > +	substatement "value"; 
 > +	...
 > +	substatement "value"; 
 
 Me and "aspell" say: "substatement" > "sub-statement", but maybe it's
 OK as psuedo-code.
 
 > +.Pp
 
 Unneeded.
 
 > +.Ss Substatements
 
 "Sub-statements" ?
 
 > +The following statements are supported within the 
 
 OK, unless you forgot "sub".
 
 > +.Ql options
 > +statement.
 > +.Bl -tag -width ".Ic directory"
 > +.It Ic directory \*q/some/path\*q; 
 > +Adds the given directory to the list of directories from which devd will read
 
 .Xr devd 8
 
 > +configuration files. Any number of this directive is valid.
 
 I'm fairly sure it should "these directives", but "is" is correct.
 (I see that it's problematic, though.)
 
 > +.It Ic pid-file \*q/var/run/devd.pid\*q;
 > +Specifies pid file.
 > +.It Ic set regexp-name \*q(some|regexp)\*q;
 > +Creates a regular expression and assigns it to the variable
 > +regexp-name, this variable is then avaiable through out the rest of 
 
 "," > ";"
 
 Probably should use: .Va regexp-name ;
 
 "through out" > "throughout"
 
 > +the configuration file.
 > +All regular expressions have an implicit ^$ around them.
 
 Use .Li or .Dq Li or .Ql Li ?
 
 > +Actually a shorthand to `match device-name'. Matches a device named string.
 
 I see nothing wrong with in-line quoting, but I wonder if other would.
 
 > +The variable $device-name is avaiable for later use with the action-statement.
 
 Probably: .Va $device-name
 
 It seems that "$" is not special char so doesn't need leading "\&".
 
 > +.It Ic match \*qvariable\*q \*qvalue\*q;
 > +Matches the content of value against variable. value can be a regular expression.
 
 .Va value
 .Va variable
 
 (I just checked; .Va underlines in my term.  .It does nothing noticable.)
 
 > +Matches the content of value against variable. value can be a regular expression.
 
 .Va's
 
 > +The variable
 > +.Ql $notify
 
 .Va $notify
 
 > +is avaiable inside this statement and contains, possibly, a value depending
 > +on which system and subsystem that delivered the event. 
 
 "value depending" > "value, depending"
 
 I would remove ",possibly, " as redundent with "depending".
 
 > +Any number of match-statements can exists within a notify-statement.
 
 I think "-" should be " " here and one similar place.
 
 > +Below is a list of avaiable systems, subsystems and types.
 
 I'm happy to say we have a standard on this: " and" > ", and".
 
 > +Command to execute upon a successful match. For example 
 > +/etc/rc.d/power_profile $notify
 
 I'd use ".Ic ..." even if it's not interactive. Bold on my term.
 
 > +.Ss Variables that can be used with the match-statement
 > +Partial list of variables and their possible values that can be used together
 
 "A partial"
 
 > +Partial list of systems, subsystems and types used within the
 
 Another comma.
 
 > +Subsystem is the actual name of the network interface on which the event 
 
 IMO, "Subsystem" needs special treatment beyond ".Li", probably quotes.
 
 >  Comments may appear anywhere that whitespace may appear in a
 >  configuration file.
 
 I'll take the original manpage's word for it, but if it's really
 a "shell construct" comment, then it can't appear at the beginning
 of some whitespaces. For example try this with and without a
 space before "#": sh -c 'aaa=bbb#ccc echo ddd$aaa'
 
 >  .Ed
 > +.Sh EXAMPLES 
 > +The file
 
 Maybe "The installed" or "The distributed", because it might
 not have the examples when the manpage is read.
 
 > +.Pa /etc/devd.conf
 > +contains numerous of different examples.
 
 "has many examples."
 
 I wonder if that busy file doesn't belong in some "sample" directory.