Hi folks, Just wanted to advise that I'll be traveling for a few days so my usual periodic burst of commits to groff Git's repo will be delayed.
I'm attaching the work that I have pending, in the event I should be eaten by a grue and don't return. :P It's just a snapshot; usually these things see some rebasing and modification before a real push. These are all/mostly documentation fix-ups; when I return I want to continue the build tidying process as the slog toward 1.23.0.rc2 continues. Probably need to bite the bullet and update the gnulib submodule to something relatively current. Bjarni has I think already tried this; if someone else would like to give it a spin, too, I'd appreciate it. See you soon! Regards, Branden
commit c3f585f8d54089b4adba47af6011fa067bc87277
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Fri Apr 22 01:24:13 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 17:15:46 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 14:07:47 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 14:06:34 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 14:03:30 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 14:02:03 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Mon Apr 18 12:48:08 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
- [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 <https://savannah.gnu.org/bugs/?58962>. Thanks to Dave
Kemper for the report, code review, and his suggestion to push
commit 47b813df96af684a1f3c8b262514664cd47552d3
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 22:40:24 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 19:02:39 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
+
+ * 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 <g.branden.robin...@gmail.com>
* 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 <http://www.gnu.org/licenses/>.
.\" .XH-UPDATE-TOC <outline-level> [<section-number>] <text>
.\" (<section-number> present only when called by XN)
.XS
-.shift\" don't use <outline-level> in rudimentary style
+.in (\\$1u - 1u * 2n)
+.shift
\&\\$*\" capture <section-number> (if present) and <text>
.XE
..
commit b51af6007cb8ff6c3faf086149e19ab6c4076b40
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 18:53:05 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
+
+ * tmac/s.tmac (XA): Drop apparently useless `ll` request. It
+ doesn't do anything according to my tests.
+
2022-04-15 G. Branden Robinson <g.branden.robin...@gmail.com>
* 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 <http://www.gnu.org/licenses/>.
. 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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 17:27:33 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <http://www.gnu.org/licenses/>.
.de XN de
.\" .XN <text>
.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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 16:35:56 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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
<https://savannah.gnu.org/bugs/?61022>, 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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 16:22:22 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <http://www.gnu.org/licenses/>.
.\" ****************************
.\" 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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 12:10:36 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sun Apr 17 11:52:08 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 19:32:00 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 19:16:28 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 18:53:58 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 18:46:08 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 18:44:06 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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 <g.branden.robin...@gmail.com>
AuthorDate: Sat Apr 16 18:39:36 2022 +1000
Commit: G. Branden Robinson <g.branden.robin...@gmail.com>
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
signature.asc
Description: PGP signature
