Reordering the rc.conf manual page

[Giorgos Keramidas]

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?

> @@ -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.