gbranden pushed a commit to branch master
in repository groff.
commit 2c1f763ec2ca9365b61aa0acb6161e34f9af3c9f
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun May 10 06:55:35 2026 -0500
[man]: Begin implementing new `LS` and `LE` macros.
* tmac/an.tmac (LS): New interface macro starts (opens) a list
enclosure.
(LE): New interface macro ends (closes) a list enclosure.
(an*list-close-all): New macro recursively closes all lists.
(an*end-document, SH, SS): Call `an*list-close-all`.
(an*break-paragraph): Recognize argument to permit override of
inter-paragraph spacing application by checking list context for
"compactness".
(TP, IP, HP): Call `an*break-paragraph` with an argument, thereby
checking for override of inter-paragraph spacing application.
* tmac/groff_man.7.man.in (Description): Document it. Add new macro
names to initial table thereof.
(List enclosure macros): New subsection specifies them.
Begins fixing <https://savannah.gnu.org/bugs/?68335>.
---
ChangeLog | 22 +++++++++++
tmac/an.tmac | 101 +++++++++++++++++++++++++++++++++++++++++++++---
tmac/groff_man.7.man.in | 85 ++++++++++++++++++++++++++++++++++++++--
3 files changed, 200 insertions(+), 8 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index c044e1b09..0a1994d47 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+2026-05-11 G. Branden Robinson <[email protected]>
+
+ [man]: Begin implementing new `LS` and `LE` macros.
+
+ * tmac/an.tmac (LS): New interface macro starts (opens) a list
+ enclosure.
+ (LE): New interface macro ends (closes) a list enclosure.
+ (an*list-close-all): New macro recursively closes all lists.
+ (an*end-document, SH, SS): Call `an*list-close-all`.
+ (an*break-paragraph): Recognize argument to permit override of
+ inter-paragraph spacing application by checking list context for
+ "compactness".
+ (TP, IP, HP): Call `an*break-paragraph` with an argument,
+ thereby checking for override of inter-paragraph spacing
+ application.
+
+ * tmac/groff_man.7.man.in (Description): Document it. Add new
+ macro names to initial table thereof.
+ (List enclosure macros): New subsection specifies them.
+
+ Begins fixing <https://savannah.gnu.org/bugs/?68335>.
+
2026-05-09 G. Branden Robinson <[email protected]>
* src/devices/xditview/xditview.am: Fix race when running
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 5a86c22ab..ebe6901d5 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -4,7 +4,7 @@
.
.\" Copyright 1989-2024 Free Software Foundation, Inc.
.\" 2001 Ruslan Ermilov
-.\" 2020-2025 G. Branden Robinson
+.\" 2020-2026 G. Branden Robinson
.\"
.\" Written by James Clark ([email protected])
.\" Enhanced by: Werner Lemberg <[email protected]>
@@ -103,6 +103,7 @@
.de1 an*end-document
. an*input-trap
. if '\\n[.z]'an*paragraph-tag' .an*TP-trap
+. an*list-close-all
. if \\n[cR] \{\
. sp 1v
. an-footer
@@ -765,16 +766,22 @@ contains unsupported escape sequence
..
.
.\" Break a paragraph. Restore defaults, except for indentation.
+.\" The presence of an argument means "check for a compact list".
.de an*break-paragraph
. an*reset-paragraph-parameters
-. sp \\n[PD]u
+. nr an*want-space 1
+. if ((\\n[.$] > 0) & (\\n[an*list-depth] > 0)) \
+. if \\n[an*list-is-compact!\\n[an*list-depth]] .nr an*want-space 0
+. if \\n[an*want-space] .sp \\n[PD]u
. ns
+. rr an*want-space
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) as a section heading.
.de1 SH
. if \\n[.it] .an-warn cannot call .\\$0 while an input trap is pending
+. an*list-close-all
. an*reset-section-parameters
. an*break-paragraph
. fi
@@ -804,6 +811,7 @@ contains unsupported escape sequence
.\" if none) as a subsection heading.
.de1 SS
. if \\n[.it] .an-warn cannot call .\\$0 while an input trap is pending
+. an*list-close-all
. an*reset-section-parameters
. an*break-paragraph
. fi
@@ -892,8 +900,13 @@ contains unsupported escape sequence
.\" .TP [indent]
.de1 TP
. if \\n[.it] .an-warn cannot call .\\$0 while an input trap is pending
-. an*break-paragraph
+. an*break-paragraph 1
. if \\n[.$] .nr an*prevailing-indent (n;\\$1)
+.\"el \{\
+.\" if (\\n[an*list-depth] > 0)
+.\" if !'\?\\*[an*list-indent!\\n[an*list-depth]]\?'\?\?' \
+.\" nr an*prevailing-indent \\*[an*list-indent!\\n[an*list-depth]]
+.\"\}
. if '\\n[.z]'an*paragraph-tag' \{\
. an-warn cannot nest .\\$0 or .TQ inside .\\$0; supply a tag
. return
@@ -912,7 +925,7 @@ contains unsupported escape sequence
.de1 IP
. nr an*enforce-tag-separation 0
. ie !\\n[.$] \{\
-. an*break-paragraph
+. an*break-paragraph 1
. ne (1v + 1u)
. in (\\n[an*margin]u + \\n[an*prevailing-indent]u)
. \}
@@ -927,10 +940,15 @@ contains unsupported escape sequence
.\" Set a paragraph with a hanging indentation.
.\" .HP [indent]
.de1 HP
-. an*break-paragraph
+. an*break-paragraph 1
. ll \\n[LL]u
. ne (1v + 1u)
. if \\n[.$] .nr an*prevailing-indent (n;\\$1)
+.\"el \{\
+.\" if (\\n[an*list-depth] > 0)
+.\" if !'\?\\*[an*list-indent!\\n[an*list-depth]]\?'\?\?' \
+.\" nr an*prevailing-indent \\*[an*list-indent!\\n[an*list-depth]]
+.\"\}
. in (\\n[an*margin]u + \\n[an*prevailing-indent]u)
. ti \\n[an*margin]u
. DEVTAG-COL 1
@@ -1406,6 +1424,79 @@ contains unsupported escape sequence
. hy \\n[an*hyphenation-mode]
..
.
+.\" === Support lists (groff 1.25). ===
+.\"
+.\" When authors of man(7) documents employ the deprecated `PD` macro at
+.\" all, they do so for one purpose only: to set lists more compactly.
+.\" Further, it is advantageous for HTML generation to distinguish
+.\" itemized, enumerated, and definition lists. Finally, we support a
+.\" parameter to specify the indentation used by the `IP`, `TP` (and
+.\" `HP`, for that matter) macros. This is advantageous becuse, if the
+.\" document author uses a non-default indentation--a cosmetic issue--
+.\" they have neither to remember to specify that parameter in the first
+.\" of their paragraph calls and maintain it there as list items change
+.\" or move over time, nor to tediously repeat the indentation amount in
+.\" each such macro call. See section "Notes" in groff_man_style(7).
+.\"
+.\" Specify list items with `IP` (if itemized or enumerated) or `TP` (if
+.\" tagged with semantically important terms, like language keywords).
+.\"
+.\" Lists can be nested. (Sub)sectioning macros, and the end of the
+.\" document, close all open lists.
+.\"
+.\" We designed this interface such that no document content is lost if
+.\" the formatter doesn't support these extension macros.
+.nr an*list-depth 0
+.
+.\" Start (or "open") a list.
+.\" .LS {definition|enumerated|itemized} [compactness] [indent]
+.de1 LS
+. if ((\\n[.$] < 1) : (\\n[.$] > 3)) \
+. an*style-warn .\\$0 expects 1 to 3 arguments, got \\n[.$]
+. ds an*list-type invalid\"
+. if '\?\\$1\?'\?definition\?' .ds an*list-type \\$1\"
+. if '\?\\$1\?'\?enumerated\?' .ds an*list-type \\$1\"
+. if '\?\\$1\?'\?itemized\?' .ds an*list-type \\$1\"
+. if '\?\\*[an*list-type]\?'\?invalid\?' \{\
+. ds an*msg invalid .\\$0 list type '\\*[an*list-type]':
+. as an*msg " assuming 'definition'
+. an-warn \\*[an*msg]
+. ds an*list-type definition\"
+. \}
+. nr an*list-is-compact 0
+. if (\\n[.$] > 1) \{\
+. ie !\B'\\$2' \
+. an-warn invalid .\\$0 compactness Boolean value '\\$2'; using 0
+. el .if \\$2 .nr an*list-is-compact 1
+. \}
+. ds an*list-indent \" empty
+. if (\\n[.$] > 2) \{\
+. ie !\B'\\$3' \
+. an-warn invalid .\\$0 indent '\\$3'; ignoring
+. el .ds an*list-indent \\$3\"
+. \}
+. nr an*list-depth +1
+. ds an*list-type!\\n[an*list-depth] \\*[an*list-type]\"
+. nr an*list-is-compact!\\n[an*list-depth] \\n[an*list-is-compact]
+. ds an*list-indent!\\n[an*list-depth] \\*[an*list-indent]\"
+. rm an*list-indent
+. rr an*list-is-compact
+. rm an*list-type
+. rm an*msg
+..
+.
+.\" End (or "close") the most recently unclosed list.
+.de1 LE
+. rm an*list-indent!\\n[an*list-depth]
+. rr an*list-is-compact!\\n[an*list-depth]
+. rm an*list-type!\\n[an*list-depth]
+. nr an*list-depth -1
+..
+.
+.de an*list-close-all
+. while (\\n[an*list-depth] > 0) .LE
+..
+.
.\" tbl(1) table support
.
.\" Start table.
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 17453d902..7dc56029b 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -63,7 +63,7 @@ _endif()dnl
.\"
.\" Copyright 1999-2017 Free Software Foundation, Inc.
.\" 2017 Ingo Schwarze
-.\" 2017-2025 G. Branden Robinson
+.\" 2017-2026 G. Branden Robinson
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
@@ -202,7 +202,9 @@ _
\&.IB Italic, bold alternating Font style macros
\&.IP Indented paragraph Paragraphing macros
\&.IR Italic, roman alternating Font style macros
+\&.LE End list List enclosure macros
\&.LP Begin paragraph Paragraphing macros
+\&.LS Start list List enclosure macros
\&.ME Mail-to end Hyperlink macros
\&.MR Man page cross reference Hyperlink macros
\&.MT Mail-to start Hyperlink macros
@@ -1070,6 +1072,78 @@ as seen in this very paragraph.
.
_endif()dnl
.\" ====================================================================
+.SS "List enclosure macros"
+.\" ====================================================================
+.
+Enclose paragraphing macros between
+.B LS
+and
+.B LE
+to mark them as list items.
+.
+Doing so can mark them as \[lq]compact\[rq]\" ,
+.\" ease management of their indentation,
+and supply hints to the output driver to improve their rendering
+(as with HTML).
+.
+Lists can be nested.
+.
+(Sub)sectioning macro calls,
+and the end of the document,
+close all open lists.
+.
+These macros are GNU extensions.
+.
+.
+.TP
+.BI .LS\~ type\~\c
+.RI [ compactness ]
+.\"RI [ compactness \~[ indentation ]
+.IR (since\~ groff \~1.25) \" TODO: remove note once novelty dies down
+Start
+(or open)
+a list.
+.
+.I type
+is one of
+.RB \%\[lq] definition \[rq],
+.RB \%\[lq] enumerated \[rq],
+or
+.RB \%\[lq] itemized \[rq].
+.
+.I compactness
+is a Boolean value directing suppression of inter-paragraph spacing
+between list items.
+.
+.\".I indentation
+.\"specifies an indentation amount for the body of each list item;
+.\"it is then unnecessary to specify this argument to the list item macros.
+.
+Use
+.B IP
+with
+a mark argument to represent an itemized or enumerated list item,
+and
+.B TP
+for a definition list item.
+.
+Use
+.B IP
+without arguments to associate successive paragraphs
+with an existing list item;
+to these,
+inter‐paragraph spacing applies even in compact lists.
+.
+.
+.TP
+.B .LE
+.IR (since\~ groff \~1.25) \" TODO: remove note once novelty dies down
+End
+(or close)
+the most recent open list.
+.
+.
+.\" ====================================================================
.SS "Synopsis macros"
.\" ====================================================================
.
@@ -4987,7 +5061,7 @@ and the
macro for
.I groff
1.23 (2023),
-and the
+the
.BR BP ,
.BR PO ,
and
@@ -4997,7 +5071,12 @@ and a revised implementation of the
.BR SY / YS
macros for
.I groff
-1.24 (2026).
+1.24 (2026);
+and the
+.BR LS / LE
+macros for
+.I groff
+1.25 (2026).
.
.
.P
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
