Skip to contentSkip to conversation

Manual pages: Standardize on EXAMPLE as section title

PATCH In review Michael Kerrisk (man-pages) 1 participant 1 message May 19, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 2/7 Manual pages: Standardize on EXAMPLE as section title

There is quite some value (in terms of readability and user expectations) if consistent names are used for the sections within manual pages. This patch is one of a series to bring about this consistency.

Currently we have EXAMPLE (10) or EXAMPLES (23). Let's standardize on the EXAMPLE (which is also what is suggested in man-pages(7)) and used consistently across a large number of pages in the Linux man-pages project.

(I realize the choice to go EXAMPLE, rather than EXAMPLES, may be debatable. If necessary, I'd write a patch that instead goes the other way, but I'd prefer to follow man-pages(7).)

---
 disk-utils/partx.8      | 2 +-
 lib/terminal-colors.d.5 | 2 +-
 misc-utils/findmnt.8    | 2 +-
 misc-utils/logger.1     | 2 +-
 misc-utils/rename.1     | 2 +-
 misc-utils/uuidgen.1    | 2 +-
 misc-utils/wipefs.8     | 4 ++--
 schedutils/ionice.1     | 2 +-
 sys-utils/chmem.8       | 2 +-
 sys-utils/flock.1       | 2 +-
 sys-utils/pivot_root.8  | 2 +-
 sys-utils/prlimit.1     | 2 +-
 sys-utils/readprofile.8 | 2 +-
 sys-utils/renice.1      | 2 +-
 sys-utils/rfkill.8      | 2 +-
 sys-utils/setarch.8     | 2 +-
 sys-utils/unshare.1     | 4 ++--
 term-utils/agetty.8     | 2 +-
 text-utils/colcrt.1     | 2 +-
 text-utils/column.1     | 2 +-
 text-utils/hexdump.1    | 2 +-
 21 files changed, 23 insertions(+), 23 deletions(-)
disk-utils/partx.8 +1 -1
index d6ff52f08..e07787b10 100644
@@ -144,7 +144,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 .TP
 partx \-\-show /dev/sdb3
 .TQ
lib/terminal-colors.d.5 +1 -1
index 4747ca268..73dff6a47 100644
@@ -50,7 +50,7 @@ or
 .I $HOME/.config/terminal-colors.d
 overrides the global setting.
 
-.SH EXAMPLES
+.SH EXAMPLE
 Disable colors for all compatible utilities:
 .RS
 .br
misc-utils/findmnt.8 +1 -1
index 6fe35ab86..3e49c5be1 100644
@@ -260,7 +260,7 @@ It's possible to specify source (device) or target (mountpoint) to filter mount
 .TP
 .B \-\-verbose
 Force findmnt to print more information (\fB\-\-verify\fP only for now).
-.SH EXAMPLES
+.SH EXAMPLE
 .IP "\fBfindmnt \-\-fstab \-t nfs\fP"
 Prints all NFS filesystems defined in
 .IR /etc/fstab .
misc-utils/logger.1 +1 -1
index e4a52228e..731695aed 100644
@@ -345,7 +345,7 @@ l l.
 .PP
 For the priority order and intended purposes of these facilities and levels, see
 .BR syslog (3).
-.SH EXAMPLES
+.SH EXAMPLE
 .B logger System rebooted
 .br
 .B logger \-p local0.notice \-t HOSTIDM \-f /dev/idmc
misc-utils/rename.1 +1 -1
index 7963a79b7..8067017f2 100644
@@ -40,7 +40,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 Given the files
 .IR foo1 ", ..., " foo9 ", " foo10 ", ..., " foo278 ,
 the commands
misc-utils/uuidgen.1 +1 -1
index 0189587a3..07d646104 100644
@@ -89,7 +89,7 @@ Generate the hash of the \fIname\fR.
 Interpret name \fIname\fR as a hexadecimal string.
 .SH CONFORMING TO
 OSF DCE 1.1
-.SH EXAMPLES
+.SH EXAMPLE
 uuidgen \-\-sha1 \-\-namespace @dns \-\-name "www.example.com"
 .SH AUTHORS
 .B uuidgen
misc-utils/wipefs.8 +2 -2
index 8882ed84a..39e9c9f96 100644
@@ -65,7 +65,7 @@ restricted with the \fB\-t\fR option.
 .TP
 .BR \-b , " \-\-backup"
 Create a signature backup to the file $HOME/wipefs-<devname>-<offset>.bak.
-For more details see the \fBEXAMPLES\fR section.
+For more details see the \fBEXAMPLE\fR section.
 .TP
 .BR \-f , " \-\-force"
 Force erasure, even if the filesystem is mounted.  This is required in
@@ -112,7 +112,7 @@ taken.  For more details see mount(8).
 .TP
 .BR \-V , " \-\-version"
 Display version information and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 .TP
 .B wipefs /dev/sda*
 Prints information about sda and all partitions on sda.
schedutils/ionice.1 +1 -1
index fa5c1ad19..0b2daba6c 100644
@@ -113,7 +113,7 @@ scheduling parameters.
 .TP
 .BR \-V , " \-\-version"
 Display version information and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 .LP
 .TP 7
 # \fBionice\fP \-c 3 \-p 89
sys-utils/chmem.8 +1 -1
index c0941ea70..c11514007 100644
@@ -91,7 +91,7 @@ failure
 .TP
 .B 64
 partial success
-.SH EXAMPLES
+.SH EXAMPLE
 .TP
 .B chmem \-\-enable 1024
 This command requests 1024 MiB of memory to be set online.
sys-utils/flock.1 +1 -1
index fba4ec8c0..abcbc73ee 100644
@@ -124,7 +124,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 Note that "shell> " in examples is a command line prompt.
 .TP
 shell1> flock /tmp \-c cat
sys-utils/pivot_root.8 +1 -1
index b1395e04f..ea98f3b3d 100644
@@ -39,7 +39,7 @@ Display version information and exit.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 Change the root file system to /dev/hda1 from an interactive shell:
 .sp
 .nf
sys-utils/prlimit.1 +1 -1
index 71dd7faa3..fb784377b 100644
@@ -89,7 +89,7 @@ Maximum number of file locks held.
 .IP "\fB\-y, \-\-rttime\fP[=\fIlimits\fR]"
 Timeout for real-time tasks.
 
-.SH EXAMPLES
+.SH EXAMPLE
 .IP "\fBprlimit \-\-pid 13134\fP"
 Display limit values for all current resources.
 .IP "\fBprlimit \-\-pid 13134 \-\-rss \-\-nofile=1024:4095\fP"
sys-utils/readprofile.8 +1 -1
index 9aef1bfba..7b7b2ab41 100644
@@ -90,7 +90,7 @@ Display version information and exit.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 Browse the profiling buffer ordering by clock ticks:
 .nf
    readprofile | sort \-nr | less
sys-utils/renice.1 +1 -1
index 3ef3512f4..12a0f608d 100644
@@ -77,7 +77,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 The following command would change the priority of the processes with
 PIDs 987 and 32, plus all processes owned by the users daemon and root:
 .TP
sys-utils/rfkill.8 +1 -1
index 0d37523bb..373af79ac 100644
@@ -74,7 +74,7 @@ Disable the corresponding device.
 Enable the corresponding device.  If the device is hard\-blocked, for example
 via a hardware switch, it will remain unavailable though it is now
 soft\-unblocked.
-.SH EXAMPLES
+.SH EXAMPLE
 rfkill --output ID,TYPE
 .br
 rfkill block all
sys-utils/setarch.8 +1 -1
index a5e8b1f79..7040ac003 100644
@@ -113,7 +113,7 @@ Display version information and exit.
 .TP
 .BR \-h , " \-\-help"
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 setarch \-\-addr-no-randomize mytestprog
 .br
 setarch ppc32 rpmbuild \-\-target=ppc \-\-rebuild foo.src.rpm
sys-utils/unshare.1 +2 -2
index 86506ffa3..b22329d9e 100644
@@ -18,7 +18,7 @@ even after the \fIprogram\fR terminates (except PID namespaces where
 permanently running init process is required).
 Once a persistent \%namespace is no longer needed, it can be unpersisted with
 .BR umount (8).
-See the \fBEXAMPLES\fR section for more details.
+See the \fBEXAMPLE\fR section for more details.
 .PP
 .B unshare
 since util-linux version 2.36 uses /\fIproc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP
@@ -259,7 +259,7 @@ The proc and sysfs filesystems mounting as root in a user namespace have to be
 restricted so that a less privileged user can not get more access to sensitive
 files that a more privileged user made unavailable. In short the rule for proc
 and sysfs is as close to a bind mount as possible.
-.SH EXAMPLES
+.SH EXAMPLE
 .TP
 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
 .TQ
term-utils/agetty.8 +1 -1
index 1ad1cddff..c8d9796c5 100644
@@ -305,7 +305,7 @@ Display version information and exit.
 \-\-help
 Display help text and exit.
 .PP
-.SH EXAMPLES
+.SH EXAMPLE
 This section shows examples for the process field of an entry in the
 \fI/etc/inittab\fP file.  You'll have to prepend appropriate values
 for the other fields.  See \fIinittab(5)\fP for more details.
text-utils/colcrt.1 +1 -1
index dbfffb41d..341d34c83 100644
@@ -66,7 +66,7 @@ Display version information and exit.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Display help text and exit.
-.SH EXAMPLES
+.SH EXAMPLE
 A typical use of
 .B colcrt
 would be:
text-utils/column.1 +1 -1
index e880f08b2..7ca8a8b31 100644
@@ -126,7 +126,7 @@ Display help text and exit.
 .SH ENVIRONMENT
 The environment variable \fBCOLUMNS\fR is used to determine the size of
 the screen if no other information is available.
-.SH EXAMPLES
+.SH EXAMPLE
 Print fstab with header line and align number to the right:
 .EX
 \fBsed 's/#.*//' /etc/fstab | column \-\-table \-\-table-columns SOURCE,TARGET,TYPE,OPTIONS,PASS,FREQ \-\-table-right PASS,FREQ\fR
text-utils/hexdump.1 +1 -1
index 8e0b278a9..66ff157f7 100644
@@ -343,7 +343,7 @@ used between format units than in the default output).
 .SH EXIT STATUS
 .B hexdump
 exits 0 on success and >0 if an error occurred.
-.SH EXAMPLES
+.SH EXAMPLE
 Display the input in perusal format:
 .nf
    "%06.6_ao "  12/1 "%3_u "
Signature · 6 lines
2.26.2

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/