[PATCH 50/61] Relocate "EXAMPLES" sections nearer the distal ends of man pages.

[G. Branden Robinson]

Place them where the Linux man-pages(7) document recommends.  Such
advice is not binding on other projects, but with literally thousands of
man pages under development over 3 decades, some wisdom has accumulated
there.

(That document also discourages use of "AUTHORS" sections, but again,
that's not binding on ncurses, which due to its history and some
struggles early in its life with former maintainers implying, or even
outright asserting, authorship without foundation,[1] it may be prudent
to retain it here--and give some scrutiny to surviving claims.)

At any rate, placing the "EXAMPLES" section late, before only "AUTHORS"
(if present) and "SEE ALSO" is intended as an ergonomic aid for
frustrated and impatient readers who may be dizzied by the technical
presentation of earlier page sections, mashing <Shift+G> in the pager in
a quest for a cookie.[2]  The "AUTHORS" and "SEE ALSO" sections are
generally short enough that the top of the terminal window is likely to
contain at least some of the "EXAMPLES" content.  For tput(1) in
particular, with its multiple examples of shell input, this section may
be easily spotted and welcomed.

Further, this arrangement is reminiscent of the POSIX reference pages'
long-standing practice of letting "informative" sections gravitate later
in the document than "normative" sections.

[1] https://invisible-island.net/ncurses/ncurses-license.html

[2] This is also why I have embraced, and advocate, the latter day
    innovation (seen in ncurses) of putting the "SEE ALSO" section
    invariably last in a man page--it helps readers who know that
    they're not reading the page they want, but are "in the
    neighborhood".   Early Unix man pages did _not_ arrange them thus.
    But today's *nix systems have thousands more man pages installed
    than in 1980 or even 1990.  (And that despite the efforts of GNU,
    every post-{Motif,OPEN LOOK} "desktop environment", most programming
    language development communities, and the average hacker to avoid
    writing man pages altogether.)
---
 man/term.5 |  34 +++++++-------
 man/toe.1m |  42 ++++++++---------
 man/tput.1 | 134 ++++++++++++++++++++++++++---------------------------
 3 files changed, 105 insertions(+), 105 deletions(-)

diff --git a/man/term.5 b/man/term.5
index 5fd36a54..7c7c6ddf 100644
--- a/man/term.5
+++ b/man/term.5
@@ -345,6 +345,23 @@ .SS Mixed-case terminal names
 \fBncurses\fP represents the \*(``first character\*(''
 of the terminal name used as
 the intermediate level of a directory tree in (two-character) hexadecimal form.
+.SH LIMITS
+Some limitations:
+.bP
+total compiled entries cannot exceed 4096 bytes in the legacy format.
+.bP
+total compiled entries cannot exceed 32768 bytes in the extended format.
+.bP
+the name field cannot exceed 128 bytes.
+.PP
+Compiled entries are limited to 32768 bytes because offsets into the
+\fIstrings table\fP use two-byte integers.
+The legacy format could have supported 32768-byte entries,
+but was limited a virtual memory page's 4096 bytes.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
 .SH EXAMPLES
 As an example, here is a description for the Lear-Siegler
 ADM\-3, a popular though rather stupid early terminal:
@@ -390,23 +407,6 @@ .SH EXAMPLES
 0150  00 08 00 0c 00 0b 00 0a  00                       ........ .
 .TE
 .in
-.SH LIMITS
-Some limitations:
-.bP
-total compiled entries cannot exceed 4096 bytes in the legacy format.
-.bP
-total compiled entries cannot exceed 32768 bytes in the extended format.
-.bP
-the name field cannot exceed 128 bytes.
-.PP
-Compiled entries are limited to 32768 bytes because offsets into the
-\fIstrings table\fP use two-byte integers.
-The legacy format could have supported 32768-byte entries,
-but was limited a virtual memory page's 4096 bytes.
-.SH FILES
-.TP
-.I \*d
-compiled terminal description database
 .SH AUTHORS
 Thomas E. Dickey
 .br
diff --git a/man/toe.1m b/man/toe.1m
index 251382eb..3936b3bb 100644
--- a/man/toe.1m
+++ b/man/toe.1m
@@ -139,6 +139,27 @@ .SH OPTIONS
 \fB\-V\fP
 reports the version of \fIncurses\fP associated
 with this program and exits with a successful status.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database
+.SH HISTORY
+\fB\%@TOE@\fP is not provided by other implementations.
+There is no applicable X/Open or POSIX standard for it.
+.PP
+It replaces a \fB\-T\fP option that was briefly supported by
+the \fIncurses\fP \fB\%infocmp\fP utility in 1995.
+.PP
+The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
+respectively.
+.PP
+The program's name originates with a developer's pun:
+.bP
+\fBtic\fP,
+.bP
+\fBtac\fP (now \fBtack\fP),
+.bP
+\fBtoe\fP.
 .SH EXAMPLES
 When not sorting with the \fB\-s\fP option,
 the \fB\-a\fP option reports all of the names found in all of the
@@ -200,27 +221,6 @@ .SH EXAMPLES
 \&.\|.\|.
 .TE
 .RE
-.SH FILES
-.TP
-.I \*d
-compiled terminal description database
-.SH HISTORY
-\fB\%@TOE@\fP is not provided by other implementations.
-There is no applicable X/Open or POSIX standard for it.
-.PP
-It replaces a \fB\-T\fP option that was briefly supported by
-the \fIncurses\fP \fB\%infocmp\fP utility in 1995.
-.PP
-The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
-respectively.
-.PP
-The program's name originates with a developer's pun:
-.bP
-\fBtic\fP,
-.bP
-\fBtac\fP (now \fBtack\fP),
-.bP
-\fBtoe\fP.
 .SH SEE ALSO
 \fB\%@CAPTOINFO@\fP(1M),
 \fB\%@INFOCMP@\fP(1M),
diff --git a/man/tput.1 b/man/tput.1
index d2751022..1a070423 100644
--- a/man/tput.1
+++ b/man/tput.1
@@ -299,73 +299,6 @@ .SS Terminal Size
 If the \fB\-T\fP option is given
 @TPUT@ ignores the environment variables by calling \fBuse_tioctl(TRUE)\fP,
 relying upon the operating system (or finally, the terminal database).
-.SH EXAMPLES
-.TP 5
-\fB@TPUT@ init\fP
-Initialize the terminal according to the type of
-terminal in the environmental variable \fBTERM\fP.  This
-command should be included in everyone's .profile after
-the environmental variable \fBTERM\fP has been exported, as
-illustrated on the \fBprofile\fP(5) manual page.
-.TP 5
-\fB@TPUT@ \-T5620 reset\fP
-Reset an AT&T 5620 terminal, overriding the type of
-terminal in the environmental variable \fBTERM\fP.
-.TP 5
-\fB@TPUT@ cup 0 0\fP
-Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
-(the upper left corner of the screen, usually known as the \*(``home\*(''
-cursor position).
-.TP 5
-\fB@TPUT@ clear\fP
-Echo the clear-screen sequence for the current terminal.
-.TP 5
-\fB@TPUT@ cols\fP
-Print the number of columns for the current terminal.
-.TP 5
-\fB@TPUT@ \-T450 cols\fP
-Print the number of columns for the 450 terminal.
-.TP 5
-\fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
-Set the shell variables \fBbold\fP, to begin stand-out mode
-sequence, and \fBoffbold\fP, to end standout mode sequence,
-for the current terminal.
-This might be followed by a
-prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
-.TP 5
-\fB@TPUT@ hc\fP
-Set exit code to indicate if the current terminal is a hard copy terminal.
-.TP 5
-\fB@TPUT@ cup 23 4\fP
-Send the sequence to move the cursor to row 23, column 4.
-.TP 5
-\fB@TPUT@ cup\fP
-Send the terminfo string for cursor-movement, with no parameters substituted.
-.TP 5
-\fB@TPUT@ longname\fP
-Print the long name from the \fBterminfo\fP database for the
-type of terminal specified in the environmental
-variable \fBTERM\fP.
-.PP
-.RS 5
-\fB@TPUT@ \-S <<!\fP
-.br
-\fB> clear\fP
-.br
-\fB> cup 10 10\fP
-.br
-\fB> bold\fP
-.br
-\fB> !\fP
-.RE
-.TP 5
-\&
-This example shows \fB@TPUT@\fP processing several capabilities
-in one invocation.
-It clears the screen,
-moves the cursor to position 10, 10
-and turns on bold (extra bright) mode.
-The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
 .SH FILES
 .TP
 .I @DATADIR@/tabset
@@ -608,6 +541,73 @@ .SH HISTORY
 almost without change,
 Raymond made improvements to the way the command-line parameters
 were handled.
+.SH EXAMPLES
+.TP 5
+\fB@TPUT@ init\fP
+Initialize the terminal according to the type of
+terminal in the environmental variable \fBTERM\fP.  This
+command should be included in everyone's .profile after
+the environmental variable \fBTERM\fP has been exported, as
+illustrated on the \fBprofile\fP(5) manual page.
+.TP 5
+\fB@TPUT@ \-T5620 reset\fP
+Reset an AT&T 5620 terminal, overriding the type of
+terminal in the environmental variable \fBTERM\fP.
+.TP 5
+\fB@TPUT@ cup 0 0\fP
+Send the sequence to move the cursor to row \fB0\fP, column \fB0\fP
+(the upper left corner of the screen, usually known as the \*(``home\*(''
+cursor position).
+.TP 5
+\fB@TPUT@ clear\fP
+Echo the clear-screen sequence for the current terminal.
+.TP 5
+\fB@TPUT@ cols\fP
+Print the number of columns for the current terminal.
+.TP 5
+\fB@TPUT@ \-T450 cols\fP
+Print the number of columns for the 450 terminal.
+.TP 5
+\fBbold=\(ga@TPUT@ smso\(ga offbold=\(ga@TPUT@ rmso\(ga\fP
+Set the shell variables \fBbold\fP, to begin stand-out mode
+sequence, and \fBoffbold\fP, to end standout mode sequence,
+for the current terminal.
+This might be followed by a
+prompt: \fBecho "${bold}Please type in your name: ${offbold}\ec"\fP
+.TP 5
+\fB@TPUT@ hc\fP
+Set exit code to indicate if the current terminal is a hard copy terminal.
+.TP 5
+\fB@TPUT@ cup 23 4\fP
+Send the sequence to move the cursor to row 23, column 4.
+.TP 5
+\fB@TPUT@ cup\fP
+Send the terminfo string for cursor-movement, with no parameters substituted.
+.TP 5
+\fB@TPUT@ longname\fP
+Print the long name from the \fBterminfo\fP database for the
+type of terminal specified in the environmental
+variable \fBTERM\fP.
+.PP
+.RS 5
+\fB@TPUT@ \-S <<!\fP
+.br
+\fB> clear\fP
+.br
+\fB> cup 10 10\fP
+.br
+\fB> bold\fP
+.br
+\fB> !\fP
+.RE
+.TP 5
+\&
+This example shows \fB@TPUT@\fP processing several capabilities
+in one invocation.
+It clears the screen,
+moves the cursor to position 10, 10
+and turns on bold (extra bright) mode.
+The list is terminated by an exclamation mark (\fB!\fP) on a line by itself.
 .SH SEE ALSO
 \fB\%@CLEAR@\fP(\*n),
 \fB\%stty\fP(1),
-- 
2.30.2

signature.asc
Description: PGP signature