diff options
author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-02-14 09:55:05 -0600 |
---|---|---|
committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2023-02-14 11:43:23 -0600 |
commit | 2213e68794f25f51f3559592b6e9fa7d18000c74 (patch) | |
tree | 53ff32b5db9bbf4ed3a15f51a72e126eb65e2628 /tmac | |
parent | 3d4249aa76943d05991e633fe2d2c886a916e1d6 (diff) | |
download | groff-git-2213e68794f25f51f3559592b6e9fa7d18000c74.tar.gz |
groff_man*(7): Make clarifications.
* Stop discussing indentation of control lines. man(7) authors have no
need of it.
* Clarify that the leading dot is not part of a man(7) macro's name.
* Weaken overgeneralization; all man(7) macros using traditional input
traps don't respect output line continuation (`\c`), but `TP` does.
* Update cross references to groff(7) "Measurements" section.
* Back off the term "standardized" regarding man(7) section headings.
* Suggest intro(1) as another place to discover a systems's expected
manual section (suffixes).
* Internally cross reference "Portability" subsection when raising \(ti
escape sequence.
* Use active voice when discussing handling of \: in hyperlinks.
* Stop using "sections" in a loose manner when the word already has two
other distinct meanings in this document.
* Fix missing opening parenthesis.
* Output devices don't "replace" characters; they format them.
* Tighten wording.
Diffstat (limited to 'tmac')
-rw-r--r-- | tmac/groff_man.7.man.in | 88 |
1 files changed, 51 insertions, 37 deletions
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index 971a1c609..20da6cd7a 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -14,7 +14,7 @@ _ifstyle()dnl ; that is, approximately the width of the letter \(lqn\(rq in the font current when the macro is called -(see section \(lqNumeric Expressions\(rq in +(see section \(lqMeasurements\(rq in .MR groff @MAN7EXT@ )\c _endif()dnl \&. @@ -287,9 +287,13 @@ 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. +put its name after a dot on a control line. +.\" You never need to indent macro calls in man(7), or call them with +.\" the no-break control character. +. +We refer to macros in this document using this leading dot. . Some macros interpret .I arguments, @@ -319,13 +323,15 @@ specially. . For .I man -documents written in the language subset described in section +documents that follow the advice 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. +and uncommented input lines ending with an escaped newline +do not spring the trap; +anything else does +(but see the +.B .TP +macro description). . . .\" ==================================================================== @@ -386,10 +392,9 @@ exceptions are noted. .SS "Document structure macros" .\" ==================================================================== . -The highest level of organization of a man page is determined by this -group of macros. +Document structure macros organize a man page's content. . -All of these macros break the output line. +All of them break the output line. . .B .TH (title heading) @@ -398,9 +403,9 @@ and footers. . Section headings .RB ( .SH ), -one of which is mandatory and many of which are standardized, -facilitate quick location of relevant material by the reader and aid -the man page writer to discuss all essential aspects of the topic. +one of which is mandatory and many of which are conventionally expected, +facilitate location of material by the reader and aid the man page +writer to discuss all essential aspects of the topic. . Subsection headings .RB ( .SS ) @@ -448,8 +453,9 @@ _endif()dnl . See .MR man 1 -for details on the section numbers and suffixes applicable to your -system. +or +.MR intro 1 +for the manual sectioning applicable to your system. . .I topic and @@ -490,7 +496,7 @@ is centered in the header. . If .I section -is a simple integer between 1 and\~9 (inclusive), +is an integer between 1 and\~9 (inclusive), there is no need to specify .I header-middle; .I an.tmac @@ -839,6 +845,10 @@ which can be formatted with a macro, becomes the tag, which is placed at the current left margin. . +The tag can be extended with the +.B \(rsc +escape sequence. +. Subsequent text is indented by .I indentation, if specified, @@ -1210,7 +1220,8 @@ repeated arbitrarily. The non-breaking adjustable space escape sequence .B \e\(ti is used to prevent the output line from being broken within the option -brackets. +brackets; +see subsection \(lqPortability\(rq below. . . .IP \(bu @@ -1345,9 +1356,10 @@ ampersands, and number signs in HTTP(S) URIs. . _endif()dnl +The formatter removes .B \e: -escape sequences are ignored when supplied to device control commands -for hyperlink-aware output drivers. +escape sequences from hyperlinks when supplying device control commands +to output drivers. . . .TP @@ -1788,8 +1800,9 @@ it is possible with the .B \ec and/or .B \ef -escape sequences, -but see subsection \(lqPortability\(rq +escape sequences. +. +See subsection \(lqPortability\(rq below for approaches. _endif()dnl . @@ -1938,7 +1951,7 @@ package assumes \(lqn\(rq; that is, the width of a letter \(lqn\(rq in the font current when the macro is called -(see section \(lqNumerical Expressions\(rq in +(see section \(lqMeasurements\(rq in .MR groff @MAN7EXT@ ). _endif()dnl _ifnotstyle()dnl @@ -1951,7 +1964,7 @@ An indentation specified in a call to or the deprecated .B .HP persists until -(1) another of these macros is called with an explicit +(1) another of these macros is called with an .I indentation argument, or @@ -2190,9 +2203,11 @@ _endif()dnl can change this vertical spacing, but its use is discouraged.) . -In -.BR .EX / .EE -sections, +Between +.B .EX +and +.B .EE +calls, the inter-paragraph spacing is 1v regardless of output device. . @@ -2414,7 +2429,7 @@ Everything after the double-quote to the end of the input line is ignored. . Whole-line comments should be placed immediately after the empty request -.RB \(lq . \(rq). +.RB (\(lq . \(rq). . . .TP @@ -2771,10 +2786,9 @@ or similar. .B \e(aq Basic Latin neutral apostrophe. . -Some -output devices replace +Some output devices format .RB \(lq\| \(aq \|\(rq -with a right single quotation mark. +as a right single quotation mark. . . .br @@ -2848,9 +2862,9 @@ for example, .B \e(ga Basic Latin grave accent. . -Some output devices replace +Some output devices format .RB \(lq\| \(ga \|\(rq -with a left single quotation mark. +as a left single quotation mark. . . .TP @@ -2858,9 +2872,9 @@ with a left single quotation mark. Basic Latin circumflex accent (\(lqhat\(rq). . -Some output devices replace +Some output devices format .RB \(lq \(ha \(rq -with U+02C6 +as U+02C6 (modifier letter circumflex accent) or similar. . @@ -2884,9 +2898,9 @@ above. .B \e(ti Basic Latin tilde. . -Some output devices replace +Some output devices format .RB \(lq \(ti \(rq -with U+02DC +as U+02DC (small tilde) or similar. . |