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

[Fredrik Lindberg]

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

From: Fredrik Lindberg <fli at shapeshifter.se>
To: "Gary W. Swearingen" <garys at opusnet.com>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital information.
Date: Fri, 19 Aug 2005 12:32:43 +0200

 Gary W. Swearingen wrote:
 > 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.
 
 This was unintentional, the "notify" statement were added to an
 original part of the manual where non-capital letters were used.
 In my opinion they should all begin with a captial 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.
 
 I took a quick look at some other manuals, .Ql seems to be used
 to quote single characters while .Dq is used to quote words.
 
 > 
 > 
 >>+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.
 
 You're probably right.
 
 > 
 > 
 >>+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"  ?
 
 Maybe even "executed" ?
 
 > "/" > " or "
 > "requires" > "require"
 > 
 > IIRC, two sentences should not share the same line.
 
 Inserting a hard break between those lines? even though they
 are so closely related?
 
 > 
 > 
 >>+.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 original manual used "substatements", I were about to change
 it to "sub-statements" but I never did it.
 
 > 
 > 
 >>+The following statements are supported within the 
 > 
 > 
 > OK, unless you forgot "sub".
 
 Well, a sub-statement is a statement and a statement can have 
 sub-statements :)
 But, you're right, it's probably better to use sub-statements for clarity.
 
 > 
 > 
 >>+.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.)
 
 I went over that sentence like a 100 times while writing, but since
 english isn't my native language I really can't say which to use.
 
 > 
 > 
 >>+.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'
 
 I confirmed this, devd(8) accepts " # foo" as a valid comment, so it's
 not relly a "shell construct" comment, more of a "shell construct"-like 
 comment.
 
 > 
 > 
 >> .Ed
 >>+.Sh EXAMPLES 
 >>+The file
 > 
 > 
 > Maybe "The installed" or "The distributed", because it might
 > not have the examples when the manpage is read.
 
 "The installed" sounds fine.
 
 > 
 > 
 >>+.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.
 Yes, moving the obvious examples to sample file would probably be a good
 idea, keeping only the statements that is in use in /etc/devd.conf
 
 
 I have addressed all of the above issues (proper quoting, choice
 of words, .Va's and so on), but I'll wait until all issues are cleared
 before posting a second patch.
 
 	Fredrik Lindberg