From owner-freebsd-doc@FreeBSD.ORG Thu Sep 15 13:29:37 2005 Return-Path: X-Original-To: FreeBSD-doc@freebsd.org Delivered-To: FreeBSD-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 30DD016A41F; Thu, 15 Sep 2005 13:29:37 +0000 (GMT) (envelope-from keramida@ceid.upatras.gr) Received: from aiolos.otenet.gr (aiolos.otenet.gr [195.170.0.93]) by mx1.FreeBSD.org (Postfix) with ESMTP id 78A8843D46; Thu, 15 Sep 2005 13:29:35 +0000 (GMT) (envelope-from keramida@ceid.upatras.gr) Received: from flame.pc (aris.bedc.ondsl.gr [62.103.39.226]) by aiolos.otenet.gr (8.13.4/8.13.4/Debian-1) with SMTP id j8FDTXWU017552; Thu, 15 Sep 2005 16:29:34 +0300 Received: from flame.pc (flame [127.0.0.1]) by flame.pc (8.13.4/8.13.4) with ESMTP id j8FDTQdN001607; Thu, 15 Sep 2005 16:29:26 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Received: (from keramida@localhost) by flame.pc (8.13.4/8.13.4/Submit) id j8FDTQZC001606; Thu, 15 Sep 2005 16:29:26 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Date: Thu, 15 Sep 2005 16:29:26 +0300 From: Giorgos Keramidas To: Tom Rhodes Message-ID: <20050915132925.GA1370@flame.pc> References: <20050915062312.73803494@localhost> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20050915062312.73803494@localhost> Cc: FreeBSD-doc@freebsd.org Subject: Re: Reordering the rc.conf manual page X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 15 Sep 2005 13:29:37 -0000 On 2005-09-15 06:23, Tom Rhodes wrote: > Hi, > > I've done some simple reordering of our rc.conf.5 manual page. [...] The changes include both reordering and text additions (probably removals too, I haven't had a thorough look at the diff). Is it possible to make this two patches, one with only moving around of existing text and one with new/deleted text? > @@ -47,7 +49,7 @@ > directly. > Instead, it is included by the > various generic startup scripts in > -.Pa /etc > +.Pa /etc/rc.d Nice catch :) > which conditionalize their > internal actions according to the settings found there. > .Pp > @@ -71,7 +73,13 @@ > The following list provides a name and short description for each > variable that can be set in the > .Nm > -file: > +file, classified by section. > +When an configuration variable exists which may fit into > +two or more catagories, it will be listed with those which > +contain the most likeness. 'catagories' is a typo. We could probably improve a bit on the syntax of the last sentence too, because "most likeness" seems a bit awkward. How about... When a configuration variable can fit in two or more categories, it will be listed as part of the category that contains those variables which are most closely related to the specific variable (or the first group if all categories contain other variables, all equally related). or am I being too verbose? > +.El > +.Ss NETWORK SERVICES > +Configuration variables which control network services such > +as NFS are defined below: > +.Bl -tag -width indent-two I think "such as NFS" should be inside a pair of commas here. > +For each > +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n > +entry that is found, > +its contents are passed to > +.Xr ifconfig 8 . > +Execution stops at the first unsuccessful access, so if > +something like this is present: > +.Bd -literal > +ifconfig_ed0_alias0="inet 127.0.0.251 netmask 0xffffffff" > +ifconfig_ed0_alias1="inet 127.0.0.252 netmask 0xffffffff" > +ifconfig_ed0_alias2="inet 127.0.0.253 netmask 0xffffffff" > +ifconfig_ed0_alias4="inet 127.0.0.254 netmask 0xffffffff" > +.Ed > +.Pp > +Then note that alias4 would > +.Em not > +be added since the search would > +stop with the missing alias3 entry. "Then note that" looks a bit misplaced here. IMHO, it's also a bug to start the line with a capital letter when a displayed block is 'inlined' somewhere in the middle of a sentence. I'd probably like it a lot better if this was rewritten as: For each .Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n entry that is found, its contents are passed to .Xr ifconfig 8 . Execution stops at the first unsuccessful access, so if something like this is present: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.251 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.252 netmask 0xffffffff" ifconfig_ed0_alias2="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias4="inet 127.0.0.254 netmask 0xffffffff" .Ed .Pp then .Li alias4 would .Em not be added since the search would stop with the missing .Li alias3 entry. > +.\" XXX PERHAPS A DEVICES CATAGORY? Typo in 'CATAGORY'. > +The field separator to use for breaking down the list of startup > script files +into individual filenames. > +The default is a space. > +It is not necessary to change this unless there are startup scripts > with names +containing spaces. Is the strange wrapping a mailer issue here or are the '+' characters really out of place in your diff? > + > + > + > + > + > + These should go away. They are the cause of the empty line warnings. If it's absolutely necessary to leave vertical space in manpages, it's ok AFAIK to use empty groff requests: . . . . .Sh SECTION . .Nm is a utility that [...] . . . .Sh SECTION 2 > @@ -889,126 +1042,10 @@ > [...] > + > + > + > + Same here.