Date: Thu, 15 Sep 2005 19:18:29 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: Giorgos Keramidas <keramida@ceid.upatras.gr> Cc: Tom Rhodes <trhodes@FreeBSD.org>, FreeBSD-doc@FreeBSD.org Subject: Re: Reordering the rc.conf manual page Message-ID: <20050915191829.7a20a2a9@localhost> In-Reply-To: <20050915132925.GA1370@flame.pc> References: <20050915062312.73803494@localhost> <20050915132925.GA1370@flame.pc>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 15 Sep 2005 16:29:26 +0300 Giorgos Keramidas <keramida@ceid.upatras.gr> wrote: > On 2005-09-15 06:23, Tom Rhodes <trhodes@freebsd.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20050915191829.7a20a2a9>