[src/trunk]: src/share/man/man9 autoconf(9) - Improve formatting.

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

details:   https://anonhg.NetBSD.org/src/rev/b31dceacd00f
branches:  trunk
changeset: 985081:b31dceacd00f
user:      uwe <uwe%NetBSD.org@localhost>
date:      Sat Aug 07 20:41:17 2021 +0000

description:
autoconf(9) - Improve formatting.

Don't hide consumed cfargs in the second sentence of a function's
description, they ends up hidden towards the right margin and that
sentence is guaranteed to get a line break further reducing its
readability.  Instead make that the first sentence and start the
description with a new paragraph.  That makes it looks like part of
the signature and is much more prominent.

Various markup improvements while here.

Bump date for thorpej-cfargs2 changes.

diffstat:

 share/man/man9/autoconf.9 |  155 ++++++++++++++++++++++++++++++++-------------
 1 files changed, 111 insertions(+), 44 deletions(-)

diffs (truncated from 329 to 300 lines):

diff -r cf5dab53f4da -r b31dceacd00f share/man/man9/autoconf.9
--- a/share/man/man9/autoconf.9 Sat Aug 07 19:44:39 2021 +0000
+++ b/share/man/man9/autoconf.9 Sat Aug 07 20:41:17 2021 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: autoconf.9,v 1.33 2021/08/07 19:41:13 andvar Exp $
+.\"     $NetBSD: autoconf.9,v 1.34 2021/08/07 20:41:17 uwe Exp $
 .\"
 .\" Copyright (c) 2001, 2002, 2021 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 28, 2021
+.Dd August 7, 2021
 .Dt AUTOCONF 9
 .Os
 .Sh NAME
@@ -126,42 +126,51 @@
 .Fn CFARGS
 macro, like this example:
 .Bd -literal -offset indent
-    config_search(self, NULL,
-        CFARGS(.search = mainbus_search,
-               .iattr = "mainbus"));
+config_search(self, NULL,
+    CFARGS(.search = mainbus_search,
+           .iattr = "mainbus"));
 .Ed
 .Pp
 Each tag is followed by a tag-specific value.
-.Bl -tag -width ".devhandle"
-.It Dv .submatch
+.Bl -tag -offset indent -width ".Fa devhandle"
+.It Fa submatch
 A pointer to a
 .Sq submatch
-function used in direct configuration.
-.It Dv .search
+function used in
+.Em direct
+configuration.
+.\"
+.It Fa search
 A pointer to a
 .Sq search
-function used in indirect configuration.
-.It Dv .iattr
-A pointer to a constant C string
-.Pq const char *
+function used in
+.Em indirect
+configuration.
+.\"
+.It Fa iattr
+A pointer to a constant
+.Tn C
+string
+.Pq Vt "const char *"
 specifying an interface attribute.
 If a parent device carries only a single interface attribute, then this
 argument may be omitted.
 If an interface attribute is specified that the parent device does not
-carry, or no interface attribute is specifies and the parent device carries
+carry, or no interface attribute is specified and the parent device carries
 more than one, behavior is undefined.
 On kernels built with the
 .Dv DIAGNOSTIC
 option, this may result in an assertion panic.
-.It Dv .locators
-A pointer an a constant array of type
-.Sq int
-.Pq const int *
+.\"
+.It Fa locators
+A pointer to a constant array of integers
+.Pq Vt "const int *"
 containing interface attribute-specific locators.
-.It Dv .devhandle
-A devhandle_t
-.Pq passed by value
-corresponding to the device being attached.
+.\"
+.It Fa devhandle
+A
+.Vt devhandle_t
+(passed by value) corresponding to the device being attached.
 .El
 .Pp
 If no arguments are to be passed, the special value
@@ -170,13 +179,17 @@
 .Fn CFARGS
 macro.
 .Sh FUNCTIONS
-.Bl -tag -width compact
+.Bl -tag -width ".Fn config"
+.\"
+.\"
 .It Fn config_search "parent" "aux" "cfargs"
-Performs indirect configuration of physical devices.
 Cfargs consumed:
-.Em .search ,
-.Em .iattr ,
-.Em .locators .
+.Fa search ,
+.Fa iattr ,
+.Fa locators .
+.\"
+.Pp
+Performs indirect configuration of physical devices.
 .Fn config_search
 iterates over all potential children, calling the given
 search function
@@ -216,13 +229,17 @@
 Note that this function is designed so that it can be used to apply an
 arbitrary function to all potential children.
 In this case callers may choose to ignore the return value.
+.\"
+.\"
 .It Fn config_found "parent" "aux" "print" "cfargs"
-Performs direct configuration on a physical device.
 Cfargs consumed:
-.Em .submatch ,
-.Em .iattr ,
-.Em .locators ,
-.Em .devhandle .
+.Fa submatch ,
+.Fa iattr ,
+.Fa locators ,
+.Fa devhandle .
+.\"
+.Pp
+Performs direct configuration on a physical device.
 .Fn config_found
 is called by the parent and in turn calls the specified submatch function
 as determined by the configuration table.
@@ -249,7 +266,7 @@
 internally uses
 .Fn config_search .
 The
-.Em softc
+.Vt softc
 structure for the matched device will be allocated, and the
 appropriate driver attach function will be called.
 If the device is matched, the system prints the name of the child and
@@ -277,20 +294,28 @@
 unsupported
 .Dc
 will be appended automatically to non-driver reports if the return
-value is UNCONF or UNSUPP respectively; otherwise the function should
-return the value QUIET.
+value is
+.Dv UNCONF
+or
+.Dv UNSUPP
+respectively; otherwise the function should
+return the value
+.Dv QUIET .
 If a device handle is specified, that handle will be associated with
 the resulting child device structure if a driver matches.
 .Pp
 .Fn config_found
 returns a pointer to the attached device's
-.Em device
+.Vt device
 structure if the device is attached,
 .Dv NULL
 otherwise.
 Most callers can ignore this value, since the system will already have
 printed a diagnostic.
+.\"
+.\"
 .It Fn config_match "parent" "cf" "aux"
+.\"
 Match a device
 .Pq direct configuration .
 Invokes the driver's match function according to the configuration table.
@@ -299,7 +324,10 @@
 function returns a nonzero integer indicating the confidence of
 supporting this device and a value of 0 if the driver doesn't support
 the device.
+.\"
+.\"
 .It Fn config_probe "parent" "cf" "aux"
+.\"
 Probe for a device
 .Pq indirect configuration .
 Invokes the driver's match function according to the configuration table.
@@ -312,23 +340,30 @@
 the return value of
 .Fn config_probe
 is not intended to reflect a confidence value.
+.\"
+.\"
 .It Fn config_attach "parent" "cf" "aux" "print" "cfargs"
-Attach a found device.
 Cfargs consumed:
-.Em .locators ,
-.Em .devhandle .
+.Fa locators ,
+.Fa devhandle .
+.\"
+.Pp
+Attach a found device.
 Allocates the memory for the
-.Em softc
+.Vt softc
 structure and calls the drivers attach function according to the
 configuration table.
 If successful,
 .Fn config_attach
 returns a pointer to the
-.Em device
+.Vt device
 structure.
 If unsuccessful, it returns
 .Dv NULL .
+.\"
+.\"
 .It Fn config_attach_pseudo "cf"
+.\"
 Create an instance of a pseudo-device driver.
 .Xr config 5
 syntax allows the creation of pseudo-devices from which regular
@@ -344,19 +379,29 @@
 The content of that object is similar to what is returned by
 .Fn config_search
 for regular devices.
+.\"
+.\"
 .It Fn config_detach "dev" "flags"
+.\"
 Called by the parent to detach the child device.
 The second argument
-.Em flags
+.Fa flags
 contains detachment flags.
-Valid values are DETACH_FORCE (force detachment (e.g., because of hardware
-removal)) and DETACH_QUIET (do not print a notice).
+Valid values are
+.Dv DETACH_FORCE
+(force detachment, e.g., because of hardware removal)
+and
+.Dv DETACH_QUIET
+(do not print a notice).
 .Fn config_detach
 returns zero if successful and an error code otherwise.
 .Fn config_detach
 is always called from a thread context, allowing condition variables
 to be used while the device detaches itself.
+.\"
+.\"
 .It Fn config_detach_children "dev" "flags"
+.\"
 Iterate through all attached devices, calling
 .Fn config_detach
 for each child of
@@ -367,7 +412,10 @@
 and any remaining devices will not be detached.
 .Fn config_detach_children
 returns zero if successful and an error code otherwise.
+.\"
+.\"
 .It Fn config_deactivate "dev"
+.\"
 Called by the parent to deactivate the child device
 .Fa dev .
 .Fn config_deactivate
@@ -377,21 +425,30 @@
 At some later point
 .Fn config_detach
 will be called to finalise the removal of the device.
+.\"
+.\"
 .It Fn config_defer "dev" "func"
+.\"
 Called by the child to defer the remainder of its configuration until
 all its parent's devices have been attached.
 At this point, the function
 .Fa func
 is called with the argument
 .Fa dev .
+.\"
+.\"
 .It Fn config_interrupts "dev" "func"
+.\"
 Called by the child to defer the remainder of its configuration until
 interrupts are enabled.
 At this point, the function
 .Fa func
 is called with the argument
 .Fa dev .
+.\"
+.\"
 .It Fn config_mountroot "dev" "func"
+.\"
 Called by the child to defer the remainder of its configuration until
 the root file system is mounted.
 At this point, the function
@@ -400,19 +457,29 @@