From owner-freebsd-doc@FreeBSD.ORG Thu Aug 18 23:50:18 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 835FC16A41F for ; Thu, 18 Aug 2005 23:50:18 +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 3909743D48 for ; Thu, 18 Aug 2005 23:50:18 +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 j7INoIK9092795 for ; Thu, 18 Aug 2005 23:50:18 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7INoINr092794; Thu, 18 Aug 2005 23:50:18 GMT (envelope-from gnats) Date: Thu, 18 Aug 2005 23:50:18 GMT Message-Id: <200508182350.j7INoINr092794@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: garys@opusnet.com (Gary W. Swearingen) 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: "Gary W. Swearingen" List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 18 Aug 2005 23:50:18 -0000 The following reply was made to PR docs/85097; it has been noted by GNATS. From: garys@opusnet.com (Gary W. Swearingen) To: Fredrik Lindberg Cc: bug-followup@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 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.