Module Name: src
Committed By: uwe
Date: Fri Jul 31 21:25:34 UTC 2020
Modified Files:
src/usr.bin/config: config.5
Log Message:
Minor tweak to list formatting.
Where necessary, use .Bl -ohang -compact and explicit .Pp to be able
to group multiple config directives (separate .It) by omitting .Pp
between them.
While here, add a .|" comment before .It to make them more visible
when editing.
To generate a diff of this commit:
cvs rdiff -u -r1.39 -r1.40 src/usr.bin/config/config.5
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/config/config.5
diff -u src/usr.bin/config/config.5:1.39 src/usr.bin/config/config.5:1.40
--- src/usr.bin/config/config.5:1.39 Fri Jul 31 20:01:42 2020
+++ src/usr.bin/config/config.5 Fri Jul 31 21:25:34 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: config.5,v 1.39 2020/07/31 20:01:42 uwe Exp $
+.\" $NetBSD: config.5,v 1.40 2020/07/31 21:25:34 uwe Exp $
.\"
.\" Copyright (c) 2006, 2007 The NetBSD Foundation.
.\" All rights reserved.
@@ -249,7 +249,9 @@ to combine options and attributes .
.\"
.Ss CONTEXT NEUTRAL STATEMENTS
.\"
-.Bl -ohang
+.Bl -ohang -compact
+.\"
+.Pp
.It Ic version Ar yyyymmdd
Indicates the syntax version used by the rest of the file, or until the next
.Ic version
@@ -258,11 +260,15 @@ The argument is an ISO date.
A given
.Xr config 1
binary might only be compatible with a limited range of version numbers.
+.\"
+.Pp
.It Ic include Ar path
Includes a file.
The path is relative to the top of the kernel source tree, or the inner-most
defined
.Ic prefix .
+.\"
+.Pp
.It Ic cinclude Ar path
Conditionally includes a file.
Contrary to
@@ -270,6 +276,8 @@ Contrary to
it will not produce an error if the file does not exist.
The argument obeys the same rules as for
.Ic include .
+.\"
+.Pp
.It Ic prefix Op Ar path
If
.Ar path
@@ -286,6 +294,8 @@ The
.Ar path
argument is either absolute or relative to the current defined prefix, which
defaults to the top of the kernel source tree.
+.\"
+.Pp
.It Ic buildprefix Op Ar path
If
.Ar path
@@ -299,8 +309,11 @@ The
.Ar path
argument is relative to the current defined buildprefix, which
defaults to the top of the kernel build directory.
-When prefix is either absolute or relative out of the kernel source tree (../),
+When prefix is either absolute or relative out of the kernel source tree
+.Pq Pa \&../ ,
buildprefix must be defined.
+.\"
+.Pp
.It Ic ifdef Ar attribute
.It Ic ifndef Ar attribute
.It Ic elifdef Ar attribute
@@ -325,6 +338,7 @@ and
.Ic prefix ,
the preamble may contain the following optional statements:
.Bl -ohang
+.\"
.It Ic build Ar path
Defines the build directory for the compilation of the kernel.
It replaces the default of
@@ -333,6 +347,7 @@ and is superseded by the
.Fl b
parameter of
.Xr config 1 .
+.\"
.It Ic source Ar path
Defines the directory in which the source of the kernel lives.
It replaces the default of
@@ -352,7 +367,10 @@ However, third parties may provide sourc
and the logic that binds them to the
.Nx
kernel will have to be added to the user-edited configuration file.
-.Bl -ohang
+.Pp
+.Bl -ohang -compact
+.\"
+.Pp
.It Ic devclass Ar class
Defines a special attribute, named
.Em device class .
@@ -361,6 +379,8 @@ A given device cannot belong to more tha
translates that property by the rule that a device cannot depend on more than
one device class, and will properly fill the configuration information file it
generates according to that value.
+.\"
+.Pp
.It Ic defflag Oo Ar file Oc Ar option Oo Ar option Oo Ar ... Oc Oc \
Op : Ar dependencies
Defines a boolean option, that can either be selected or be un-selected by the
@@ -379,6 +399,8 @@ option, it will be empty.
Several options can be combined in one header file, for convenience.
The header file is created in the compilation directory, making them directly
accessible by source files.
+.\"
+.Pp
.It Ic defparam Oo Ar file Oc Ar option Oo = Ar value Oc \
Oo := Ar lint-value Oc Oo Ar option Oo Ar ... Oc Oc Op : Ar dependencies
Behaves like
@@ -397,6 +419,8 @@ is specified,
will use it as a value when generating a lint configuration with
.Fl L ,
and ignore it in all other cases.
+.\"
+.Pp
.It Ic deffs Ar name Op Ar name Op Ar ...
Defines a file-system name.
It is no more than a regular option, as defined by
@@ -407,6 +431,8 @@ file-systems to be compiled in the kerne
statement instead of the
.Ic options
statement.
+.\"
+.Pp
.It Ic obsolete defflag Oo Ar file Oc Ar option Op Ar option Op Ar ...
.It Ic obsolete defparam Oo Ar file Oc Ar option Op Ar option Op Ar ...
Those two statements are identical and mark the listed option names as
@@ -418,6 +444,8 @@ will emit a warning and ignore the optio
The optional
.Ar file
argument should match the original definition of the option.
+.\"
+.Pp
.It Ic define Ar attribute Oo Bro Ar locators Brc Oc Oo : Ar dependencies Oc
Defines an
.Ar attribute .
@@ -428,12 +456,16 @@ If the pair of brackets are present, the
declared attribute becomes an
.Em interface attribute ,
on which devices can attach.
+.\"
+.Pp
.It Ic maxpartitions Ar number
Defines the maximum number of partitions the disklabels for the considered
architecture can hold.
This statement cannot be repeated and should only appear in the
.Pa std\&.$\&{ARCH\&}
file.
+.\"
+.Pp
.It Ic maxusers Ar min default max
Indicates the range of values that will later be accepted by
.Xr config 1
@@ -445,6 +477,8 @@ In case the user doesn't include a
statement in the configuration file, the value
.Ar default
is used instead.
+.\"
+.Pp
.It Ic device Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc
Declares a device of name
.Ar base .
@@ -465,6 +499,8 @@ statement to
However, it is the responsibility of the developer to add the relevant
.Fn CFATTACH_DECL_NEW
line to the source of the device's driver.
+.\"
+.Pp
.It Ic attach Ar base Ic at Ar attr Oo , Ar attr Oo , Ar ... Oc Oc Oo Ic with \
Ar name Oc Oo : dependencies Oc
All devices must have at least one declared attachment.
@@ -493,10 +529,14 @@ It is then possible to use the associate
as a conditional element in a
.Ic file
statement.
+.\"
+.Pp
.It Ic defpseudo Ar base Oo : dependencies Oc
Declares a pseudo-device.
Those devices don't need an attachment to be declared, they will always be
attached if they were selected by the user.
+.\"
+.Pp
.It Ic defpseudodev Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc
Declares a pseudo-device.
Those devices don't need an attachment to be declared, they will always be
@@ -512,6 +552,8 @@ allowing the pseudo-device to have child
Interface attributes can also be defined in the
.Ar dependencies
list.
+.\"
+.Pp
.It Ic file Ar path Oo Ar condition Oc Oo Ic needs-count Oc \
Oo Ic needs-flag Oc Op Ic compile with Ar rule
Adds a source file to the list of files to be compiled into the kernel, if the
@@ -571,6 +613,8 @@ architecture.
The path is relative to the top of the kernel source tree, or the inner-most
defined
.Ic prefix .
+.\"
+.Pp
.It Ic object Ar path Op Ar condition
Adds an object file to the list of objects to be linked into the kernel, if the
.Ar conditions
@@ -580,6 +624,8 @@ This is most useful for third parties pr
The path is relative to the top of the kernel source tree, or the inner-most
defined
.Ic prefix .
+.\"
+.Pp
.It Ic device-major Ar base Oo Ic char Ar number Oc Oo Ic block Ar number Oc \
Op Ar condition
Associates a major device number with the device
@@ -599,6 +645,7 @@ statement.
.Ss OPTIONS SELECTION
.\"
.Bl -ohang
+.\"
.It Ic machine Ar machine Op Ar arch Op Ar subarch Op Ar ...
The
.Ic machine
@@ -625,6 +672,7 @@ the
.Ar arch
and each of the
.Ar subarch .
+.\"
.It Ic package Ar path
Simpler version of:
.Bd -literal -offset indent
@@ -632,12 +680,15 @@ prefix PATH
include FILE
prefix
.Ed
+.\"
.It Ic ident Ar string
Defines the identification string of the kernel.
This statement is optional, and the name of the main configuration file will be
used as a default value.
+.\"
.It Ic no ident
Deletes any pre-existing identification string of the kernel.
+.\"
.It Ic maxusers Ar number
Despite its name, this statement does not limit the maximum number of users on
the system.
@@ -648,6 +699,7 @@ users, and the
parameter is used for example to compute the maximum number of opened files,
and the maximum number of processes, which itself is used to adjust a few
other parameters.
+.\"
.It Ic options Ar name Oo = Ar value Oc Op , Ar name Oo = Ar \
value Oc , Ar ...
Selects the option
@@ -667,16 +719,20 @@ If the option has previously been select
warning, and the new
.Ic options
statement replaces the original.
+.\"
.It Ic no options Ar name Op , Ar name Op , Ar ...
Un-selects the option
.Ar name .
If option
.Ar name
has not previously been selected, the statement produces a warning.
+.\"
.It Ic file-system Ar name Op , Ar name Op , Ar ...
Adds support for all the listed file-systems.
+.\"
.It Ic no file-system Ar name Op , Ar name Op , Ar ...
Removes support for all the listed file-systems.
+.\"
.It Ic config Ar name Ic root on Ar device Oo Ic type Ar fs Oc Op Ic dumps on \
Ar device
Adds
@@ -703,10 +759,12 @@ specifies a named disk wedge.
At least one
.Ic config
statement must appear in the configuration file.
+.\"
.It Ic no config Ar name
Removes
.Ar name
from the list of kernel binaries to compile from the configuration file.
+.\"
.It Ar instance Ic at Ar attachment Op Ar locator specification
Configures an instance of a device attaching at a specific location in the
device tree.
@@ -719,6 +777,7 @@ and a
for
.Ar attachment
and the locators.
+.\"
.It Ic no Ar instance Op Ic at Ar attachment
Removes the previously configured instances of a device that exactly match the
given specification.
@@ -731,6 +790,7 @@ If
.Ar instance
is a bare device name, all the previously defined instances of that device,
regardless of the numbers or wildcard, are removed.
+.\"
.It Ic no device at Ar attachment
Removes all previously configured instances that attach to the specified
attachment.
@@ -741,6 +801,7 @@ ends with a
all instances attaching to all the variants of
.Ar attachment
are removed.
+.\"
.It Ic pseudo-device Ar device Op Ar number
Adds support for the specified pseudo-device.
The parameter
@@ -748,8 +809,10 @@ The parameter
is passed to the initialisation function of the pseudo-device, usually to
indicate how many instances should be created.
It defaults to 1, and some pseudo-devices ignore that parameter.
+.\"
.It Ic no pseudo-device Ar name
Removes support for the specified pseudo-device.
+.\"
.It Ic makeoptions Ar name Ns = Ns Ar value Op , Ar name Ns += Ns Ar value \
Op , Ar ...
Adds or appends to a definition in the generated
@@ -763,15 +826,19 @@ is defined with
the
.Ar value
is defined as an option too.
+.\"
.It Ic makeoptions Ar condition name Ns += Ns Ar value Op , Ar condition \
name Ns += Ns Ar value
Appends to a definition in the generated
.Pa Makefile .
+.\"
.It Ic no makeoptions Ar name Op , Ar name Op , Ar ...
Removes one or more definitions from the generated
.Pa Makefile .
+.\"
.It Ic select Ar name
Adds the specified attribute and its dependencies.
+.\"
.It Ic no select Ar name
Removes the specified attribute and all the attributes which depend on it.
.El
