diff options
author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-01-17 11:41:57 -0600 |
---|---|---|
committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-01-17 16:16:01 -0600 |
commit | e9e0ff709f53418852f9301d6667d9e41cb47b1a (patch) | |
tree | a2c5121d029c5e01f8f112574a404a85a4585430 /tmac | |
parent | 9989aee6672afb5e8ea1065eec4e91f18f05d323 (diff) | |
download | groff-git-e9e0ff709f53418852f9301d6667d9e41cb47b1a.tar.gz |
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".
Diffstat (limited to 'tmac')
-rw-r--r-- | tmac/groff_man.7.man.in | 128 |
1 files 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" .\" ==================================================================== |