[review request] New config.5 manual page

[Ruslan Ermilov]

On Fri, Jul 04, 2003 at 01:45:40AM -0700, Joseph Koshy wrote:
> The attached manual page documents the syntax for the kernel configuration
> files as understood by the config(8) program in 5-CURRENT.  This syntax has 
> diverged from the syntax understood by the original 4.4BSD config(8) program,
> and it is perhaps time for a new manual page.

> .\" Copyright (c) 2003	Joseph Koshy
                        ^ that should be a space

> .\" $FreeBSD: src/share/man/man5/quota.user.5,v 1.3 2002/12/12 17:25:57 ru Exp 
> $
> .\"

Wrong cut-n-paste.

> .Dd June 03, 2003

"June 3", no leading zeroes in dates please.

> .Sh LEXICAL STRUCTURE
> 
Please make these subsections, like this:

.Ss Lexical Structure

> Case is significant,
> .Ql machine

".Dq Li" is more appropriate here.  I usually use .Ql only
for short (one-two character sequences).

> and
> .Ql MACHINE

Ditto.

> are different tokens.
> .Pp
> A double quote character
> .Ql \&\*q

Please use \(dq to represent the double quote.  And no \& is
necessary here.

> Number are specified using

Number_s_

> .Li C Ns No -style

.Tn C Ns -style

> .Sh CONFIGURATION DIRECTIVES

"Subsection" it please.

> .Bl -tag -width "makeoptions"

The width should either be exact like ".Cm makeoptions ..."
or be a simple "indent".

> .\" -------- CPU --------
> .It Cm cpu Ar cputype
> Specify the CPU this kernel will run on.

The appropriate markup for iternal config(8) directives would
be the .Ic macro, not .Cm.

> There can be more than one
> .Li cpu

.Ic cpu

> directives in a configuration file.
> The allowed list of cpu names is architecture specific and is
                      CPU (acronyms are all uppercase)

> defined in the file
> .Pa "sys/conf/options." Ns Ar arch .
      ^                 ^

Excessive quotes.

> .\" -------- DEVICE --------

Are these comments really necessary?

> .It Cm device Ar name Op count
                           ^ "Ar" is missing

> (see
> .Xr device.hints 5 Ns ).

.Xr device.hints ) .

> .Ar filename.
              ^ missing space

> .Ar filename

The
.Ar filename
argument

please, we want this look like a real sentence.

> must conform to
                 ^ "the" is missing

> .Xr device.hints 5
> syntax.

> .\" -------- MACHINE --------
> .It Cm machine Ar arch
> Specifies the architecture of the machine the kernel is being
> compiled for.
> Legal values for
> .Ar arch
> include:
> .Bl -hang -compact

Normal -tag list please.

> .It alpha

.It Cm alpha

would be appropriate.

> .It pc98
> The pc96 architecture.
         ^ oops

> .It powerpc
> The IBM PowerPC architecture.

Was it Apple?  ;)

> .It sparc64
> The Sparc64 architecture.

The Sun Sparc64, to be consistent.

"IBM PC" for i386 is also bogus.

> .El
> .Pp
> At least one machine architecture must be specified.

Er, "exactly one" must be specified.

> .\" -------- MAKEOPTION --------
> .It Cm makeoptions Ar options
> Add
> .Ar options
> to the generated makefile.
> .Pp

> .Ar options

The
.Ar options
argument

> is a comma separated list of one or more option
> specifications.
> Each option specification has the form
> .D1 Ar MakeVariableName Op = Ar Value

While speces around `=' may actually work, we don't use them.
Please add the necessary .Ns'es.

> Example:
> .Bd -unfilled -offset indent -compact
> .Li makeoptions MYOPTION = \*qfoobar\*q
> .Li makeoptions MYNULLOPTION
> .Ed

Er,

.Bd -literal -offset indent
makeoptions MYOPTION="foobar"
makeoptions MYNULLOPTION
.Ed

> .\" -------- NOMAKEOPTION --------
> .It Cm nomakeoption Ar name
> Removes previously defined
> .Xr make 1
> option
> .Ar name
> from the kernel build.

I would add: "Useful with the .include directive."

> .\" -------- NOOPTION --------
> .It Cm nooption Ar kerneloptionname
> Remove kernel option
> .Ar kerneloptionname
> from the list of previously defined options.

Same here.

> .\" -------- OPTIONS --------
> .It Cm options Ar optionspecs
> Add compile time kernel options to the kernel build.

> .Ar optionspecs

I haven't looked beyond that point, please apply the same
fixes below, and resubmit your patch.


Cheers,
-- 
Ruslan Ermilov		Sysadmin and DBA,
ru at sunbay.com		Sunbay Software Ltd,
ru at FreeBSD.org		FreeBSD committer
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20030704/67df2ad5/attachment.sig>