From owner-freebsd-doc@FreeBSD.ORG Thu Sep 15 23:19:34 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 494DD16A41F; Thu, 15 Sep 2005 23:19:34 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id C8FB043D45; Thu, 15 Sep 2005 23:19:33 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from localhost (net-ix.gw.ai.net [205.134.160.6] (may be forged)) (authenticated bits=0) by pittgoth.com (8.13.3/8.13.3) with ESMTP id j8FNJSoo036323 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Thu, 15 Sep 2005 19:19:29 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Thu, 15 Sep 2005 19:18:29 -0400 From: Tom Rhodes To: Giorgos Keramidas Message-ID: <20050915191829.7a20a2a9@localhost> In-Reply-To: <20050915132925.GA1370@flame.pc> References: <20050915062312.73803494@localhost> <20050915132925.GA1370@flame.pc> X-Mailer: Sylpheed-Claws 1.9.13 (GTK+ 2.6.8; i386-portbld-freebsd7.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: Tom Rhodes , 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 23:19:34 -0000 On Thu, 15 Sep 2005 16:29:26 +0300 Giorgos Keramidas wrote: > 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? Actually, I did absolutely nothing to the original text other than add to it. I agree, moving it around and adding new text should be separate commits. Will handle. This is just a "proof of concept" patch which was only to arouse interest. > > > @@ -47,7 +49,7 @@ > > directly. > > Instead, it is included by the > > various generic startup scripts in > > -.Pa /etc > > +.Pa /etc/rc.d > > Nice catch :) Thanks! :) > > > 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... Again, this is just a sample. No spell checking, I was really tired when I was doing this, and wanted opinions; however, ... > > 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). Sounds good, but I'd like to cut the ()'s out. > > or am I being too verbose? Perhaps, not sure honestly. > > > +.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. Again, perhaps. This patch will be much different when I actually commit it. > > > +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: Original text, though. This manual page is so big that, well, I guess the only way to get much review/cleanup is to submit a patch so others can look at the wording around it. :) > > 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? Probably a stupid mailing issue. It doesn't save my settings for some odd reason. I've been too busy lately and lack time enough for simple, stupid issues. > > > + > > + > > + > > + > > + > > + > > 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: That was only a separator in my work. I know it causes the warnings, I know it needs removed before commit. :) > > . > . > . > . > .Sh SECTION > . > .Nm > is a utility that [...] > . > . > . > .Sh SECTION 2 > > > > @@ -889,126 +1042,10 @@ > > [...] > > + > > + > > + > > + > > Same here. What do you think about the idea of what I'm doing though? :) -- Tom Rhodes