Date: Fri, 4 Jul 2003 17:17:49 +0300 From: Ruslan Ermilov <ru@freebsd.org> To: Joseph Koshy <jkoshy@freebsd.org> Cc: doc@freebsd.org Subject: Re: [review request] New config.5 manual page Message-ID: <20030704141749.GB90405@sunbay.com> In-Reply-To: <20030704084540.104CA37B401@hub.freebsd.org> References: <20030704084540.104CA37B401@hub.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--ZoaI/ZTpAVc4A5k6
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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 h=
as=20
> diverged from the syntax understood by the original 4.4BSD config(8) prog=
ram,
> 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 r=
u Exp=20
> $
> .\"
Wrong cut-n-paste.
> .Dd June 03, 2003
"June 3", no leading zeroes in dates please.
> .Sh LEXICAL STRUCTURE
>=20
Please make these subsections, like this:
=2ESs 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
=2ETn 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
=2EIc 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 ).
=2EXr device.hints ) .
> .Ar filename.
^ missing space
> .Ar filename
The
=2EAr 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
=2EIt 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
=2EAr options
argument
> is a comma separated list of one or more option
> specifications.
> Each option specification has the form
> .D1 Ar MakeVariableName Op =3D Ar Value
While speces around `=3D' may actually work, we don't use them.
Please add the necessary .Ns'es.
> Example:
> .Bd -unfilled -offset indent -compact
> .Li makeoptions MYOPTION =3D \*qfoobar\*q
> .Li makeoptions MYNULLOPTION
> .Ed
Er,
=2EBd -literal -offset indent
makeoptions MYOPTION=3D"foobar"
makeoptions MYNULLOPTION
=2EEd
> .\" -------- 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,
--=20
Ruslan Ermilov Sysadmin and DBA,
ru@sunbay.com Sunbay Software Ltd,
ru@FreeBSD.org FreeBSD committer
--ZoaI/ZTpAVc4A5k6
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (FreeBSD)
iD8DBQE/BYyNUkv4P6juNwoRAptLAJ9qvrjL99yB826j1KsvVrjjmBOjvwCfS3xN
/5SsfSzHRxiCAd4Ul8+UAZU=
=AnF/
-----END PGP SIGNATURE-----
--ZoaI/ZTpAVc4A5k6--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030704141749.GB90405>