commit c3f585f8d54089b4adba47af6011fa067bc87277 Author: G. Branden Robinson AuthorDate: Fri Apr 22 01:24:13 2022 +1000 Commit: G. Branden Robinson CommitDate: Fri Apr 22 01:24:13 2022 +1000 XXX copyedit new XN/XH feature description diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man index f93b927bb..abab985b6 100644 --- a/tmac/groff_ms.7.man +++ b/tmac/groff_ms.7.man @@ -2006,56 +2006,68 @@ register. . . .P -When creating a table of contents, -incorporating content derived from headings specified by +When creating a table of contents with entry text derived from +headings specified by .B .NH and -.B .SH , +.BR .SH , traditional .I ms implementations provide no convenient mechanism -for duplication of the heading text into the table of contents; +for duplication of the heading in the table entries; .I groff ms -mitigates this limitation, -by providing the following pair of macros, -(for use after +mitigates this limitation +by providing the following pair of macros +for use after .B .NH and .B .SH -respectively): +respectively. +. . .TP -.BI .XN\~ text\ ... +.BI .XN\~ text\~\c +\&.\|.\|. .TQ -.BI .XH\~ outline\-level\ text\ ... -Duplicate -.I text\~... -added to the body ot the document, -to create a table of contents entry, -(which may be indented in accordance with -.IR outline\-level ). +.BI .XH\~ "depth text\~\c" +\&.\|.\|. +Add +.I text +and subsequent arguments +to the body of the document +and create a table of contents entry. +. +.B .XH +futhermore indents the entry by +.IR depth , +which corresponds to the +.B .SH +argument of the same name. +. . .P -Either, -or both of +Either of the .B XN and .B XH -may be redefined by the user, -(preferably by definition of the replacement hook macros, -.BR \%XN\-REPLACEMENT , +macros may be redefined if desired. +. +Doing so via the replacement hook macros, +.B \%XN\-REPLACEMENT and .B \%XH\-REPLACEMENT -respectively); -in their default implementations, -both emit their +is recommended. +. +In their default implementations, +they emit their .I text -arguments into the body of the document, -as heading text; -they also pass this same text to the callback macro: +arguments into the body of the document as heading text +and pass this same text to the callback macro +.BR XH\-UPDATE\-TOC . +. . .TP -.BI \%.XH\-UPDATE\-TOC\~ \%outline\-level\ text\ ... +.BI \%.XH\-UPDATE\-TOC\~ \%depth\~text\~... Encapsulate .I text within @@ -2071,7 +2083,7 @@ macro is required), and may be redefined by the user; in its default implementation, its -.I \%outline\-level +.I \%depth argument, (which is inferred from the last\[hy]specified .B .NH @@ -2087,7 +2099,7 @@ to control indentation of the table of contents. When called by .BR .XN , in addition to the inference of the -.I \%outline\-level +.I \%depth argument, the .I text @@ -2096,6 +2108,7 @@ by prefixing the current heading number, (which is also deduced from the last preceding use of .BR .NH ). . +. .P In addition to .BR \%XH\-UPDATE\-TOC , @@ -2123,6 +2136,7 @@ but either, or both, may be redefined by the user. . +. .P If the user has chosen to redefine .BR \%XH\-UPDATE\-TOC , @@ -2138,6 +2152,7 @@ or or both, to handle the required discriminatory effect. . +. .P It should be noted that, whereas commit 3849ef56fabc2489ab42ec0d0de6737cbf1bfc90 Author: G. Branden Robinson AuthorDate: Mon Apr 18 17:15:46 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 17:22:19 2022 +1000 groff_man*(7): Fix style nits. * Drop misleading reference to "strings". Macro arguments are not best thought of as string objects in the roff language. (You don't interpolate them with `\*`, for instance but with the bespoke `\$`.) * Tighten wording. diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index 5084d8998..4180275e9 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -284,7 +284,7 @@ See section \(lqNotes\(rq below for examples of cases where better alternatives to empty arguments in macro calls are available. _endif()dnl . -Most macro arguments are strings that will be output as text; +Most macro arguments wll be formatted as text in the output; exceptions are noted. . . @@ -915,9 +915,8 @@ Begin synopsis. . A new paragraph is begun at the left margin _ifstyle()dnl -(like -.B .P -and its aliases) +(as with +.BR .P ) _endif()dnl unless .B .SY commit 231d1b4ef568193178878d6e05c64994b35bf668 Author: G. Branden Robinson AuthorDate: Mon Apr 18 14:07:47 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 17:22:19 2022 +1000 groff_man_style(7): Fix style nit. Recast description of `\e` escape sequence. (There's no such thing as an "input glyph", so don't imply its existence with "output glyph".) diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index f8791250b..5084d8998 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -2636,7 +2636,8 @@ and perhaps with some other formatters. . .TP .B \ee -Widely used in man pages to represent a backslash output glyph. +Format the current escape character on the output; +widely used in man pages to render a backslash glyph. . .\" Don't bold the .ec request in this discussion; it's not a major .\" topic of _this_ page as it would be in groff(7). Also, we don't commit e1a9e5ed9fbb06de9cb380b427a4212678db50bb Author: G. Branden Robinson AuthorDate: Mon Apr 18 14:06:34 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 17:22:19 2022 +1000 groff_man_style(7): Fix content nit. Refer to "the roff language" as a singular entity; see commit 80afae9f4, 13 April. diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index 49c4516eb..f8791250b 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -2215,9 +2215,9 @@ and font style alternation macros. . . .P -The two major syntactical categories of +The two major syntactical categories of the .I roff -languages are requests and escape sequences. +language are requests and escape sequences. . Since the .I man @@ -2419,9 +2419,9 @@ This escape sequence produces the Unix command-line option dash in the output. . .RB \(lq \- \(rq -is a hyphen in +is a hyphen in the .I roff -languages; +language; some output devices replace it with U+2010 (hyphen) or similar. @@ -2524,9 +2524,9 @@ or similar. Reverse solidus (backslash). . -The backslash is the default escape character in +The backslash is the default escape character in the .I roff -languages, +language, so it does not represent itself in output. . Also see commit 918aeddb8a793bed64bf3ab51ad143768a0c0eac Author: G. Branden Robinson AuthorDate: Mon Apr 18 14:03:30 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 17:22:19 2022 +1000 groff_man_style(7): Adjust dead-tree typography. Require more space for table with multi-line entry. diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index b35a55a62..49c4516eb 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -3612,7 +3612,7 @@ When this seems necessary, often a shorter or clearer alternative is available. . .br -.ne 3v +.ne 10v .TS c c lfCB lfCB. commit 6a65e0fbba7481a6859687a78f217155aae7a54d Author: G. Branden Robinson AuthorDate: Mon Apr 18 14:02:03 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 17:22:12 2022 +1000 groff_man_style(7): Fix content nits. * Consistently refer to `\|` as a "thin space" escape sequence (not "narrow"). * Revise discussion of ellipsis again. Use a more representative example, and present it in two-column format used elsewhere in this section. diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in index 70a946699..b35a55a62 100644 --- a/tmac/groff_man.7.man.in +++ b/tmac/groff_man.7.man.in @@ -412,8 +412,11 @@ The macro package may also abbreviate .I title and .I footer-inside -with an ellipsis if they overrun the space available in the header and -footer, +with ellipses +_ifstyle()dnl +.RB ( .\|.\|.\& ) +_endif()dnl +if they overrun the space available in the header and footer, respectively. . For HTML output, @@ -2397,10 +2400,10 @@ recognized as such. . .TP .B \e| -Narrow +Thin space (one-sixth em on typesetters, -zero-width on terminals) -non-breaking space. +zero-width on terminals); +a non-breaking space. . Used primarily in ellipses (\(lq.\e|.\e|.\(rq) @@ -3822,7 +3825,7 @@ in subsection \[lq]Command synopsis macros\[rq]. The idiomatic .I roff ellipsis is three dots (periods) -with a \[lq]thin space\[rq] escape sequence +with thin space escape sequences .B \[rs]| internally separating them. . @@ -3850,18 +3853,28 @@ would then need to be suffixed with .B \[rs]& when not ending a sentence. . -.RS -.RS -.EX -Arguments are foo bar \[rs]*[EL]\[rs]& except when debugging. -Arguments are foo bar .\[rs]|.\[rs]|.\[rs]& except when debugging. -.EE -.RE +.br +.ne 4v +.TS +C C +LfCB LfCB. +Instead of.\|.\|. .\|.\|.do this. +_ +\&.ds EL \[rs]&.\[rs]|.\[rs]|. Arguments are +Arguments are .IR src-file\[rs]\[ti] .\[rs]|.\[rs]|.\[rs]& +\&.IR src-file\[rs]\[ti] \[rs]*(EL\[rs]& .IR dest-dir . +\&.IR dest-dir . +_ +.TE . -Such a string saves one character of typing, -at the cost of obscuring even the suggestion of an ellipsis to a casual -reader of the source document. -.RE +. +.IP +The first column practices a false economy; +the savings in typing is offset by the cost of obscuring even the +suggestion of an ellipsis to a casual reader of the source document, +and reduced portability to +.RI non- roff +man page formatters that cannot handle string definitions. . . .IP commit 1c61128594ee22206404ae71230c586d47529eed Author: G. Branden Robinson AuthorDate: Mon Apr 18 12:48:08 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 12:50:03 2022 +1000 ChangeLog: Fix misdescription of bug fix. The problem wasn't that `UE` and `ME` were given _extraneous_ arguments, it was that they were given _any_ (else the problem wouldn't have been seen in groff's own man pages), combined with the attempt at robust handling for excess arguments, without which the implementation would likely have been simpler and perhaps not introduced the bug. Also fix typo. diff --git a/ChangeLog b/ChangeLog index a60b564b2..1957afc55 100644 --- a/ChangeLog +++ b/ChangeLog @@ -46,8 +46,8 @@ 2022-04-14 G. Branden Robinson - [man]: Fix extraneous space when `ME` or `UE` given extraneous - arguments and mandoc wrapper is used. + [man]: Fix extraneous space when `ME` or `UE` given arguments + and mandoc wrapper is used. * tmac/an-ext.tmac (UE, ME): Double backslashes in macro definitions when interpolating `.$` register (just like we tell @@ -82,7 +82,7 @@ (presumably ASCII/ISO 8859/Unicode) systems. * src/roff/troff/input.cpp (token::next): Translate the input - character codes for input NBSP to \~ and nput SHY to \%. + character codes for input NBSP to \~ and input SHY to \%. Fixes . Thanks to Dave Kemper for the report, code review, and his suggestion to push commit 47b813df96af684a1f3c8b262514664cd47552d3 Author: G. Branden Robinson AuthorDate: Sun Apr 17 22:40:24 2022 +1000 Commit: G. Branden Robinson CommitDate: Mon Apr 18 01:44:05 2022 +1000 doc/ms.ms: Fix TOC example in nroff mode. The example was broken on terminal devices. Stop trying to simulate TOC output and use PX to get the real thing. This necessitates knowledge of ms package internals, unfortunately, but is otherwise much cleaner. diff --git a/doc/ms.ms b/doc/ms.ms index 01afe822c..2897701d4 100644 --- a/doc/ms.ms +++ b/doc/ms.ms @@ -3005,16 +3005,11 @@ register. Here's an example of typical .I ms table of contents preparation and -(a simulation of) its result. . -.ds DOT \h'1m'.\" .TS box center; -cb | cb -l | c. -Input Result -_ +L. T{ .nf .CW @@ -3030,8 +3025,9 @@ Introduction Methodology \&.XS \[->]Methodology -\&.XA +\&.XA no \[->]\[->]Fassbinder\[aq]s Approach +\&.XA no \[->]\[->]Kahiu\[aq]s Approach \&.XE .R @@ -3047,27 +3043,56 @@ Findings .CW \&.TC .fi -T} T{ -.sp 1v -.nf -.LG -.\" Manual centering--ugh! -.B "\h'2m'Table of Contents" -.NL -.sp 2v -.\" Use absolute motions to gets the dots aligned. -Introduction\h'|4.5m'\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\01 -\h'1m'Methodology\h'|4.5m'\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\02 -\h'2m'Fassbinder's Approach -\h'2m'Kahiu's Approach -\&.\|.\|. -.\" XXX: Why doesn't \h'|3.5m' achieve alignment? -Findings\h'|3.2m'\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\*[DOT]\08 T} .TE -.rm DOT .KE . +.nr SavedPageNumber \n% +.nr SavedH1 \n[H1] \" groff ms internal name +.nr SavedH2 \n[H2] \" groff ms internal name +.nr % 1 +.rr H1 +.rr H2 +.als SavedTOC toc*div \" groff ms internal name +.rm toc*div +.di ThrowAway +.NH 1 +Introduction +.XS +Introduction +.XE +.nr % 2 +.NH 2 +Methodology +.XS + Methodology +.XA no + Fassbinder's Approach +.XA no + Kahiu's Approach +.XE +.nr % 5 +.NH 1 +Findings +.XS +Findings +.XE +.br +.di +.\" We can't emit the TOC inside a B1/B2 box, so use lines instead. +.R +\l'\n[.l]u' +.PX +\l'\n[.l]u' +.als toc*div SavedTOC +.rm SavedTOC +.nr % \n[SavedPageNumber] +.nr H1 \n[SavedH1] +.nr H2 \n[SavedH2] +.rr SavedPageNumber +.rr SavedH1 +.rr SavedH2 +. . .PP Provins's @@ -3090,6 +3115,7 @@ regularly. . . .\" ------------------------ +.if t .bp .NH 1 Differences from AT&T .BI ms commit da5e8704480ebf9df89224cdf3831917ad1d060f Author: G. Branden Robinson AuthorDate: Sun Apr 17 19:02:39 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 19:02:39 2022 +1000 [ms]: Apply depth-specific indents to TOC entries. * tmac/s.tmac (XH-UPDATE-TOC): Modify Keith Marshall's new XN/XH feature to indent TOC entries by section heading depth. The increment is 2 ens per depth level. diff --git a/ChangeLog b/ChangeLog index ecd0f2c04..a60b564b2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2022-04-17 G. Branden Robinson + + * tmac/s.tmac (XH-UPDATE-TOC): Modify Keith Marshall's new XN/XH + feature to indent TOC entries by section heading depth. The + default increment is 2 ens. + 2022-04-17 G. Branden Robinson * tmac/s.tmac (XA): Drop apparently useless `ll` request. It diff --git a/tmac/s.tmac b/tmac/s.tmac index 98bf0ce7e..c6cad011a 100644 --- a/tmac/s.tmac +++ b/tmac/s.tmac @@ -1768,7 +1768,8 @@ along with this program. If not, see . .\" .XH-UPDATE-TOC [] .\" ( present only when called by XN) .XS -.shift\" don't use in rudimentary style +.in (\\$1u - 1u * 2n) +.shift \&\\$*\" capture (if present) and .XE .. commit b51af6007cb8ff6c3faf086149e19ab6c4076b40 Author: G. Branden Robinson AuthorDate: Sun Apr 17 18:53:05 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 18:53:05 2022 +1000 [ms: Drop apparently useless `ll` request in `XA`. * tmac/s.tmac (XA): Drop apparently useless `ll` request. It doesn't do anything according to my tests. diff --git a/ChangeLog b/ChangeLog index d16d0d3ea..ecd0f2c04 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2022-04-17 G. Branden Robinson + + * tmac/s.tmac (XA): Drop apparently useless `ll` request. It + doesn't do anything according to my tests. + 2022-04-15 G. Branden Robinson * src/preproc/refer/label.ypp: Drop redundant declaration of diff --git a/tmac/s.tmac b/tmac/s.tmac index 5ff23d04b..98bf0ce7e 100644 --- a/tmac/s.tmac +++ b/tmac/s.tmac @@ -1739,7 +1739,6 @@ along with this program. If not, see . . br . par@reset . na -. ll -8n \" XXX: take TC-MARGIN into account? . in (n;0\\$2) .\} .el .@error .XA without .XS commit 8967c30d7893a88fac0136bdafcd6829ba960c73 Author: G. Branden Robinson AuthorDate: Sun Apr 17 17:27:33 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 17:27:33 2022 +1000 tmac/s.tmac: Fix code style (trivial). * This file does not place calls after open brace escape sequences. * This file uses tabs, not spaces, for indentation. diff --git a/tmac/s.tmac b/tmac/s.tmac index 9faf88ad6..5ff23d04b 100644 --- a/tmac/s.tmac +++ b/tmac/s.tmac @@ -1789,9 +1789,10 @@ along with this program. If not, see . .de XN de .\" .XN .ie \\n[nh*hl] .toc*xn-init \\$@ -.el \{ .@error .XN is not allowed before .NH -. nop \&\\$* -. \} +.el \{\ +. @error .XN is not allowed before .NH +. nop \&\\$* +.\} .de toc*xn-init de .rn XN-REPLACEMENT XN .XN \\$@ commit b03bf5362d4a4be11b0a9a0e15ecea8f043b5057 Author: G. Branden Robinson AuthorDate: Sun Apr 17 16:35:56 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 16:50:08 2022 +1000 [ms]: Update discussion of footnote paragraphing. * Introduce term "automatic number" to (somewhat) abbreviate the sesquipedialian alternative "automatically generated footnote number". * tmac/groff_ms.7.man: Undocument FP macro, partially reverting 4aae5708b, 1 October. As noted in , we should probably gate this macro name behind some sort of compatibility selector, perhaps a string which the user can set to "ATT" or "BSD" (or a default, "GNU"). This string would also affect the semantics of "P1" and potentially, "TM" (which means incompatible things in the AT&T and Berkeley ms traditions, but GNU ms supports neither). diff --git a/doc/groff.texi b/doc/groff.texi index be458a38b..ab6bbaa34 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -2914,10 +2914,11 @@ and those for which the @code{FS} request is given a marker argument, at the bottom of a column or page. This is a Berkeley extension. @table @code @item 0 -Set an automatic number as a superscript (on typesetter devices) or -surrounded by square brackets (on terminals). The footnote paragraph is -indented as with @code{PP} if there is an @code{FS} argument or an -automatic number, and as with @code{LP} otherwise. This is the default. +Set an automatic number@footnote{defined in @ref{ms Footnotes}) below} +as a superscript (on typesetter devices) or surrounded by square +brackets (on terminals). The footnote paragraph is indented as with +@code{PP} if there is an @code{FS} argument or an automatic number, and +as with @code{LP} otherwise. This is the default. @item 1 As @code{0}, but set the marker as regular text and follow an @@ -3945,9 +3946,10 @@ A footnote is typically anchored to a place in the text with a arbitrary user-specified text. @Defmpstr {*, ms} -Place an automatically numbered footnote marker in the text. Each time -this string is interpolated, the number it produces increments by one. -Automatic footnote numbers start at 1. This is a Berkeley extension. +Place an @dfn{automatic number}, an automatically generated numeric +footnote marker, in the text. Each time this string is interpolated, +the number it produces increments by one. Automatic numbers start at 1. +This is a Berkeley extension. @endDefesc Enclose the footnote text in @code{FS} and @code{FE} macro calls to set @@ -4002,8 +4004,8 @@ parameters. The registers @code{FI}, @code{FPD}, @code{FPS}, and respectively. The @code{FF} register controls the formatting of automatically numbered -footnotes and those for which @code{FS} is given a marker argument. -@xref{ms Document Control Settings}. +footnote paragraphs and those for which @code{FS} is given a marker +argument. @xref{ms Document Control Settings}. The default footnote line length is 11/12ths of the normal line length for compatibility with the expectations of historical @file{ms} diff --git a/doc/ms.ms b/doc/ms.ms index 76772dd71..01afe822c 100644 --- a/doc/ms.ms +++ b/doc/ms.ms @@ -2232,12 +2232,15 @@ lf(CR) lx. String Description _ \[rs]** T{ -Place an automatically numbered footnote marker in the text. +Place an +.I "automatic number" , +an automatically generated numeric footnote marker, +in the text. . Each time this string is interpolated, the number it produces increments by one. . -Automatic footnote numbers start at 1. +Automatic numbers start at 1. . This is a Berkeley extension. T} @@ -2275,8 +2278,7 @@ which is then also placed at the beginning of the footnote text. If .I marker is omitted, -the next pending automatic footnote number enqueued by interpolation of -the +the next pending automatic number enqueued by interpolation of the .CW * string is used, and if none exists, @@ -2417,10 +2419,13 @@ respectively. .PP The .CW FF -register controls the formatting of automatically numbered footnotes, +register controls the formatting of automatically numbered footnote +paragraphs, and those for which .CW .FS -is given a marker argument, +is given a +.I marker +argument, at the bottom of a column or page as follows. . . diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man index 5d2b0b9f7..f93b927bb 100644 --- a/tmac/groff_ms.7.man +++ b/tmac/groff_ms.7.man @@ -1502,12 +1502,15 @@ or arbitrary user-specified text. . .TP .B \[rs]** -Place an automatically numbered footnote marker in the text. +Place an +.IR automatic number , +an automatically generated numeric footnote marker, +in the text. . Each time this string is interpolated, the number it produces increments by one. . -Automatic footnote numbers start at 1. +Automatic numbers start at 1. . This is a Berkeley extension. . @@ -1539,8 +1542,7 @@ which is then also placed at the beginning of the footnote text. If .I marker is omitted, -the next pending automatic footnote number enqueued by interpolation of -the +the next pending automatic number enqueued by interpolation of the .B * string is used, and if none exists, @@ -1591,33 +1593,22 @@ respectively. . . .P -Paragraph-level formatting of footnotes is performed by a macro named -.BR FP , -which is called once for each individual footnote. -A default implementation of -.B FP -is provided; -alternatively, -you may define your own replacement implementation, -and so assert your own control over footnote paragraph formatting. -. -.P -When using the default implementation of -.BR FP , -the +The .B FF -register controls the formatting of automatically numbered footnotes, +register controls the formatting of automatically numbered footnote +paragraphs, and those for which .B .FS is given a .I marker argument, -at the bottom of a column or page as follows:- +at the bottom of a column or page as follows. +. . .RS .TP 0 -Set an automatically generated number, +Set an automatic number, or a specified .B FS .I marker @@ -1644,7 +1635,7 @@ This is the default. As .BR 0 , but set the marker as regular text, -and follow an automatically generated number with a period. +and follow an automatic number with a period. . . .TP @@ -1666,35 +1657,6 @@ but set the footnote paragraph with the marker hanging .RE . . -.P -Conversely, -if you choose to provide your own -.B FP -macro implementation, -.I you -have control of how footnote paragraphs will be formatted; -it is your choice as to how the -.B FF -register should be interpreted, -(if at all). -For each individual footnote, -your macro will be called with one argument, -which represents either an automatically generated footnote number, -or the verbatim -.I marker -argument passed in the initiating -.B FS -macro call; -in the latter case, -an explicit second argument of -.RB \[lq] no \[rq] -will also be present, -indicating that no embellishment of the footnote -.I marker -(as may be appropriate for footnote numbers) -is required. -. -. .\" ==================================================================== .SS "Headers and footers" .\" ==================================================================== commit c07cc37bf7f08e2937df0fa83e050f7f1dbdc2a3 Author: G. Branden Robinson AuthorDate: Sun Apr 17 16:22:22 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 16:22:22 2022 +1000 tmac/s.tmac: Clarify a comment. diff --git a/tmac/s.tmac b/tmac/s.tmac index 2317b8ee4..9faf88ad6 100644 --- a/tmac/s.tmac +++ b/tmac/s.tmac @@ -2133,10 +2133,14 @@ along with this program. If not, see . .\" **************************** .\" Emulate Bell Labs localisms. Note, (a) they're not documented, and .\" (b) the .P1 and .UC macros collide with different ones in Berkeley -.\" ms. We hack around this by conditionalizing the behavior of P1; UC -.\" was not defined by groff and will be a no-op if called Berkeley -.\" style with no arguments, so there is no problem with hijacking it -.\" here. +.\" ms. +.\" +.\" [Correction 2022-04-17: 10th Edition AT&T ms also collides with +.\" Berkeley's (undocumented) FP macro.] +.\" +.\" We hack around this by conditionalizing the behavior of P1; UC was +.\" not defined by groff and will be a no-op if called Berkeley style +.\" with no arguments, so there is no problem with hijacking it here. .\" .\" What's done here is sufficient to give back the Guide to EQN (1976) .\" its section headings and restore some text that had gone missing as commit 4cffbb7ce0feaac725a1535a474bb8a57d82ef19 Author: G. Branden Robinson AuthorDate: Sun Apr 17 12:10:36 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 12:10:36 2022 +1000 [ms]: (docs) Clarify \n[FF] behavior. ...by relating each supported register value to a paragraphing macro. diff --git a/doc/groff.texi b/doc/groff.texi index 81a862c0d..be458a38b 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -2916,18 +2916,19 @@ the bottom of a column or page. This is a Berkeley extension. @item 0 Set an automatic number as a superscript (on typesetter devices) or surrounded by square brackets (on terminals). The footnote paragraph is -indented if there is an @code{FS} argument or an automatic number. This -is the default. +indented as with @code{PP} if there is an @code{FS} argument or an +automatic number, and as with @code{LP} otherwise. This is the default. @item 1 -Like @code{0}, but set the marker as regular text and follow an +As @code{0}, but set the marker as regular text and follow an automatic number with a period. @item 2 -Like @code{1}, but without indentation. +As @code{1}, but without indentation (like @code{LP}). @item 3 -Like @code{1}, but set the footnote paragraph with the marker hanging. +As @code{1}, but set the footnote paragraph with the marker hanging +(like @code{IP}). @end table Effective: next footnote. diff --git a/doc/ms.ms b/doc/ms.ms index 55164c5bd..76772dd71 100644 --- a/doc/ms.ms +++ b/doc/ms.ms @@ -2436,27 +2436,36 @@ Set an automatic number as a superscript or surrounded by square brackets (on terminals). . -The footnote paragraph is indented if there is an +The footnote paragraph is indented as with +.CW .PP +if there is an .CW .FS -argument or an automatic number. +argument or an automatic number, +and as with +.CW .LP +otherwise. . This is the default. T} 1 T{ -Like +As .CW 0 , but set the marker as regular text, and follow an automatic number with a period. T} 2 T{ -Like +As .CW 1 , -but without indentation. +but without indentation +(like +.CW .LP ). T} 3 T{ -Like +As .CW 1 , -but set the footnote paragraph with the marker hanging. +but set the footnote paragraph with the marker hanging +(like +.CW .IP ). T} .TE .KE diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man index 83a18b09c..5d2b0b9f7 100644 --- a/tmac/groff_ms.7.man +++ b/tmac/groff_ms.7.man @@ -1627,16 +1627,21 @@ as a superscript or surrounded by square brackets (on terminals). . -The footnote paragraph is indented if there is an +The footnote paragraph is indented as with +.B .PP +if there is an .B .FS -argument or an automatically generated number. +argument or an automatic number, +and as with +.B .LP +otherwise. . This is the default. . . .TP 1 -Like +As .BR 0 , but set the marker as regular text, and follow an automatically generated number with a period. @@ -1644,18 +1649,23 @@ and follow an automatically generated number with a period. . .TP 2 -Like +As .BR 1 , -but without indentation. +but without indentation +(like +.BR .LP ). . . .TP 3 -Like +As .BR 1 , -but set the footnote paragraph with the marker hanging. +but set the footnote paragraph with the marker hanging +(like +.BR .IP ). .RE . +. .P Conversely, if you choose to provide your own commit a32acd5356b37a62b9195cab42f5392379fbff8b Author: G. Branden Robinson AuthorDate: Sun Apr 17 11:52:08 2022 +1000 Commit: G. Branden Robinson CommitDate: Sun Apr 17 11:52:08 2022 +1000 grotty(1): Fix content nit. Introduce singleton list with singular noun. diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man index 0a7f3ed24..702b2d0ae 100644 --- a/src/devices/grotty/grotty.1.man +++ b/src/devices/grotty/grotty.1.man @@ -275,7 +275,7 @@ There is therefore no need to filter its output through .\" ==================================================================== . .I grotty -understands the following device control functions produced using the +understands one device control function produced by the .I roff .B \[rs]X escape sequence in a document. commit 5f552e95f55a42d3b55b14a548f56826c855ea44 Author: G. Branden Robinson AuthorDate: Sat Apr 16 19:32:00 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 19:32:00 2022 +1000 hpftodit(1): Tighten wording. diff --git a/src/utils/hpftodit/hpftodit.1.man b/src/utils/hpftodit/hpftodit.1.man index ce767d660..288d97eda 100644 --- a/src/utils/hpftodit/hpftodit.1.man +++ b/src/utils/hpftodit/hpftodit.1.man @@ -110,16 +110,17 @@ glyph names .MR groff_char @MAN7EXT@ for a list). . -The values can be separated by any whitespace; -the Unicode value must use uppercase digits A\^\[en]\^F, -and must be without a leading +The values can be separated by any number of spaces and/or tabs. +. +The Unicode value must use uppercase hexadecimal digits A\^\[en]\^F, +and must lack a leading .RB \[lq] 0x \[rq], .RB \[lq] u \[rq], or .RB \[lq] U+ \[rq]. . Unicode values corresponding to composite glyphs are decomposed; -e.g., +that is .RB \[lq] u00C0 \[rq] becomes .RB \[lq] u0041_0300 \[rq]. @@ -132,7 +133,7 @@ if the glyph corresponds to a Unicode value, or as an unnamed glyph .RB \[lq] \-\-\- \[rq]. . -If the given Unicode value is in the Private Use Area +If the given Unicode value is in the Private Use Area (PUA) (0xE000\^\[en]\^0xF8FF), the glyph is included as an unnamed glyph. . @@ -141,7 +142,7 @@ Refer to for additional information about unnamed glyphs and how to access them. . . -.LP +.P Blank lines and lines beginning with .RB \[lq] # \[rq] are ignored. @@ -160,7 +161,7 @@ name, it must appear first in a list of .I groff names if a comment is included, -e.g., +as in . .RS .EX @@ -176,7 +177,7 @@ or .EE .RE . -rather than +whereas in . .RS .EX @@ -184,9 +185,9 @@ rather than .EE .RE . -which will treat the first +the first .RB \[lq] # \[rq] -as the beginning of the comment. +is interpreted as the beginning of the comment. . . .P @@ -252,13 +253,9 @@ font and which are placed in a special font. The presence or absence of the .B \-s option has some effect on which glyphs are included: -without the -.B \-s -option, +without it, only the \[lq]text\[rq] symbol sets are searched for matching glyphs; -with the -.B \-s -option, +with it, only the \[lq]mathematical\[rq] symbol sets are searched. . Nonetheless, @@ -266,20 +263,17 @@ restricting the symbol sets searched isn't very selective\[em]many glyphs are placed in both regular and special fonts. . Normally, -the .B \-a -option should be used only as a last resort. +should be used only as a last resort. . . .TP .B \-d Dump information about the TFM file to the standard output stream; -this option can be useful for ensuring that a TFM file is a proper match -for a font, -and that the contents of the TFM file are suitable. +use this to ensure that a TFM file is a proper match for a font, +and that its contents are suitable. . -The information includes the values of important TFM tags, -and a listing +The information includes the values of important TFM tags and a listing (by MSL number for Intellifont TFM files or by Unicode value for TrueType TFM files) of the glyphs included in the TFM file. @@ -329,7 +323,7 @@ italic correction is equal to thousandths of an em plus the amount by which the right edge of the glyphs's bounding box is to the right of its origin. . -If this would result in a negative italic correction, +If a negative italic correction would result, use a zero italic correction instead. . . @@ -337,8 +331,8 @@ use a zero italic correction instead. Also generate a subscript correction equal to the product of the tangent of the slant of the font and four fifths of the x-height of the font. . -If this would result in a subscript correction greater than the italic -correction, +If a subscript correction greater than the italic correction would +result, use a subscript correction equal to the italic correction instead. . . @@ -411,10 +405,11 @@ is a .MR make 1 script that uses .MR hpftodit @MAN1EXT@ -to prepare the foregoing font description files from HP TFM data; -in can be used to regenerate the +to prepare the .I groff -font descriptions in the event the TFM files are updated. +font description files above from HP TFM data; +in can be used to regenerate them in the event the TFM files are +updated. . . .TP @@ -436,7 +431,7 @@ later. .I @FONTDIR@/\:\%devlj4/\:\%generate/\:text\:.map .TQ .I @FONTDIR@/\:\%devlj4/\:\%generate/\:\%wingdings.map -map MSL indices and HP Unicode Private Use Area assignments to +map MSL indices and HP Unicode PUA assignments to .I groff special character identifiers. . commit c90e16f8f011dde3ae4522217f4e86d954adbd7d Author: G. Branden Robinson AuthorDate: Sat Apr 16 19:16:28 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 19:16:28 2022 +1000 nroff(1): Fix style nits. * Remove comma from internal reference phrase. * Tighten wording. diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man index d61a81d4e..ddc5cc62a 100644 --- a/src/roff/nroff/nroff.1.man +++ b/src/roff/nroff/nroff.1.man @@ -129,7 +129,7 @@ It first tries the .MR locale 1 program, then checks several locale-related environment variables; -see section \[lq]Environment\[rq], below. +see section \[lq]Environment\[rq] below. . If all of the foregoing fail, .B \-Tascii @@ -296,9 +296,9 @@ defines fallback definitions of special characters. . These definitions more poorly optically approximate typeset output -compared to those of the -.I tty -macro file in favor of communicating semantic information. +compared to those of +.I tty.tmac +in favor of communicating semantic information. . .I nroff loads it automatically. commit ff546e0badc3877c5fb2a35b9be62ee40c64c260 Author: G. Branden Robinson AuthorDate: Sat Apr 16 18:53:58 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 18:54:45 2022 +1000 preconv(1): Fix style nits. * Use indentation of 4n for numbered list. * Tighten wording. diff --git a/src/preproc/preconv/preconv.1.man b/src/preproc/preconv/preconv.1.man index 0f5648745..5661f6d59 100644 --- a/src/preproc/preconv/preconv.1.man +++ b/src/preproc/preconv/preconv.1.man @@ -129,7 +129,7 @@ tries to find the input encoding with the following algorithm, stopping at the first success. . . -.IP 1. +.IP 1. 4n If the input encoding has been explicitly specified with option .BR \-e , use it. @@ -500,13 +500,11 @@ if all detection methods fail. . .TP .BI \-e\~ encoding -Override detection procedure and assume -.IR encoding . -. -This corresponds to +Skip detection and assume +.IR encoding ; +see .IR groff 's -.RB \[lq] \-K -.IR encoding \[rq] +.B \-K option. . . commit 94cbdb12d0272957d7f0a15b8aafea01e693ee02 Author: G. Branden Robinson AuthorDate: Sat Apr 16 18:46:08 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 18:54:45 2022 +1000 troff(1): Clarify meaning of 'char' warning. diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man index 98d558416..21378e935 100644 --- a/src/roff/troff/troff.1.man +++ b/src/roff/troff/troff.1.man @@ -523,7 +523,7 @@ This category is enabled by default. . .TP .BR char "\t1" -An undefined glyph was requested for output. +No mounted font defines the glyph requested for formatting. . .RB (\[lq] char \[rq] is a misnomer since it reports missing glyphs\[em]there are no commit bbd5ea1219a0a86a038b0b9b48568a91660305ca Author: G. Branden Robinson AuthorDate: Sat Apr 16 18:44:06 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 18:54:45 2022 +1000 groff_font(5): Fix semicolon splice. diff --git a/man/groff_font.5.man b/man/groff_font.5.man index 5640de498..ae369da58 100644 --- a/man/groff_font.5.man +++ b/man/groff_font.5.man @@ -883,8 +883,8 @@ all glyphs might have a type of zero. .TP 0 means the glyph lies entirely between the baseline and -a horizontal line at the \[lq]x-height\[rq] of the font; -typical examples are \[lq]a\[rq], +a horizontal line at the \[lq]x-height\[rq] of the font, +like as \[lq]a\[rq], \[lq]c\[rq], and \[lq]x\[rq]; commit 4d95c0576327c143491df859a09e684214c8b8ee Author: G. Branden Robinson AuthorDate: Sat Apr 16 18:39:36 2022 +1000 Commit: G. Branden Robinson CommitDate: Sat Apr 16 18:54:35 2022 +1000 eqn(1): Fix style and markup nits. * Use `P` macro instead of `LP`. * Indent bulleted paragraphs by only 2n. * Tighten wording. diff --git a/src/preproc/eqn/eqn.1.man b/src/preproc/eqn/eqn.1.man index 087cb4bde..70ea7a60b 100644 --- a/src/preproc/eqn/eqn.1.man +++ b/src/preproc/eqn/eqn.1.man @@ -173,11 +173,11 @@ below; these may safely be ignored if you do not know \*[tx]. . . -.LP +.P Three points are worth special note. \" good, bad, and different . . -.IP \[bu] +.IP \[bu] 2n GNU .I eqn \" GNU emits Presentation MathML output when invoked with the @@ -290,8 +290,8 @@ type "binary" \[rs](mu . . .IP -The name of the type doesn't have to be quoted, -but quoting it protects it from macro expansion. +The type name doesn't have to be quoted, +but doing so protects it from macro expansion. . . .TP