Module Name: src
Committed By: uwe
Date: Fri Jul 31 23:30:23 UTC 2020
Modified Files:
src/usr.bin/config: config.5
Log Message:
Formatting improvements.
To generate a diff of this commit:
cvs rdiff -u -r1.40 -r1.41 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.40 src/usr.bin/config/config.5:1.41
--- src/usr.bin/config/config.5:1.40 Fri Jul 31 21:25:34 2020
+++ src/usr.bin/config/config.5 Fri Jul 31 23:30:23 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: config.5,v 1.40 2020/07/31 21:25:34 uwe Exp $
+.\" $NetBSD: config.5,v 1.41 2020/07/31 23:30:23 uwe Exp $
.\"
.\" Copyright (c) 2006, 2007 The NetBSD Foundation.
.\" All rights reserved.
@@ -342,7 +342,7 @@ the preamble may contain the following o
.It Ic build Ar path
Defines the build directory for the compilation of the kernel.
It replaces the default of
-.Pa ../compile/<config-file>
+.Pa ../compile/ Ns Aq Ar config-file
and is superseded by the
.Fl b
parameter of
@@ -381,10 +381,14 @@ one device class, and will properly fill
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
-user with the
+.It Ic defflag \
+ Oo Ar file Oc \
+ Ar option \
+ Oo Ar option Oo Ar ... Oc Oc \
+ Op Ic \&: Ar dependencies
+Defines a boolean
+.Ar option ,
+that can either be selected or be un-selected by the user with the
.Ic options
statement.
The optional
@@ -392,7 +396,7 @@ The optional
argument names a header file that will contain the C pre-processor definition
for the option.
If no file name is given, it will default to
-.Ar opt_<option>.h .
+.Li opt_ Ns Ao Ar option Ac Ns Li \&.h .
.Xr config 1
will always create the header file, but if the user choose not to select the
option, it will be empty.
@@ -401,8 +405,12 @@ The header file is created in the compil
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
+.It Ic defparam \
+ Oo Ar file Oc \
+ Ar option Ns Oo Ns Ic = Ns Ar value\^ Oc \
+ Oo Ns Ic \&:= Ns Ar lint-value Oc \
+ Oo Ar option Oo Ar ... Oc Oc \
+ Op Ic \&:\~ Ns Ar dependencies
Behaves like
.Ic defflag ,
except the defined option must have a value.
@@ -421,8 +429,9 @@ will use it as a value when generating a
and ignore it in all other cases.
.\"
.Pp
-.It Ic deffs Ar name Op Ar name Op Ar ...
-Defines a file-system name.
+.It Ic deffs Ar name ...
+Defines a file-system
+.Ar name .
It is no more than a regular option, as defined by
.Ic defflag ,
but it allows the user to select the
@@ -433,8 +442,12 @@ statement instead of the
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 ...
+.It Ic obsolete defflag \
+ Oo Ar file Oc \
+ Ar option ...
+.It Ic obsolete defparam \
+ Oo Ar file Oc \
+ Ar option ...
Those two statements are identical and mark the listed option names as
obsolete.
If the user selects one of the listed options in the kernel configuration
@@ -446,13 +459,16 @@ The optional
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
+.It Ic define \
+ Ar attribute \
+ Oo Ic \&{ Ar locators Ic \&} Oc \
+ Op Ic \&: Ar dependencies
Defines an
.Ar attribute .
The
.Ar locators
list is optional, and can be empty.
-If the pair of brackets are present, the locator list is defined and the
+If the pair of braces are present, the locator list is defined and the
declared attribute becomes an
.Em interface attribute ,
on which devices can attach.
@@ -462,7 +478,7 @@ on which devices can attach.
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\&}
+.Pa "std.${ARCH}"
file.
.\"
.Pp
@@ -479,7 +495,10 @@ statement in the configuration file, the
is used instead.
.\"
.Pp
-.It Ic device Ar base Oo Bro Ar locators Brc Oc Oo : dependencies Oc
+.It Ic device \
+ Ar base \
+ Oo Ic \&{ Ar locators Ic \&} Oc \
+ Op Ic \&: Ar dependencies
Declares a device of name
.Ar base .
The optional list of
@@ -489,7 +508,7 @@ directly to it.
Internally, that means
.Ar base
becomes an
-.Ar interface attribute .
+.Em interface attribute .
For every device the user selects,
.Xr config 1
will add the matching
@@ -501,17 +520,20 @@ However, it is the responsibility of the
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
+.It Ic attach \
+ Ar base \
+ Ic at Ar attr\^ \
+ Ns Oo Ic \&, Ar attr\^ \
+ Ns Oo Ic \&, Ar ... Oc Oc \
+ Oo Ic with Ar name Oc \
+ Op Ic \&: dependencies
All devices must have at least one declared attachment.
Otherwise, they will never be found in the
.Xr autoconf 9
process.
The attributes on which an instance of device
.Ar base
-can attach must be
-.Ar interface attributes ,
-or
+can attach must be interface attributes, or
.Ic root
in case the device is at the top-level, which is usually the case of e.g.,
.Xr mainbus 4 .
@@ -531,13 +553,15 @@ as a conditional element in a
statement.
.\"
.Pp
-.It Ic defpseudo Ar base Oo : dependencies Oc
+.It Ic defpseudo Ar base Op Ic \&: Ar dependencies
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
+.It Ic defpseudodev Ar base \
+ Oo Ic \&{ Ar locators Ic \&} Oc \
+ Op Ic \&: Ar dependencies
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.
@@ -554,19 +578,21 @@ Interface attributes can also be defined
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
+.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
-.Ar conditions
-are met.
+.Ar condition
+is met.
The
.Ic needs-count
option indicates that the source file requires the number of all the countable
objects it depends on (through the
-.Ar conditions )
+.Ar condition )
to be defined.
-It is usually used for
-.Ar pseudo-devices
+It is usually used for pseudo-devices
whose number can be specified by the user in the
.Ic pseudo-device
statement.
@@ -580,12 +606,13 @@ be created, but the precise number isn't
This is useful for source files that only partly depend on the attribute,
and thus need to add pre-processor statements for it.
.Pp
+Both
.Ic needs-count
and
.Ic needs-flag
-both produce a header file for each of the considered attributes.
+produce a header file for each of the considered attributes.
The name of that file is
-.Pa <attribute>.h .
+.Ao Ns Ar attribute Ns Ac Ns Pa \&.h .
It contains one pre-processor definition of
.Dv NATTRIBUTE
set to 0 if the attribute was not selected by the user, or to the number of
@@ -605,7 +632,7 @@ statement, but not from the same configu
statements can only specify a
.Ar rule
argument, and no
-.Ar conditions
+.Ar condition
or flags.
This is useful when a file needs special consideration from one particular
architecture.
@@ -676,7 +703,7 @@ and each of the
.It Ic package Ar path
Simpler version of:
.Bd -literal -offset indent
-prefix PATH
+prefix DIR
include FILE
prefix
.Ed
@@ -700,8 +727,10 @@ parameter is used for example to compute
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 ...
+.It Ic options \
+ Ar name Ns Oo Ic = Ns Ar value\^ Oc \
+ Ns Op Ic \&, Ar name Ns Oo Ic = Ns Ar value\^ Oc \
+ Ns Op Ic \&, Ar ...
Selects the option
.Ar name ,
affecting it a
@@ -720,21 +749,32 @@ warning, and the new
.Ic options
statement replaces the original.
.\"
-.It Ic no options Ar name Op , Ar name Op , Ar ...
+.It Ic no options \
+ Ar name \
+ Ns Op Ic \&, Ar name \
+ Ns Op Ic \&, 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 ...
+.It Ic file-system \
+ Ar name \
+ Ns Op Ic \&, Ar name \
+ Ns Op Ic \&, Ar ...
Adds support for all the listed file-systems.
.\"
-.It Ic no file-system Ar name Op , Ar name Op , Ar ...
+.It Ic no file-system \
+ Ar name \
+ Ns Op Ic \&, Ar name \
+ Ns Op Ic \&, 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
+.It Ic config Ar name \
+ Ic root on Ar device \
+ Oo Ic type Ar fs Oc \
+ Op Ic dumps on Ar device
Adds
.Ar name
to the list of kernel binaries to compile from the configuration file, using
@@ -745,7 +785,7 @@ Any of the
and
.Ar fs
parameters can be wildcarded with
-.Dq \&?
+.Ql \&?
to let the kernel automatically discover those values.
The
.Ar device
@@ -753,7 +793,7 @@ can also be specified as a quoted specif
The kernel interprets this string like the console input
when prompting for a root device.
E.g.,
-.Dq wedge:NAME
+.Dq Li wedge: Ns Ar NAME\|
specifies a named disk wedge.
.Pp
At least one
@@ -765,15 +805,15 @@ 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
+.It Ar instance Ic at Ar attachment Op Ar locator-specifications ...
Configures an instance of a device attaching at a specific location in the
device tree.
All parameters can be wildcarded, with a
-.Dq *
+.Ql *
for
.Ar instance ,
and a
-.Dq \&?
+.Ql \&?
for
.Ar attachment
and the locators.
@@ -797,7 +837,7 @@ attachment.
If
.Ar attachment
ends with a
-.Dq * ,
+.Ql * ,
all instances attaching to all the variants of
.Ar attachment
are removed.
@@ -813,22 +853,27 @@ It defaults to 1, and some pseudo-device
.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 ...
+.It Ic makeoptions \
+ Ar name Ns Ic = Ns Ar value \
+ Ns Op Ic \&, Ar name Ns Ic += Ns Ar value \
+ Ns Op Ic \&, Ar ...
Adds or appends to a definition in the generated
.Pa Makefile .
A definition cannot be overriden, it must be removed before it can be added
again.
Optionally, if an option
-.Pa makeoptions_<name>
+.Li makeoptions_ Ns Aq Ar name
is defined with
.Ic defparam ,
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
+.\" XXX: This variant of makeoptions can only be specified in the descriptions.
+.It Ic makeoptions \
+ Ar condition name Ns Ic += Ns Ar value \
+ Ns Op Ic \&, Ar condition name Ns Ic += Ns Ar value \
+ Ns Op Ic \&, Ar ...
Appends to a definition in the generated
.Pa Makefile .
.\"
@@ -846,7 +891,7 @@ Removes the specified attribute and all
The files are relative to the kernel source top directory (e.g.,
.Pa /usr/src/sys ) .
.Pp
-.Bl -tag -width arch/${MACHINE}/conf/std.${MACHINE}
+.Bl -tag -width ".Pa conf/files"
.It Pa arch/${MACHINE}/conf/std.${MACHINE}
Standard configuration for the given architecture.
This file should always be included.
