[groff] 32/36: groff_man_style(7): Refine "Fundamental concepts".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e9e0ff709f53418852f9301d6667d9e41cb47b1a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jan 17 11:41:57 2023 -0600

    groff_man_style(7): Refine "Fundamental concepts".
    
    * Shift some material here from "Macro reference preliminaries".
    * Present, but do not define, "words".  Describe how they are separated.
      (That's about as much definition as a man(7) package user needs.)
    * Link breaking and hyphenation more strongly.
    * Refer to command-line options as "options", not "flags".
    * Drop internal cross reference that duplicates one in the previous
      sentence.
    * Distinguish inter-sentence space from adjustment more strongly.
    * Define "control line".
    * Stop quoting double quotes; doing so looks crazy when degraded to
      basic Latin.  (I can hear the reader now: "...so I double the double
      quotes?!")  They're already parenthesized.
    * Define "argument".
    * Define "empty request".
    * Define "text line".
---
 tmac/groff_man.7.man.in | 128 +++++++++++++++++++++++++++---------------------
 1 file changed, 71 insertions(+), 57 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 333712664..e434fe83e 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -211,8 +211,6 @@ and employ the Unix line-ending convention
 .\" What about rare English words that require diacritics, and
 .\" proper names that require more than basic Latin?
 .\"
-.\" text lines vs. control lines (macro calls)
-.\" word (delimited by spaces or newlines)
 .\" sentence (including end-of-sentence detection)
 .\" The above distinction works well with filling.
 .\" Don't fill your input text yourself; let groff do the work.
@@ -226,15 +224,26 @@ and employ the Unix line-ending convention
 .\" type size
 .\" typesetter (troff device, PostScript, PDF)
 .\" terminal (nroff device, emulator, typewriter, TTY)
+.I groff
+is a programming system for typesetting:
+we thus often use the verb \(lqto set\(rq in the sense
+\(lqto typeset\(rq.
 .
-The formatter collects words from the input and
+The formatter
+.MR @g@troff @MAN1EXT@
+collects words from the input and
 .I fills
 output lines with as many as will fit.
 .
+.I Words
+are separated by spaces and newlines.
+.\" Also tabs and leaders, but let's not discuss those in man(7).
+.
 A transition to a new output line is called a
 .I break.
 .
-A word may be split across output lines at hyphens,
+When formatted,
+a word may be broken at hyphens,
 at
 .B \e%
 or
@@ -245,19 +254,67 @@ or at predetermined locations
 if automatic hyphenation is enabled
 (see the
 .B \-rHY
-flag in section \(lqOptions\(rq below).
+option in section \(lqOptions\(rq below).
 .
 An output line may be supplemented with
-.I inter-sentence space
-and
+.I inter-sentence space,
+and then optionally
 .I adjusted
-to form a straight right margin
+with more space to a consistent line length
 (see the
 .B \-dAD
-flag in section \(lqOptions\(rq below).
+option).
 .
 .MR roff @MAN7EXT@
 details these processes.
+.
+.
+.P
+An input line that starts with a dot (.\&)
+or neutral apostrophe (\(aq)
+is a
+.I control line.
+To call a macro,
+follow the dot with zero or more spaces \" or tabs
+and then the macro name.
+.
+Some macros interpret
+.I arguments,
+words that follow the macro name.
+.
+A newline,
+unless escaped
+(see subsection \(lqPortability\(rq below),
+marks the end of the macro call.
+.
+An input line consisting of a dot followed by a newline
+is called the
+.I empty request;
+it does nothing.
+.
+.I Text lines
+are input lines that are not control lines.
+.
+.
+.P
+We describe below several
+.I man
+macros that plant one-line
+.I input traps:
+the next input line that directly produces formatted output is treated
+specially.
+.
+For
+.I man
+documents written in the language subset described in section
+\[lq]Portability\[rq] below,
+this means that control lines using the empty request
+and uncommented input lines ending with an escaped newline or the
+.B \[rs]c
+escape sequence do not spring the trap;
+anything else does.
+.
+.
 .\" ====================================================================
 .\" .SS "Why have a tutorial and style guide?"
 .\" ====================================================================
@@ -270,6 +327,8 @@ details these processes.
 _endif()dnl
 .
 .
+.br
+.ne 6v
 .\" ====================================================================
 .SS "Macro reference preliminaries"
 .\" ====================================================================
@@ -283,22 +342,8 @@ and
 .BR .EE .
 .
 .
-_ifstyle()dnl
-.P
-A macro call appears on a line starting with a dot (\(lq.\(rq),
-followed by zero or more spaces and then the macro name.
-.
-Some macros accept arguments;
-each such argument is separated from the macro name and any subsequent
-arguments by one or more spaces.
-.
-A newline,
-unless escaped
-(see subsection \(lqPortability\(rq below),
-terminates the macro call.
-.
-.
-_endif()dnl
+.br
+.ne 2v
 .P
 _ifstyle()dnl
 Optional macro arguments are indicated by surrounding them with square
@@ -310,7 +355,7 @@ characters must be double-quoted to be interpreted 
correctly.
 .
 _endif()dnl
 An empty macro argument can be specified with a pair of double-quotes
-(\(lq""\(rq),
+(""),
 but the
 .I man
 package is designed such that this should seldom be necessary.
@@ -324,37 +369,6 @@ Most macro arguments wll be formatted as text in the 
output;
 exceptions are noted.
 .
 .
-_ifstyle()dnl
-.P
-Bear in mind that
-.I groff
-is fundamentally a programming system for typesetting.
-.
-Consequently,
-the verb \(lqto set\(rq is frequently used below in the sense \(lqto
-typeset\(rq.
-.
-.
-.P
-We describe below several
-.I man
-macros that plant one-line
-.I input traps:
-the next input line that directly produces formatted output is treated
-specially.
-.
-For
-.I man
-documents written in the language subset described in section
-\[lq]Portability\[rq] below,
-this means that control lines using the empty request
-and uncommented input lines ending with an escaped newline or the
-.B \[rs]c
-escape sequence do not spring the trap;
-anything else does.
-.
-.
-_endif()dnl
 .\" ====================================================================
 .SS "Document structure macros"
 .\" ====================================================================