[src/trunk]: src/share/man/man7 Do some markup cleanup for the benefit of tro...

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

details:   https://anonhg.NetBSD.org/src/rev/64a1960383fa
branches:  trunk
changeset: 761034:64a1960383fa
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed Jan 19 02:25:17 2011 +0000

description:
Do some markup cleanup for the benefit of troff PostScript output.

- try to be more consistent with Va/Vt/Dv
- make the space in "... otherwise 0." non-paddable to prevent widow "0."
- consistently use -width "123456" for lists of nodes


TODO: There's still quite a bit of mess to clean up:

- tables of "n+1 level names" are indented (or not) inconsistently
- formatting of node names is inconsistent (normal vs literal)
- references to POSIX should use .St
- filesystem vs. file-system, our old time favorite!
- .Pq adds annoying extra space in troff output, do we really want to use it?
- etc.

diffstat:

 share/man/man7/sysctl.7 |  208 ++++++++++++++++++++++++++---------------------
 1 files changed, 115 insertions(+), 93 deletions(-)

diffs (truncated from 590 to 300 lines):

diff -r e5bf99185a09 -r 64a1960383fa share/man/man7/sysctl.7
--- a/share/man/man7/sysctl.7   Wed Jan 19 01:52:43 2011 +0000
+++ b/share/man/man7/sysctl.7   Wed Jan 19 02:25:17 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sysctl.7,v 1.55 2011/01/09 22:21:55 wiz Exp $
+.\"    $NetBSD: sysctl.7,v 1.56 2011/01/19 02:25:17 uwe Exp $
 .\"
 .\" Copyright (c) 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"    @(#)sysctl.3    8.4 (Berkeley) 5/9/95
 .\"
-.Dd January 9, 2011
+.Dd January 19, 2011
 .Dt SYSCTL 7
 .Os
 .Sh NAME
@@ -69,26 +69,28 @@
 .Xr sysctl 3
 manual page for programming examples.
 .Ss Top level names
-The top level names are defined with a CTL_ prefix in
+The top level names are defined with a
+.Va CTL_
+prefix in
 .In sys/sysctl.h ,
 and are as follows.
 The next and subsequent levels down are found in the include files
 listed here, and described in separate sections below.
-.Bl -column security CTL_SECURITY "Next level names" "High kernel limits"
-.It Sy Name    Constant        Next level names        Description
-.It kern       CTL_KERN        sys/sysctl.h    High kernel limits
-.It vm CTL_VM  uvm/uvm_param.h Virtual memory
-.It vfs        CTL_VFS sys/mount.h     Filesystem
-.It net        CTL_NET sys/socket.h    Networking
-.It debug      CTL_DEBUG       sys/sysctl.h    Debugging
-.It hw CTL_HW  sys/sysctl.h    Generic CPU, I/O
-.It machdep    CTL_MACHDEP     sys/sysctl.h    Machine dependent
-.It user       CTL_USER        sys/sysctl.h    User-level
-.It ddb        CTL_DDB sys/sysctl.h    In-kernel debugger
-.It proc       CTL_PROC        sys/sysctl.h    Per-process
-.It vendor     CTL_VENDOR      ?       Vendor specific
-.It emul       CTL_EMUL        sys/sysctl.h    Emulation settings
-.It security   CTL_SECURITY    sys/sysctl.h    Security settings
+.Bl -column "security" ".Dv CTL_SECURITY" ".In uvm/uvm_param.h" "High kernel limits"
+.It Sy Name  Ta Sy Constant     Ta Sy Next level names Ta Sy Description
+.It kern     Ta Dv CTL_KERN     Ta In sys/sysctl.h     Ta High kernel limits
+.It vm       Ta Dv CTL_VM       Ta In uvm/uvm_param.h  Ta Virtual memory
+.It vfs      Ta Dv CTL_VFS      Ta In sys/mount.h      Ta Filesystem
+.It net      Ta Dv CTL_NET      Ta In sys/socket.h     Ta Networking
+.It debug    Ta Dv CTL_DEBUG    Ta In sys/sysctl.h     Ta Debugging
+.It hw       Ta Dv CTL_HW       Ta In sys/sysctl.h     Ta Generic CPU, I/O
+.It machdep  Ta Dv CTL_MACHDEP  Ta In sys/sysctl.h     Ta Machine dependent
+.It user     Ta Dv CTL_USER     Ta In sys/sysctl.h     Ta User-level
+.It ddb      Ta Dv CTL_DDB      Ta In sys/sysctl.h     Ta In-kernel debugger
+.It proc     Ta Dv CTL_PROC     Ta In sys/sysctl.h     Ta Per-process
+.It vendor   Ta Dv CTL_VENDOR   Ta ?                   Ta Vendor specific
+.It emul     Ta Dv CTL_EMUL     Ta In sys/sysctl.h     Ta Emulation settings
+.It security Ta Dv CTL_SECURITY Ta In sys/sysctl.h     Ta Security settings
 .El
 .Ss The debug.* subtree
 The debugging variables vary from system to system.
@@ -100,7 +102,7 @@
 gets the list of debugging variables from the kernel and
 displays their current values.
 The system defines twenty
-.Va ( struct ctldebug )
+.Vt ( struct ctldebug )
 variables named
 .Dv debug0
 through
@@ -110,7 +112,7 @@
 The loader prevents multiple use of the same variable by issuing errors
 if a variable is initialized in more than one place.
 For example, to export the variable
-.Dv dospecialcheck
+.Va dospecialcheck
 as a debugging variable, the following declaration would be used:
 .Pp
 .Bd -literal -offset indent -compact
@@ -133,10 +135,10 @@
 .Li vfs.generic ( VFS_GENERIC ) ,
 is used to get general information about all filesystems.
 It has the following third level identifiers:
-.Bl -tag -width "vfs.generic.maxtypenum (VFS_MAXTYPENUM)"
-.It vfs.generic.maxtypenum ( VFS_MAXTYPENUM )
+.Bl -tag -width "123456"
+.It Li vfs.generic.maxtypenum ( VFS_MAXTYPENUM )
 The highest valid filesystem type number.
-.It vfs.generic.conf ( VFS_CONF )
+.It Li vfs.generic.conf ( VFS_CONF )
 Returns configuration information about the file-system type given as a fourth
 level identifier.
 .El
@@ -145,13 +147,13 @@
 .Xr wapbl 4
 (Write Ahead Physical Block Logging file system journalling)
 capabilities with the following third level identifiers:
-.Bl -tag -width "vfs.wapbl.flush_disk_cache"
-.It vfs.wapbl.flush_disk_cache
+.Bl -tag -width "123456"
+.It Li vfs.wapbl.flush_disk_cache
 Controls whether to attempt to flush the disk cache on each commit.
 It defaults to 1 and it should always be on to ensure data integrity in
 case of a crash.
 For slow disks, turning it off can improve performance.
-.It vfs.wapbl.verbose_commit
+.It Li vfs.wapbl.verbose_commit
 For each transaction log commit, print the number of bytes written
 and the time it took to commit as seconds.nanoseconds.
 .El
@@ -161,6 +163,7 @@
 .Xr statvfs 2
 call or from
 .Li vfs.generic.conf .
+.Pp
 The third level identifiers available for each filesystem
 are given in the header file that defines the mount
 argument structure for that filesystem.
@@ -194,10 +197,10 @@
 This shows the value
 .Dv ALIGNBYTES
 in
-.Pa /usr/include/machine/param.h ,
+.In machine/param.h ,
 at the kernel compilation time.
 .It Li hw.byteorder ( HW_BYTEORDER )
-The byteorder (4,321, or 1,234).
+The byteorder (4321, or 1234).
 .It Li hw.cnmagic ( HW_CNMAGIC )
 The console magic key sequence.
 .It Li hw.disknames ( HW_DISKNAMES )
@@ -209,15 +212,15 @@
 Return statistical information on the NFS mounts, disk and tape
 devices on the system.
 An array of
-.Va struct io_sysctl
+.Vt struct io_sysctl
 structures is returned,
 whose size depends on the current number of such objects in the system.
 The third level name is the size of the
-.Va struct io_sysctl .
+.Vt struct io_sysctl .
 The type of object can be determined by examining the
 .Va type
 element of
-.Va struct io_sysctl .
+.Vt struct io_sysctl .
 Which can be
 .Dv IOSTAT_DISK
 (disk drive),
@@ -360,7 +363,7 @@
 .It Li kern.arandom
 This variable picks a random number each time it is queried.
 The used random number generator
-.Pq Tn RNG
+.Pf ( Tn RNG )
 is based on
 .Xr arc4random 3 .
 .It Li kern.argmax ( KERN_ARGMAX )
@@ -372,7 +375,7 @@
 for the meanings of the flags.
 .It Li kern.boottime ( KERN_BOOTTIME )
 A
-.Va struct timeval
+.Vt struct timeval
 structure is returned.
 This structure contains the time that the system was booted.
 .\" .It Li kern.bufq
@@ -381,7 +384,7 @@
 The scheduler exponential decay value.
 .It Li kern.clockrate ( KERN_CLOCKRATE )
 A
-.Va struct clockinfo
+.Vt struct clockinfo
 structure is returned.
 This structure contains the clock, statistics clock and profiling clock
 frequencies, the number of micro-seconds per hz tick, and the clock
@@ -428,7 +431,9 @@
 .It Li kern.cp_id ( KERN_CP_ID )
 Mapping of CPU number to CPU id.
 .It Li kern.cp_time ( KERN_CP_TIME )
-Returns an array of CPUSTATES uint64_ts.
+Returns an array of
+.Dv CPUSTATES
+.Vt uint64_t Ns s.
 This array contains the
 number of clock ticks spent in different CPU states.
 On multi-processor systems, the sum across all CPUs is returned unless
@@ -459,7 +464,7 @@
 .Xr core 5
 for format of this template).
 The default value is
-.Nm %n.core
+.Pa %n.core
 and can be changed with the kernel configuration option
 .Cd options DEFCORENAME
 (see
@@ -471,7 +476,7 @@
 Get or set the YP domain name.
 .It Li kern.drivers ( KERN_DRIVERS )
 Return an array of
-.Va struct kinfo_drivers
+.Vt struct kinfo_drivers
 that contains the name and major device numbers of all the device drivers
 in the current kernel.
 The
@@ -486,9 +491,9 @@
 .It Li kern.file ( KERN_FILE )
 Return the entire file table.
 The returned data consists of a single
-.Va struct filelist
+.Vt struct filelist
 followed by an array of
-.Va struct file ,
+.Vt struct file ,
 whose size depends on the current number of such objects in the system.
 .It Li kern.forkfsleep ( KERN_FORKFSLEEP )
 If
@@ -506,7 +511,7 @@
 .It Li kern.fsync ( KERN_FSYNC )
 Return 1 if the POSIX 1003.1b File Synchronization Option is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.hardclock_ticks ( KERN_HARDCLOCK_TICKS )
 Returns the number of
 .Xr hardclock 9
@@ -523,7 +528,7 @@
 .Xr hostname 1 .
 .It Li kern.iov_max ( KERN_IOV_MAX )
 Return the maximum number of
-.Va iovec
+.Vt iovec
 structures that a process has available for use with
 .Xr preadv 2 ,
 .Xr pwritev 2 ,
@@ -556,15 +561,15 @@
 .It Li kern.ipc.sysvmsg ( KERN_SYSVIPC_MSG )
 Returns 1 if System V style message queue functionality is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.ipc.sysvsem ( KERN_SYSVIPC_SEM )
 Returns 1 if System V style semaphore functionality is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.ipc.sysvshm ( KERN_SYSVIPC_SHM )
 Returns 1 if System V style share memory functionality is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.ipc.sysvipc_info ( KERN_SYSVIPC_INFO )
 Return System V style IPC configuration and run-time information.
 The fourth level name selects the System V style IPC facility.
@@ -619,9 +624,11 @@
 Max number of undo structures in system.
 .El
 .It Li kern.job_control ( KERN_JOB_CONTROL )
-Return 1 if job control is available on this system, otherwise 0.
+Return 1 if job control is available on this system, otherwise\ 0.
 .It Li kern.labeloffset ( KERN_LABELOFFSET )
-The offset within the sector specified by KERN_LABELSECTOR of the
+The offset within the sector specified by
+.Dv KERN_LABELSECTOR
+of the
 .Xr disklabel 5 .
 .It Li kern.labelsector ( KERN_LABELSECTOR )
 The sector number containing the
@@ -638,7 +645,7 @@
 .It Li kern.mapped_files ( KERN_MAPPED_FILES )
 Returns 1 if the POSIX 1003.1b Memory Mapped Files Option is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.maxfiles ( KERN_MAXFILES )
 The maximum number of open files that may be open in the system.
 .It Li kern.maxpartitions ( KERN_MAXPARTITIONS )
@@ -692,15 +699,15 @@
 .It Li kern.memlock ( KERN_MEMLOCK )
 Returns 1 if the POSIX 1003.1b Process Memory Locking Option is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.memlock_range ( KERN_MEMLOCK_RANGE )
 Returns 1 if the POSIX 1003.1b Range Memory Locking Option is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.memory_protection ( KERN_MEMORY_PROTECTION )
 Returns 1 if the POSIX 1003.1b Memory Protection Option is available
 on this system,
-otherwise 0.
+otherwise\ 0.
 .It Li kern.module
 Settings related to kernel modules.
 The third level names for the settings are described below.
@@ -724,7 +731,7 @@