Manual pages: Standardize on EXAMPLE as section title
Subsystems (2)
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).)
Signed-off-by Michael Kerrisk <[email protected]>
--- 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/