mdoc(7) police: scheduled sweep.

Approved by:	re

2 files changed, 163 insertions, 137 deletions

diff --git a/share/man/man8/rc.8 b/share/man/man8/rc.8
index c8c1b6a..f299111 100644
--- a/share/man/man8/rc.8
+++ b/share/man/man8/rc.8
@@ -40,16 +40,12 @@
 .Os
 .Sh NAME
 .Nm rc
-.Nd command scripts for auto\-reboot and daemon startup
+.Nd command scripts for auto-reboot and daemon startup
 .Sh SYNOPSIS
 .Nm
-.Nm rc.d/
-.Nm rc.d/atm*
-.Nm rc.d/network*
-.Nm rc.d/pccard
-.Nm rc.d/serial
 .Nm rc.conf
 .Nm rc.conf.local
+.Nm rc.d/
 .Nm rc.firewall
 .Nm rc.local
 .Nm rc.shutdown
@@ -63,22 +59,24 @@ after being called by
 The
 .Nm rc.local
 script contains commands which are pertinent only
-to a specific site.  Typically, the
-.Nm /usr/local/etc/rc.d
+to a specific site.
+Typically, the
+.Pa /usr/local/etc/rc.d/
 mechanism is used instead of
 .Nm rc.local
 these days but if
 you want to use
-.Nm rc.local
-it is still supported.  In this case it should source
-.Nm /etc/rc.conf
+.Nm rc.local ,
+it is still supported.
+In this case, it should source
+.Pa /etc/rc.conf
 and contain additional custom startup code for your system.
 The best way to handle
-.Nm rc.local ;
+.Nm rc.local ,
 however, is to separate it out into
-.Nm /etc/rc.d
-style scripts and place them in
-.Nm /usr/local/etc/rc.d .
+.Nm rc.d/
+style scripts and place them under
+.Pa /usr/local/etc/rc.d/ .
 The
 .Nm rc.conf
 file contains the global system configuration information referenced
@@ -90,10 +88,10 @@ See
 for more information.
 .Pp
 The
-.Nm rc.d
+.Nm rc.d/
 directories contain scripts which will be automatically
 executed at boot time and shutdown time.
-.Ss Operation of rc
+.Ss Operation of Nm
 .Bl -enum
 .It
 Source
@@ -103,16 +101,16 @@ to load various
 shell functions to use.
 .It
 If autobooting, set
-.Sy autoboot=yes
+.Va autoboot Ns = Ns Li yes
 and enable a flag
-.Sy ( rc_fast=yes ) ,
+.Pq Va rc_fast Ns = Ns Li yes ,
 which prevents the
-.Nm rc.d
+.Nm rc.d/
 scripts from performing the check for already running processes
 (thus speeding up the boot process).
 This
-.Sy rc_fast=yes
-speedup won't occur when
+.Va rc_fast Ns = Ns Li yes
+speedup will not occur when
 .Nm
 is started up after exiting the single-user shell.
 .It
@@ -121,25 +119,27 @@ Invoke
 to order the files in
 .Pa /etc/rc.d/
 that do not have a
-.Dq nostart
+.Dq Li nostart
 keyword (refer to
-.Xr rcorder 8 's
+.Xr rcorder 8 Ns 's
 .Fl s
 flag),
-and assigns the result to a variable.
+and assign the result to a variable.
 .It
-Calls each script in turn using run_rc_script() (from
+Call each script in turn using
+.Fn run_rc_script
+(from
 .Xr rc.subr 8 ) ,
 which sets
-.Dv $1
+.Va $1
 to
-.Sq start ,
+.Dq Li start ,
 and sources the script in a subshell.
 If the script has a
-.Sq .sh
+.Pa .sh
 suffix then it is sourced directly into the current shell.
 .El
-.Ss Operation of rc.shutdown
+.Ss Operation of Nm rc.shutdown
 .Bl -enum
 .It
 Source
@@ -153,53 +153,51 @@ Invoke
 to order the files in
 .Pa /etc/rc.d/
 that have a
-.Dq shutdown
+.Dq Li shutdown
 keyword (refer to
-.Xr rcorder 8 's
+.Xr rcorder 8 Ns 's
 .Fl k
 flag),
-reverses that order, and assigns the result to a variable.
+reverse that order, and assign the result to a variable.
 .It
-Calls each script in turn using run_rc_script() (from
+Call each script in turn using
+.Fn run_rc_script
+(from
 .Xr rc.subr 8 ) ,
 which sets
-.Dv $1
+.Va $1
 to
-.Sq stop ,
+.Dq Li stop ,
 and sources the script in a subshell.
 If the script has a
-.Sq .sh
+.Pa .sh
 suffix then it is sourced directly into the current shell.
 .El
-.Ss Contents of rc.d/
+.Ss Contents of Nm rc.d/
 .Nm rc.d/
 is located in
-.Pa /etc/rc.d .
+.Pa /etc/rc.d/ .
 The following file naming conventions are currently used in
 .Nm rc.d/ :
-.Bl -tag -width ALLUPPERCASExx -offset indent
+.Bl -tag -width ".Pa ALLUPPERCASE" -offset indent
 .It Pa ALLUPPERCASE
 Scripts that are
-.Sq placeholders
+.Dq placeholders
 to ensure that certain operations are performed before others.
 In order of startup, these are:
-.Bl -tag -width NETWORKINGxx
+.Bl -tag -width ".Pa NETWORKING"
 .It Pa NETWORKING
 Ensure basic network services are running, including general
-network configuration (
-.Pa network1,
-.Pa network2
-.Pa network3 ) .
+network configuration
+.Pq Pa network1 , network2 , network3 .
 .It Pa SERVERS
 Ensure basic services (such as
-.Pa NETWORKING ,
-.Pa ppp-user ,
-.Pa syslogd ,
+.Pa NETWORKING , ppp-user , syslogd ,
 and
 .Pa isdnd )
 exist for services that start early (such as
 .Pa named ) ,
-because they're required by
+because they are required by
 .Pa DAEMON
 below.
 .It Pa DAEMON
@@ -220,7 +218,7 @@ and
 .It Pa foo.sh
 Scripts that are to be sourced into the current shell rather than a subshell
 have a
-.Sq Pa .sh
+.Pa .sh
 suffix.
 Extreme care must be taken in using this, as the startup sequence will
 terminate if the script does.
@@ -228,11 +226,11 @@ terminate if the script does.
 Scripts that are sourced in a subshell.
 These can stop the boot if necessary with the following shell
 commands:
-.Bd -literal -offset
-	if [ "$autoboot" = yes ]; then
-		kill -TERM $$
-	fi
-	exit 1
+.Bd -literal -offset indent
+if [ "$autoboot" = yes ]; then
+	kill -TERM $$
+fi
+exit 1
 .Ed
 .Pp
 Note that this should be used extremely sparingly!
@@ -241,19 +239,22 @@ Note that this should be used extremely sparingly!
 Each script should contain
 .Xr rcorder 8
 keywords, especially an appropriate
-.Dq PROVIDE
+.Dq Li PROVIDE
 entry, and if necessary
-.Dq REQUIRE
+.Dq Li REQUIRE
 and
-.Dq BEFORE
-keywords. In addition, all scripts must have a
-.Dq # KEYWORD: FreeBSD
+.Dq Li BEFORE
+keywords.
+In addition, all scripts must have a
+.Dq Li "# KEYWORD: FreeBSD"
 line.
 .Pp
 Each script is expected to support at least the following arguments, which
-are automatically supported if it uses the run_rc_command() function.
-.Bl -tag -width restart -offset indent
-.It Sy start
+are automatically supported if it uses the
+.Fn run_rc_command
+function:
+.Bl -tag -width ".Cm restart" -offset indent
+.It Cm start
 Start the service.
 This should check that the service is to be started as specified by
 .Xr rc.conf 5 .
@@ -264,35 +265,35 @@ This latter check is not performed by standard
 scripts if the system is starting directly to multi-user mode, to
 speed up the boot process.
 If
-.Sq forcestart
+.Cm forcestart
 is given, ignore the
 .Xr rc.conf 5
 check and start anyway.
-.It Sy stop
+.It Cm stop
 If the service is to be started as specified by
 .Xr rc.conf 5 ,
 stop the service.
-This should check that the service is running and complain if it's not.
+This should check that the service is running and complain if it is not.
 If
-.Sq forcestop
+.Cm forcestop
 is given, ignore the
 .Xr rc.conf 5
 check and attempt to stop.
-.It Sy restart
+.It Cm restart
 Perform a
-.Sy stop
+.Cm stop
 then a
-.Sy start .
-.It Sy status
+.Cm start .
+.It Cm status
 If the script starts a process (rather than performing a one-off
 operation), show the status of the process.
-Otherwise it's not necessary to support this argument.
+Otherwise it is not necessary to support this argument.
 Defaults to displaying the process ID of the program (if running).
-.It Sy poll
+.It Cm poll
 If the script starts a process (rather than performing a one-off
 operation), wait for the command to exit.
-Otherwise it's not necessary to support this argument.
-.It Sy rcvar
+Otherwise it is not necessary to support this argument.
+.It Cm rcvar
 Display which
 .Xr rc.conf 5
 variables are used to control the startup of the service (if any).
@@ -300,16 +301,16 @@ variables are used to control the startup of the service (if any).
 .Pp
 If a script must implement additional commands it can list them in
 the
-.Sq extra_commands
-variable and define their actions in a variable constructed from
+.Va extra_commands
+variable, and define their actions in a variable constructed from
 the command name (see the
 .Sx EXAMPLES
 section).
 .Pp
 The following key points apply to old-style scripts in
-.Nm /usr/local/etc/rc.d :
+.Pa /usr/local/etc/rc.d/ :
 .Pp
-.Bl -bullet -compact
+.Bl -bullet
 .It
 Scripts are only executed if their
 .Xr basename 1
@@ -320,16 +321,16 @@ Any other files or directories present within the directory are silently
 ignored.
 .It
 When a script is executed at boot time, it is passed the string
-.Dq start
+.Dq Li start
 as its first and only argument.
 At shutdown time, it is passed the string
-.Dq stop
+.Dq Li stop
 as its first and only argument.
 All
-.Nm rc.d
+.Nm rc.d/
 scripts are expected to handle these arguments appropriately.
 If no action needs to be taken at a given time
-(either boot time or shutdown time)
+(either boot time or shutdown time),
 the script should exit successfully and without producing an error message.
 .It
 The scripts within each directory are executed in lexicographical order.
@@ -348,13 +349,13 @@ a trailing newline character (see the
 .Sx EXAMPLES
 section).
 .El
-.Sh Scripts of Interest
+.Sh SCRIPTS OF INTEREST
 When an automatic reboot is in progress,
 .Nm
 is invoked with the argument
-.Em autoboot .
+.Cm autoboot .
 One of the scripts run from
-.Nm /etc/rc.d
+.Pa /etc/rc.d/
 is
 .Pa /etc/rc.d/fsck .
 This script runs
@@ -363,61 +364,70 @@ with option
 .Fl p
 and
 .Fl F
-to ``preen'' all the disks of minor inconsistencies resulting
-from the last system shutdown. If this fails, then checks/repairs of serious inconsistencies
-caused by hardware or software failure will be performed in the background at the end
-of the booting process. If
-.Em autoboot
-is not set, when going from single-user to multi-user mode for example, the script
-does not do anything.
+to
+.Dq preen
+all the disks of minor inconsistencies resulting
+from the last system shutdown.
+If this fails, then checks/repairs of serious inconsistencies
+caused by hardware or software failure will be performed
+in the background at the end of the booting process.
+If
+.Cm autoboot
+is not set, when going from single-user to multi-user mode for example,
+the script does not do anything.
 .Pp
 The
 .Nm rc.early
 script is run very early in the startup process, immediately before the
-filesystem check. The
+filesystem check.
+The
 .Nm rc.early
-script is deprecated. Any commands in this
+script is deprecated.
+Any commands in this
 file should be separated out into
-.Nm rc.d
+.Nm rc.d/
 style scripts and integrated into the
-.Nm rc
+.Nm
 system.
 .Pp
 The
-.Nm /etc/rc.d/local
+.Pa /etc/rc.d/local
 script can execute scripts from multiple
-.Nm rc.d
+.Nm rc.d/
 directories.
 The default locations are
-.Pa /usr/local/etc/rc.d
+.Pa /usr/local/etc/rc.d/
 and
-.Pa /usr/X11R6/etc/rc.d ,
+.Pa /usr/X11R6/etc/rc.d/ ,
 but these may be overridden with the
 .Va local_startup
 .Xr rc.conf 5
 variable.
 .Pp
 The
-.Nm /etc/rc.d/serial
+.Pa /etc/rc.d/serial
 script is used to set any special configurations for serial devices.
 .Pp
 The
-.Nm /etc/rc.d/pccard
+.Pa /etc/rc.d/pccard
 script is used to enable PC-cards.
 .Pp
 The
-.Nm /etc/rc.d/network*
+.Pa /etc/rc.d/network*
 scripts are used to start the network.
-The network is started in three passes.
+The network is started in several passes.
 The first pass,
-.Nm /etc/rc.d/network1 ,
+.Pa /etc/rc.d/network1 ,
 sets the hostname and domainname and configures the network
-interfaces. The
-.Nm /etc/rc.d/network2
-script starts routing and sets routing options.  The
-.Nm /etc/rc.d/network3
-script sets additional networking options. Lastly, the
-.Nm /etc/rc.d/network_ipv6
+interfaces.
+The
+.Pa /etc/rc.d/network2
+script starts routing and sets routing options.
+The
+.Pa /etc/rc.d/network3
+script sets additional networking options.
+Finally, the
+.Pa /etc/rc.d/network_ipv6
 script configures IPv6 interfaces and options.
 .Pp
 The
@@ -426,23 +436,25 @@ script is used to configure rules for the kernel based firewall
 service.
 It has several possible options:
 .Pp
-.Bl -tag -width "fBfilename" -compact -offset indent
-.It open
-will allow anyone in.
-.It client
-will try to protect just this machine.
-.It simple
-will try to protect a whole network.
-.It closed
-totally disables IP services except via lo0 interface.
-.It UNKNOWN
-disables the loading of firewall rules.
-.It filename
+.Bl -tag -width ".Ar filename" -compact -offset indent
+.It Cm open
+will allow anyone in
+.It Cm client
+will try to protect just this machine
+.It Cm simple
+will try to protect a whole network
+.It Cm closed
+totally disables IP services except via
+.Pa lo0
+interface
+.It Cm UNKNOWN
+disables the loading of firewall rules
+.It Ar filename
 will load the rules in the given filename (full path required).
 .El
 .Pp
 The
-.Nm /etc/rc.d/atm*
+.Pa /etc/rc.d/atm*
 scripts are used to configure ATM network interfaces.
 The interfaces are configured in three passes.
 The first pass performs the initial interface configuration.
@@ -451,7 +463,7 @@ permanent ATMARP entries.
 The third pass starts any ATM daemons.
 .Pp
 Most daemons, including network related daemons, have their own script in
-.Nm /etc/rc.d ,
+.Pa /etc/rc.d/ ,
 which can be used to start, stop, and check the status of the service.
 .Pp
 Any architecture specific scripts, such as
@@ -463,8 +475,9 @@ Following tradition, all startup files reside in
 .Pa /etc .
 .Sh EXAMPLES
 The following is a minimal
-.Nm /etc/rc.d
-style script. Most scripts require little more than the following.
+.Nm rc.d/
+style script.
+Most scripts require little more than the following.
 .Bd -literal -offset indent
 #!/bin/sh
 #
@@ -474,7 +487,7 @@ style script. Most scripts require little more than the following.
 # BEFORE:  baz_service_requiring_foo_to_precede_it
 # KEYWORD: FreeBSD
 
-. /etc/rc.subr
+\&. /etc/rc.subr
 
 name="foo"
 rcvar=`set_rcvar`
@@ -484,9 +497,9 @@ load_rc_config $name
 run_rc_command "$1"
 .Ed
 .Pp
-Certain scripts may want to provide enhanced functionality. The
-user may access this functionality through additional commands. The
-script may list and define as many commands at it needs.
+Certain scripts may want to provide enhanced functionality.
+The user may access this functionality through additional commands.
+The script may list and define as many commands at it needs.
 .Bd -literal -offset indent
 #!/bin/sh
 #
@@ -496,7 +509,7 @@ script may list and define as many commands at it needs.
 # BEFORE:  baz_service_requiring_foo_to_precede_it
 # KEYWORD: FreeBSD
 
-. /etc/rc.subr
+\&. /etc/rc.subr
 
 name="foo"
 rcvar=`set_rcvar`
@@ -515,7 +528,7 @@ run_rc_command "$1"
 .Ed
 .Pp
 The following is a simple, hypothetical example of an old-style
-.Nm /usr/local/etc/rc.d
+.Pa /usr/local/etc/rc.d/
 script,
 which would start a daemon at boot time,
 and kill it at shutdown time.
@@ -542,6 +555,17 @@ As all processes are killed by
 at shutdown, the explicit
 .Xr kill 1
 is unnecessary, but is often included.
+.Sh FILES
+.Bl -tag -compact
+.It Pa /etc/rc
+.It Pa /etc/rc.conf
+.It Pa /etc/rc.conf.local
+.It Pa /etc/rc.d/
+.It Pa /etc/rc.firewall
+.It Pa /etc/rc.local
+.It Pa /etc/rc.shutdown
+.It Pa /etc/rc.subr
+.El
 .Sh SEE ALSO
 .Xr kill 1 ,
 .Xr rc.conf 5 ,
diff --git a/share/man/man8/rc.sendmail.8 b/share/man/man8/rc.sendmail.8
index 6eb2574..7b05ced 100644
--- a/share/man/man8/rc.sendmail.8
+++ b/share/man/man8/rc.sendmail.8
@@ -241,9 +241,11 @@ if (${sendmail_enable} != NONE &&
 endif
 .Ed
 .Pp
-To completely prevent any sendmail daemons from starting you must
+To completely prevent any
+.Xr sendmail 8
+daemons from starting, you must
 set the following variables in
-/etc/rc.conf:
+.Pa /etc/rc.conf :
 .Bd -literal -offset indent
 sendmail_enable="NO"
 sendmail_submit_enable="NO"