Reordering the rc.conf manual page
Tom Rhodes
trhodes at FreeBSD.org
Thu Sep 15 23:19:34 UTC 2005
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
More information about the freebsd-doc
mailing list