[src/trunk]: src/usr.bin/config Formatting improvements.

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7c23dbff74cd
branches:  trunk
changeset: 936619:7c23dbff74cd
user:      uwe <uwe%NetBSD.org@localhost>
date:      Fri Jul 31 23:30:23 2020 +0000

description:
Formatting improvements.

diffstat:

 usr.bin/config/config.5 |  155 ++++++++++++++++++++++++++++++-----------------
 1 files changed, 100 insertions(+), 55 deletions(-)

diffs (truncated from 383 to 300 lines):

diff -r bb77d7ea0ffe -r 7c23dbff74cd usr.bin/config/config.5
--- a/usr.bin/config/config.5   Fri Jul 31 22:07:28 2020 +0000
+++ b/usr.bin/config/config.5   Fri Jul 31 23:30:23 2020 +0000
@@ -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 @@
 .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 @@
 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 @@
 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 @@
 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 @@
 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.
 .\"
 .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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 .It Ic package Ar path
 Simpler version of:
 .Bd -literal -offset indent
-prefix PATH
+prefix DIR
 include FILE
 prefix
 .Ed
@@ -700,8 +727,10 @@
 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 @@
 .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 @@
 and
 .Ar fs
 parameters can be wildcarded with
-.Dq \&?