Date: Sun, 12 Oct 2003 19:43:51 -0600 (MDT) From: Kazuo Horikawa <horikawa@FreeBSD.org> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/57926: amd.conf.5 poorly format as it has both man(7) and mdoc(7) Message-ID: <20031012.194351.74754956.horikawa@attbi.com> Resent-Message-ID: <200310130150.h9D1oClv067592@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 57926
>Category: docs
>Synopsis: amd.conf.5 poorly format as it has both man(7) and mdoc(7)
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Oct 12 18:50:12 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Kazuo Horikawa
>Release: FreeBSD 5.1-RELEASE i386
>Organization:
jpman project
>Environment:
amd.conf.5 comes with 5.1-CURRENT-20031005-JPSNAP
>Description:
Revision 1.14 of src/contrib/amd/scripts/amd.conf.5
has some man(7) macros while the most of this file is written
in mdoc(7).
The result is lines marked up with man(7) are poorly formatted.
>How-To-Repeat:
$ gzcat /usr/share/man/man5/amd.conf.5.gz | \
/usr/bin/groff -mandoc -Tascii -mtty-char -z -ww
<standard input>:128: warning: macro `BR' not defined
<standard input>:131: warning: macro `I' not defined
[snip]
>Fix:
Apply the following diff to src/contrib/amd/scripts/amd.conf.5.
--- amd.conf.5.bak Sun Oct 12 18:37:36 2003
+++ amd.conf.5 Sun Oct 12 19:38:17 2003
@@ -121,56 +121,99 @@
calls. This means you could run for example
.Xr ls 1
and see what keys are available to mount in that directory. Not all entries
-are made visible to readdir(3): the "/default" entry, wildcard
-entries, and those with a "/" in them are not included. If you specify
-"full" to this option, all but "/default" will be visible.
+are made visible to
+.Xr readdir 3 :
+the
+.Qq Pa /default
+entry, wildcard entries, and those with a
+.Qq Pa /
+in them are not included.
+If you specify
+.Qq full
+to this option, all but
+.Qq Pa /default
+will be visible.
Note that if you run a command which will attempt to
-.BR stat (2)
-the entries, such as often done by "ls -l" or "ls -F", amd will attempt to
-mount
-.I every
-entry in that map. This is often called a ``mount storm''.
-
-.TP
-.BR map_options " (string, default no options)"
+.Xr stat 2
+the entries, such as often done by
+.Qq ls -l
+or
+.Qq ls -F ,
+.Nm amd
+will attempt to mount
+.Em every
+entry in that map.
+This is often called a
+.Em mount storm .
+.It Ic map_options Xo
+(string, default no options)
+.Xc
This option is the same as specifying map options on the command line to
-amd, such as "cache:=all".
-
-.TP
-.BR map_type " (string, default search all map types)"
-If specified, amd will initialize the map only for the type given. This is
+.Nm amd ,
+such as
+.Ql cache\&:\&=all .
+.It Ic map_type Xo
+(string, default search all map types)
+.Xc
+If specified, amd will initialize the map only for the type given.
+This is
useful to avoid the default map search type used by amd which takes longer
and can have undesired side-effects such as initializing NIS even if not
-used. Possible values are
-
-.nf
-\fBfile\fR plain files
-\fBhesiod\fR Hesiod name service from MIT
-\fBldap\fR Lightweight Directory Access Protocol
-\fBndbm\fR (New) dbm style hash files
-\fBnis\fR Network Information Services (version 2)
-\fBnisplus\fR Network Information Services Plus (version 3)
-\fBpasswd\fR local password files
-\fBunion\fR union maps
-.fi
-
-.TP
-.BR mount_type " (string, default=nfs)"
-All amd mount types must be NFS. That is, amd is an NFS server on the
-map mount points, for the local host it is running on. If "autofs" is
-specified, amd will log an error and convert it to NFS.
-
-.TP
-.BR search_path " (string, default no search path)"
-This provides a (colon-delimited) search path for file maps. Using a search
+used.
+Possible values are
+.Pp
+.Bl -tag -width "nisplus" -compact
+.It Ic file
+plain files
+.It Ic hesiod
+Hesiod name service from MIT
+.It Ic ldap
+Lightweight Directory Access Protocol
+.It Ic ndbm
+(New) dbm style hash files
+.It Ic nis
+Network Information Services (version 2)
+.It Ic nisplus
+Network Information Services Plus (version 3)
+.It Ic passwd
+local password files
+.It Ic union
+union maps
+.El
+.It Ic mount_type Xo
+(string, default=nfs)
+.Xc
+All
+.Nm amd
+mount types must be
+.Tn NFS .
+That is,
+.Nm amd
+is an
+.Tn NFS
+server on the
+map mount points, for the local host it is running on.
+If
+.Qq autofs
+is specified,
+.Nm amd
+will log an error and convert it to
+.Tn NFS .
+.It Ic search_path Xo
+(string, default no search path)
+.Xc
+This provides a
+(colon-delimited)
+search path for file maps.
+Using a search
path, sites can allow for local map customizations and overrides, and can
distributed maps in several locations as needed.
-
-.\" **************************************************************************
-.SS Parameters applicable to the global section only
-
-.TP
-.BR arch " (string, default to compiled in value)"
+.El
+.Ss "Parameters applicable to the global section only"
+.Bl -tag -width 4n
+.It Ic arch Xo
+(string, default to compiled in value)
+.Xc
Allows you to override the value of the
.Va arch
.Nm amd
@@ -410,7 +453,7 @@
(numeric, default=110)
.Xc
Same as the
-.Ic counter
+.Ar counter
part of the
.Fl t Ar interval.counter
option to
@@ -420,97 +463,162 @@
(numeric, default=8)
.Xc
Same as the
-.B \-x
-option to amd. Specify any logging options for amd. Options are comma
-delimited, and can be preceded by the string "no" to negate their meaning.
-The "debug" logging option is only available if am-utils was configured with
---enable-debug. You can get the list of supported debugging and logging
-options by running amd \-H. Possible values are:
-
-.nf
-\fBall\fR all messages
-\fBdebug\fR debug messages
-\fBerror\fR non-fatal system errors
-\fBfatal\fR fatal errors
-\fBinfo\fR information
-\fBmap\fR map errors
-\fBstats\fR additional statistical information
-\fBuser\fR non-fatal user errors
-\fBwarn\fR warnings
-\fBwarning\fR warnings
-.fi
-
-.TP
-.BR nfs_vers " (numeric, default to trying version 3 then 2)"
-By default, amd tries version 3 and then version 2. This option forces the
-overall NFS protocol used to version 3 or 2. It overrides what is in the
+.Fl x
+option to
+.Nm amd .
+Specify any logging options for
+.Nm amd .
+Options are comma
+delimited, and can be preceded by the string
+.Qq no
+to negate their meaning.
+The
+.Qq debug
+logging option is only available if am-utils was configured with
+--enable-debug.
+You can get the list of supported debugging and logging
+options by running
+.Nm amd Fl H .
+Possible values are:
+.Pp
+.Bl -tag -width "warning" -compact
+.It Ic all
+all messages
+.It Ic debug
+debug messages
+.It Ic error
+non-fatal system errors
+.It Ic fatal
+fatal errors
+.It Ic info
+information
+.It Ic map
+map errors
+.It Ic stats
+additional statistical information
+.It Ic user
+non-fatal user errors
+.It Ic warn
+warnings
+.It Ic warning
+warnings
+.El
+.It Ic nfs_vers Xo
+(numeric, default to trying version 3 then 2)
+.Xc
+By default,
+.Nm amd
+tries version 3 and then version 2.
+This option forces the
+overall
+.Tn NFS
+protocol used to version 3 or 2.
+It overrides what is in the
amd maps, and is useful when amd is compiled with NFSv3 support that may not
-be stable. With this option you can turn off the complete usage of NFSv3
+be stable.
+With this option you can turn off the complete usage of NFSv3
dynamically (without having to recompile amd) until such time as NFSv3
support is desired again.
-
-.TP
-.BR nfs_retransmit_counter " (numeric, default=11)"
+.It Ic nfs_retransmit_counter Xo
+(numeric, default=11)
+.Xc
Same as the
-.I retransmit
+.Ar retransmit
part of the
-.BI \-t " timeout.retransmit"
-option to amd.
-Specifies the number of NFS retransmissions that the kernel will use to
-communicate with amd.
-
-.TP
-.BR nfs_retry_interval " (numeric, default=8)"
+.Fl t Ar timeout.retransmit
+option to
+.Nm amd .
+Specifies the number of
+.Tn NFS
+retransmissions that the kernel will use to
+communicate with
+.Nm amd .
+.It Ic nfs_retry_interval Xo
+(numeric, default=8)
+.Xc
Same as the
-.I timeout
+.Ar timeout
part of the
-.BI \-t " timeout.retransmit"
-option to amd. Specifies the NFS timeout interval, in
-.I tenths
-of seconds, between NFS/RPC retries (for UDP only).
+.Fl t Ar timeout.retransmit
+option to
+.Nm amd .
+Specifies the
+.Tn NFS
+timeout interval, in
+.Em tenths
+of seconds, between NFS/RPC
+retries (for UDP only).
This is the value that the kernel will use to
-communicate with amd.
-
-Amd relies on the kernel RPC retransmit mechanism to trigger mount retries.
+communicate with
+.Nm amd .
+.Pp
+.Nm Amd
+relies on the kernel RPC retransmit mechanism to trigger mount retries.
The values of the
-.B nfs_retransmit_counter
+.Ar nfs_retransmit_counter
and the
-.B nfs_retry_interval
-parameters change the overall retry interval. Too long an interval gives
+.Ar nfs_retry_interval
+parameters change the overall retry interval.
+Too long an interval gives
poor interactive response; too short an interval causes excessive retries.
-
-.TP
-.BR nfs_proto " (string, default to trying version tcp then udp)"
-By default, amd tries TCP and then UDP. This option forces the overall NFS
-protocol used to TCP or UDP. It overrides what is in the amd maps, and is
-useful when amd is compiled with NFSv3 support that may not be stable. With
+.It Ic nfs_proto Xo
+(string, default to trying version tcp then udp)
+.Xc
+By default,
+.Nm amd
+tries TCP and then UDP.
+This option forces the overall
+.Tn NFS
+protocol used to TCP or UDP.
+It overrides what is in the amd maps, and is
+useful when amd is compiled with NFSv3 support that may not be stable.
+With
this option you can turn off the complete usage of NFSv3 dynamically
(without having to recompile amd) until such time as NFSv3 support is
desired again.
-
-.TP
-.BR nis_domain " (string, default to local NIS domain name)"
-Same as the
-.B \-y
-option to amd. Specify an alternative NIS domain from which to fetch the
-NIS maps. The default is the system domain name. This option is ignored if
-NIS support is not available.
-
-.TP
-.BR normalize_hostnames " (boolean, default=no)"
-Same as the
-.B \-n
-option to amd. If "yes", then the name refereed to by ${rhost} is
-normalized relative to the host database before being used. The effect is
-to translate aliases into ``official'' names.
-
-.TP
-.BR os " (string, default to compiled in value)"
-Same as the
-.B \-O
-option to amd. Allows you to override the compiled-in name of the operating
-system. Useful when the built-in name is not desired for backward
-compatibility reasons. For example, if the build in name is
+.It Ic nis_domain Xo
+(string, default to local NIS domain name)
+.Xc
+Same as the
+.Fl y
+option to
+.Nm amd .
+Specify an alternative
+.Tn NIS
+domain from which to fetch the
+.Tn NIS
+maps.
+The default is the system domain name.
+This option is ignored if
+.Tn NIS
+support is not available.
+.It Ic normalize_hostnames Xo
+(boolean, default=no)
+.Xc
+Same as the
+.Fl n
+option to
+.Nm amd .
+If
+.Qq yes ,
+then the name refereed to by
+.Va ${rhost}
+is normalized relative to the host database before being used.
+The effect is
+to translate aliases into
+.Qq official
+names.
+.It Ic os Xo
+(string, default to compiled in value)
+.Xc
+Same as the
+.Fl O
+option to
+.Nm amd .
+Allows you to override the compiled-in name of the operating system.
+Useful when the built-in name is not desired for backward
+compatibility reasons.
+For example, if the build in name is
.Dq sunos5 ,
you can override it to
.Dq sos5 ,
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20031012.194351.74754956.horikawa>