From c83a52f03f3e9796a2454e6adb48c82cd70806d5 Mon Sep 17 00:00:00 2001 From: Rafael Fontenelle Date: Thu, 2 Sep 2021 10:20:35 -0300 Subject: [PATCH] docs: Uniformize references to section titles Wrap section title references with asterisks, and prioritize 'see the *TITLE* section' over 'see section TITLE'. --- disk-utils/cfdisk.8.adoc | 2 +- disk-utils/sfdisk.8.adoc | 2 +- lib/terminal-colors.d.5.adoc | 4 ++-- login-utils/login.1.adoc | 2 +- misc-utils/blkid.8.adoc | 2 +- misc-utils/cal.1.adoc | 2 +- misc-utils/getopt.1.adoc | 4 ++-- misc-utils/look.1.adoc | 2 +- sys-utils/lsmem.1.adoc | 2 +- sys-utils/mount.8.adoc | 4 ++-- sys-utils/prlimit.1.adoc | 2 +- sys-utils/rfkill.8.adoc | 2 +- sys-utils/unshare.1.adoc | 2 +- term-utils/agetty.8.adoc | 2 +- 14 files changed, 17 insertions(+), 17 deletions(-) diff --git a/disk-utils/cfdisk.8.adoc b/disk-utils/cfdisk.8.adoc index f1d0dc99d8..7d73f1cabe 100644 --- a/disk-utils/cfdisk.8.adoc +++ b/disk-utils/cfdisk.8.adoc @@ -48,7 +48,7 @@ If you want to remove an old partition table from a device, use *wipefs*(8). Display help text and exit. *-L*, *--color*[**=**__when__]:: -Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled, for the current built-in default see *--help* output. See also the COLORS section. +Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled, for the current built-in default see *--help* output. See also the *COLORS* section. *--lock*[=_mode_]:: Use exclusive BSD lock for device or file it operates. The optional argument _mode_ can be *yes*, *no* (or 1 and 0) or *nonblock*. If the _mode_ argument is omitted, it defaults to *"yes"*. This option overwrites environment variable *$LOCK_BLOCK_DEVICE*. The default is not to use any lock at all, but it's recommended to avoid collisions with udevd or other tools. diff --git a/disk-utils/sfdisk.8.adoc b/disk-utils/sfdisk.8.adoc index 091e591209..9c45fd3484 100644 --- a/disk-utils/sfdisk.8.adoc +++ b/disk-utils/sfdisk.8.adoc @@ -71,7 +71,7 @@ If no _partition-number_ is specified, then list the partitions with an enabled Delete all or the specified partitions. *-d*, *--dump* _device_:: -Dump the partitions of a device in a format that is usable as input to *sfdisk*. See the section *BACKING UP THE PARTITION TABLE*. +Dump the partitions of a device in a format that is usable as input to *sfdisk*. See the *BACKING UP THE PARTITION TABLE* section. *-g*, *--show-geometry* [__device__...]:: List the geometry of all or the specified devices. For backward compatibility the deprecated option *--show-pt-geometry* have the same meaning as this one. diff --git a/lib/terminal-colors.d.5.adoc b/lib/terminal-colors.d.5.adoc index 2332b1d3db..797ae782b7 100644 --- a/lib/terminal-colors.d.5.adoc +++ b/lib/terminal-colors.d.5.adoc @@ -53,7 +53,7 @@ ____ *name color-sequence* ____ -The *name* is a logical name of color sequence (for example "error"). The names are specific to the utilities. For more details always see the COLORS section in the man page for the utility. +The *name* is a logical name of color sequence (for example "error"). The names are specific to the utilities. For more details always see the *COLORS* section in the man page for the utility. The *color-sequence* is a color name, ASCII color sequences or escape sequences. @@ -163,7 +163,7 @@ ____ == COMPATIBILITY -The terminal-colors.d functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the COLORS section in the man page for the utility. +The terminal-colors.d functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the *COLORS* section in the man page for the utility. include::man-common/bugreports.adoc[] diff --git a/login-utils/login.1.adoc b/login-utils/login.1.adoc index 412b85dd21..bcc5847c92 100644 --- a/login-utils/login.1.adoc +++ b/login-utils/login.1.adoc @@ -22,7 +22,7 @@ login - begin session on the system *login* is used when signing onto a system. If no argument is given, *login* prompts for the username. -The user is then prompted for a password, where appropriate. Echoing is disabled to prevent revealing the password. Only a number of password failures are permitted before *login* exits and the communications link is severed. See *LOGIN_RETRIES* in CONFIG FILE ITEMS section. +The user is then prompted for a password, where appropriate. Echoing is disabled to prevent revealing the password. Only a number of password failures are permitted before *login* exits and the communications link is severed. See *LOGIN_RETRIES* in the *CONFIG FILE ITEMS* section. If password aging has been enabled for the account, the user may be prompted for a new password before proceeding. In such case old password must be provided and the new password entered before continuing. Please refer to *passwd*(1) for more information. diff --git a/misc-utils/blkid.8.adoc b/misc-utils/blkid.8.adoc index e178418ec7..85e7723809 100644 --- a/misc-utils/blkid.8.adoc +++ b/misc-utils/blkid.8.adoc @@ -44,7 +44,7 @@ For security reasons *blkid* silently ignores all devices where the probing resu The _size_ and _offset_ arguments may be followed by the multiplicative suffixes like KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. *-c*, *--cache-file* _cachefile_:: -Read from _cachefile_ instead of reading from the default cache file (see the CONFIGURATION FILE section for more details). If you want to start with a clean cache (i.e., don't report devices previously scanned but not necessarily available at this time), specify _/dev/null_. +Read from _cachefile_ instead of reading from the default cache file (see the *CONFIGURATION FILE* section for more details). If you want to start with a clean cache (i.e., don't report devices previously scanned but not necessarily available at this time), specify _/dev/null_. *-d*, *--no-encoding*:: Don't encode non-printing characters. The non-printing characters are encoded by ^ and M- notation by default. Note that the *--output udev* output format uses a different encoding which cannot be disabled. diff --git a/misc-utils/cal.1.adoc b/misc-utils/cal.1.adoc index 0a2686d283..885c099016 100644 --- a/misc-utils/cal.1.adoc +++ b/misc-utils/cal.1.adoc @@ -112,7 +112,7 @@ Display a calendar for the whole year. Display a calendar for the next twelve months. *-w*, *--week*[=_number_]:: -Display week numbers in the calendar (US or ISO-8601). See NOTES section for more details. +Display week numbers in the calendar (US or ISO-8601). See the *NOTES* section for more details. *--color*[=_when_]:: Colorize the output. The optional argument _when_ can be *auto*, *never* or *always*. If the _when_ argument is omitted, it defaults to *auto*. The colors can be disabled; for the current built-in default see the *--help* output. See also the *COLORS* section. diff --git a/misc-utils/getopt.1.adoc b/misc-utils/getopt.1.adoc index 1b44b20765..6cbdd51748 100644 --- a/misc-utils/getopt.1.adoc +++ b/misc-utils/getopt.1.adoc @@ -23,7 +23,7 @@ getopt - parse command options (enhanced) The parameters *getopt* is called with can be divided into two parts: options which modify the way *getopt* will do the parsing (the _options_ and the _optstring_ in the *SYNOPSIS*), and the parameters which are to be parsed (_parameters_ in the *SYNOPSIS*). The second part will start at the first non-option parameter that is not an option argument, or after the first occurrence of '*--*'. If no '*-o*' or '*--options*' option is found in the first part, the first parameter of the second part is used as the short options string. -If the environment variable *GETOPT_COMPATIBLE* is set, or if the first _parameter_ is not an option (does not start with a '*-*', the first format in the *SYNOPSIS*), *getopt* will generate output that is compatible with that of other versions of *getopt*(1). It will still do parameter shuffling and recognize optional arguments (see section *COMPATIBILITY* for more information). +If the environment variable *GETOPT_COMPATIBLE* is set, or if the first _parameter_ is not an option (does not start with a '*-*', the first format in the *SYNOPSIS*), *getopt* will generate output that is compatible with that of other versions of *getopt*(1). It will still do parameter shuffling and recognize optional arguments (see the *COMPATIBILITY* section for more information). Traditional implementations of *getopt*(1) are unable to cope with whitespace and other (shell-specific) special characters in arguments and non-option parameters. To solve this problem, this implementation can generate quoted output which must once again be interpreted by the shell (usually by using the *eval* command). This has the effect of preserving those characters, but you must call *getopt* in a way that is no longer compatible with other versions (the second or third format in the *SYNOPSIS*). To determine whether this enhanced version of *getopt*(1) is installed, a special test option (*-T*) can be used. @@ -42,7 +42,7 @@ The long (multi-character) options to be recognized. More than one option name m The name that will be used by the *getopt*(3) routines when it reports errors. Note that errors of *getopt*(1) are still reported as coming from getopt. *-o*, *--options* _shortopts_:: -The short (one-character) options to be recognized. If this option is not found, the first parameter of *getopt* that does not start with a '*-*' (and is not an option argument) is used as the short options string. Each short option character in _shortopts_ may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument. The first character of shortopts may be '*{plus}*' or '*-*' to influence the way options are parsed and output is generated (see section *SCANNING MODES* for details). +The short (one-character) options to be recognized. If this option is not found, the first parameter of *getopt* that does not start with a '*-*' (and is not an option argument) is used as the short options string. Each short option character in _shortopts_ may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument. The first character of shortopts may be '*{plus}*' or '*-*' to influence the way options are parsed and output is generated (see the *SCANNING MODES* section for details). //TRANSLATORS: Keep {plus} untranslated. *-q*, *--quiet*:: diff --git a/misc-utils/look.1.adoc b/misc-utils/look.1.adoc index e4d798e675..29f5ad7da6 100644 --- a/misc-utils/look.1.adoc +++ b/misc-utils/look.1.adoc @@ -81,7 +81,7 @@ The *look* utility exits 0 if one or more lines were found and displayed, 1 if n == ENVIRONMENT *WORDLIST*:: -Path to a dictionary file. The environment variable has greater priority than the dictionary path defined in FILES segment. +Path to a dictionary file. The environment variable has greater priority than the dictionary path defined in the *FILES* segment. == FILES diff --git a/sys-utils/lsmem.1.adoc b/sys-utils/lsmem.1.adoc index 4ead07a997..5a97f40124 100644 --- a/sys-utils/lsmem.1.adoc +++ b/sys-utils/lsmem.1.adoc @@ -58,7 +58,7 @@ Produce output in the form of key="value" pairs. All potentially unsafe value ch Produce output in raw format. All potentially unsafe characters are hex-escaped (\x). *-S*, *--split* _list_:: -Specify which columns (attributes) use to split memory blocks to ranges. The supported columns are STATE, REMOVABLE, NODE and ZONES, or "none". The other columns are silently ignored. For more details see DESCRIPTION above. +Specify which columns (attributes) use to split memory blocks to ranges. The supported columns are STATE, REMOVABLE, NODE and ZONES, or "none". The other columns are silently ignored. For more details see *DESCRIPTION* above. *-s*, *--sysroot* _directory_:: Gather memory data for a Linux instance other than the instance from which the *lsmem* command is issued. The specified _directory_ is the system root of the Linux instance to be inspected. diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index fff6c7c2f7..afdcc7cf63 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -294,7 +294,7 @@ mount --make-unbindable /foo The full set of mount options used by an invocation of *mount* is determined by first extracting the mount options for the filesystem from the _fstab_ table, then applying any options specified by the *-o* argument, and finally applying a *-r* or *-w* option, when present. -The *mount* command does not pass all command-line options to the **/sbin/mount.**__suffix__ mount helpers. The interface between *mount* and the mount helpers is described below in the section *EXTERNAL HELPERS*. +The *mount* command does not pass all command-line options to the **/sbin/mount.**__suffix__ mount helpers. The interface between *mount* and the mount helpers is described below in the *EXTERNAL HELPERS* section. Command-line options available for the *mount* command are: @@ -1230,7 +1230,7 @@ If *dmode=* is set the permissions of all directory inodes read from the filesys *bs=*:: Set the block size. Default value prior to kernel version 2.6.30 was 2048. Since 2.6.30 and prior to 4.11 it was logical device block size with fallback to 2048. Since 4.11 it is logical block size with fallback to any valid block size between logical device block size and 4096. + -For other details see the *mkudffs*(8) 2.0+ manpage, sections *COMPATIBILITY* and *BLOCK SIZE*. +For other details see the *mkudffs*(8) 2.0+ manpage, see the *COMPATIBILITY* and *BLOCK SIZE* sections. *unhide*:: Show otherwise hidden files. diff --git a/sys-utils/prlimit.1.adoc b/sys-utils/prlimit.1.adoc index fcc3c51061..51b2f853c8 100644 --- a/sys-utils/prlimit.1.adoc +++ b/sys-utils/prlimit.1.adoc @@ -30,7 +30,7 @@ When _command_ is given, *prlimit* will run this command with the given argument The _limits_ parameter is composed of a soft and a hard value, separated by a colon (:), in order to modify the existing values. If no _limits_ are given, *prlimit* will display the current values. If one of the values is not given, then the existing one will be used. To specify the unlimited or infinity limit (*RLIM_INFINITY*), the -1 or 'unlimited' string can be passed. -Because of the nature of limits, the soft limit must be lower or equal to the high limit (also called the ceiling). To see all available resource limits, refer to the RESOURCE OPTIONS section. +Because of the nature of limits, the soft limit must be lower or equal to the high limit (also called the ceiling). To see all available resource limits, refer to the *RESOURCE OPTIONS* section. //TRANSLATORS: Keep {colon} untranslated. * _soft_{colon}_hard_ Specify both limits. diff --git a/sys-utils/rfkill.8.adoc b/sys-utils/rfkill.8.adoc index 49bb8ed585..426583ae90 100644 --- a/sys-utils/rfkill.8.adoc +++ b/sys-utils/rfkill.8.adoc @@ -54,7 +54,7 @@ Display help text and exit. Listen for rfkill events and display them on stdout. *list* [__id__|_type_ ...]:: -List the current state of all available devices. The command output format is deprecated, see the section DESCRIPTION. It is a good idea to check with *list* command _id_ or _type_ scope is appropriate before setting *block* or *unblock*. Special _all_ type string will match everything. Use of multiple _ID_ or _type_ arguments is supported. +List the current state of all available devices. The command output format is deprecated, see the *DESCRIPTION* section. It is a good idea to check with *list* command _id_ or _type_ scope is appropriate before setting *block* or *unblock*. Special _all_ type string will match everything. Use of multiple _ID_ or _type_ arguments is supported. **block id**|*type* [...]:: Disable the corresponding device. diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index f0fdf506f5..5f43ffaa15 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -18,7 +18,7 @@ unshare - run program in new namespaces The *unshare* command creates new namespaces (as specified by the command-line options described below) and then executes the specified _program_. If _program_ is not given, then "${SHELL}" is run (default: _/bin/sh_). -By default, a new namespace persists only as long as it has member processes. A new namespace can be made persistent even when it has no member processes by bind mounting /proc/_pid_/ns/_type_ files to a filesystem path. A namespace that has been made persistent in this way can subsequently be entered with *nsenter*(1) even after the _program_ terminates (except PID namespaces where a permanently running init process is required). Once a persistent namespace is no longer needed, it can be unpersisted by using *umount*(8) to remove the bind mount. See the EXAMPLES section for more details. +By default, a new namespace persists only as long as it has member processes. A new namespace can be made persistent even when it has no member processes by bind mounting /proc/_pid_/ns/_type_ files to a filesystem path. A namespace that has been made persistent in this way can subsequently be entered with *nsenter*(1) even after the _program_ terminates (except PID namespaces where a permanently running init process is required). Once a persistent namespace is no longer needed, it can be unpersisted by using *umount*(8) to remove the bind mount. See the *EXAMPLES* section for more details. *unshare* since util-linux version 2.36 uses _/proc/[pid]/ns/pid_for_children_ and _/proc/[pid]/ns/time_for_children_ files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer. diff --git a/term-utils/agetty.8.adoc b/term-utils/agetty.8.adoc index aeb902cb56..f75a12f25f 100644 --- a/term-utils/agetty.8.adoc +++ b/term-utils/agetty.8.adoc @@ -130,7 +130,7 @@ Options and arguments that are passed to *login*(1). Where \u is replaced by the + See *--autologin*, *--login-program* and *--remote*. + -Please read the SECURITY NOTICE below before using this option. +Please read the *SECURITY NOTICE* below before using this option. *-p*, *--login-pause*:: Wait for any key before dropping to the login prompt. Can be combined with *--autologin* to save memory by lazily spawning shells. -- 2.47.2