Reordering the rc.conf manual page

[Tom Rhodes]

On Thu, 15 Sep 2005 16:29:26 +0300
Giorgos Keramidas <keramida at ceid.upatras.gr> wrote:

> On 2005-09-15 06:23, Tom Rhodes <trhodes at 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