From owner-freebsd-doc@FreeBSD.ORG Fri Aug 19 10:40:10 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 17E0F16A41F for ; Fri, 19 Aug 2005 10:40:10 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id C09F143D49 for ; Fri, 19 Aug 2005 10:40:09 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id j7JAe93c079226 for ; Fri, 19 Aug 2005 10:40:09 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7JAe90L079225; Fri, 19 Aug 2005 10:40:09 GMT (envelope-from gnats) Date: Fri, 19 Aug 2005 10:40:09 GMT Message-Id: <200508191040.j7JAe90L079225@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Fredrik Lindberg Cc: Subject: Re: docs/85097: [patch] devd.conf.5 lacks a lot of vital information. X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Fredrik Lindberg List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 19 Aug 2005 10:40:10 -0000 The following reply was made to PR docs/85097; it has been noted by GNATS. From: Fredrik Lindberg To: "Gary W. Swearingen" Cc: bug-followup@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 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