util-linux.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 2/7] Manual pages: Standardize on EXAMPLE as section title
@ 2020-05-19 12:51 Michael Kerrisk (man-pages)
  0 siblings, 0 replies; only message in thread
From: Michael Kerrisk (man-pages) @ 2020-05-19 12:51 UTC (permalink / raw)
  To: Karel Zak; +Cc: mtk.manpages, util-linux

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 <mtk.manpages@gmail.com>
---
 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(-)

diff --git a/disk-utils/partx.8 b/disk-utils/partx.8
index d6ff52f08..e07787b10 100644
--- a/disk-utils/partx.8
+++ b/disk-utils/partx.8
@@ -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
diff --git a/lib/terminal-colors.d.5 b/lib/terminal-colors.d.5
index 4747ca268..73dff6a47 100644
--- a/lib/terminal-colors.d.5
+++ b/lib/terminal-colors.d.5
@@ -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
diff --git a/misc-utils/findmnt.8 b/misc-utils/findmnt.8
index 6fe35ab86..3e49c5be1 100644
--- a/misc-utils/findmnt.8
+++ b/misc-utils/findmnt.8
@@ -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 .
diff --git a/misc-utils/logger.1 b/misc-utils/logger.1
index e4a52228e..731695aed 100644
--- a/misc-utils/logger.1
+++ b/misc-utils/logger.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
diff --git a/misc-utils/rename.1 b/misc-utils/rename.1
index 7963a79b7..8067017f2 100644
--- a/misc-utils/rename.1
+++ b/misc-utils/rename.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
diff --git a/misc-utils/uuidgen.1 b/misc-utils/uuidgen.1
index 0189587a3..07d646104 100644
--- a/misc-utils/uuidgen.1
+++ b/misc-utils/uuidgen.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
diff --git a/misc-utils/wipefs.8 b/misc-utils/wipefs.8
index 8882ed84a..39e9c9f96 100644
--- a/misc-utils/wipefs.8
+++ b/misc-utils/wipefs.8
@@ -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.
diff --git a/schedutils/ionice.1 b/schedutils/ionice.1
index fa5c1ad19..0b2daba6c 100644
--- a/schedutils/ionice.1
+++ b/schedutils/ionice.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
diff --git a/sys-utils/chmem.8 b/sys-utils/chmem.8
index c0941ea70..c11514007 100644
--- a/sys-utils/chmem.8
+++ b/sys-utils/chmem.8
@@ -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.
diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index fba4ec8c0..abcbc73ee 100644
--- a/sys-utils/flock.1
+++ b/sys-utils/flock.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
diff --git a/sys-utils/pivot_root.8 b/sys-utils/pivot_root.8
index b1395e04f..ea98f3b3d 100644
--- a/sys-utils/pivot_root.8
+++ b/sys-utils/pivot_root.8
@@ -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
diff --git a/sys-utils/prlimit.1 b/sys-utils/prlimit.1
index 71dd7faa3..fb784377b 100644
--- a/sys-utils/prlimit.1
+++ b/sys-utils/prlimit.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"
diff --git a/sys-utils/readprofile.8 b/sys-utils/readprofile.8
index 9aef1bfba..7b7b2ab41 100644
--- a/sys-utils/readprofile.8
+++ b/sys-utils/readprofile.8
@@ -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
diff --git a/sys-utils/renice.1 b/sys-utils/renice.1
index 3ef3512f4..12a0f608d 100644
--- a/sys-utils/renice.1
+++ b/sys-utils/renice.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
diff --git a/sys-utils/rfkill.8 b/sys-utils/rfkill.8
index 0d37523bb..373af79ac 100644
--- a/sys-utils/rfkill.8
+++ b/sys-utils/rfkill.8
@@ -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
diff --git a/sys-utils/setarch.8 b/sys-utils/setarch.8
index a5e8b1f79..7040ac003 100644
--- a/sys-utils/setarch.8
+++ b/sys-utils/setarch.8
@@ -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
diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 86506ffa3..b22329d9e 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -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
diff --git a/term-utils/agetty.8 b/term-utils/agetty.8
index 1ad1cddff..c8d9796c5 100644
--- a/term-utils/agetty.8
+++ b/term-utils/agetty.8
@@ -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.
diff --git a/text-utils/colcrt.1 b/text-utils/colcrt.1
index dbfffb41d..341d34c83 100644
--- a/text-utils/colcrt.1
+++ b/text-utils/colcrt.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:
diff --git a/text-utils/column.1 b/text-utils/column.1
index e880f08b2..7ca8a8b31 100644
--- a/text-utils/column.1
+++ b/text-utils/column.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
diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
index 8e0b278a9..66ff157f7 100644
--- a/text-utils/hexdump.1
+++ b/text-utils/hexdump.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 "
-- 
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/

^ permalink raw reply related	[flat|nested] only message in thread
only message in thread, other threads:[~2020-05-19 12:51 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-19 12:51 [PATCH 2/7] Manual pages: Standardize on EXAMPLE as section title Michael Kerrisk (man-pages)

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).