Commit: runtime(doc): Update [gnt]roff information

[Christian Brabandt]

runtime(doc): Update [gnt]roff information

Commit: https://github.com/vim/vim/commit/f338a2f1a6fdb89bd4764c38b4cf8954526b632e
Author: G. Branden Robinson <g.branden...@gmail.com>
Date: Tue Jan 20 19:12:26 2026 +0000

runtime(doc): Update [gnt]roff information

Content:
* Refer to the formatter as "GNU troff". Strictly, "groff" refers to
several things.[1] Since the context is the editing of input to the
formatter, GNU's troff program is most relevant choice.
* Refer to groff as distributions' default "typesetting" rather than
"text processing" package. Many text processing tools exist, and some
distributions (Alpine Linux, NetBSD, OpenBSD) have replaced groff with
mandoc[2] as their man page formatter.
* Mention that Plan 9 still ships an AT&T-derived troff; they even
maintain it.[3]
* Correct explanation of traditional `yr` register (1). `
(yr` is not
a request, but an escape sequence.[4]
* Correct explanation of traditional `yr` register (2). This register
has not interpolated a "2-digit year" since the year 2000; it now
interpolates a 3-digit one, because AT&T troff designed the `yr`
register with a Y2K bug in it.[5]
* Fix scrambled terminology. The phrase "macro request" confuses two
separate things: macros and requests.[6] Say instead "font, request,
register, macro, and string names"; these are the formatter object
types that people writing groff documents most often use.
* Refer to "groff's mm package" instead of "GNU mm". Strictly, this
package is in groff's "contrib" area, which implies that it's not
official GNU product. (To be fair, after shipping with groff for over
34 years,[7] I'm not sure how much distinction anyone perceives.)
* Motivate the newly added advice preferring macro package facilities
for paragraphing; this issue is distinct from aiding sentence boundary
detection, which until recently[8] was the only advice offered here.

Style:
* Condense introductory paragraphs.
* Refer to "language syntax" rather than "language primitives".
* Use slightly more idiomatic English.

While these revisions convey more information, they leave the line count
unchanged. I'll try to stop fooling with this material now.

Notes:
[1] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/man/groff.7.man?h=1.24.0.rc1#n303
[2] https://mandoc.bsd.lv/
[3] https://github.com/9fans/plan9port/pull/738
https://github.com/9front/9front/commit/4f3a4d8b3da7e7f38b4bc392524944f6f9ccf21f
[4] https://www.gnu.org/software/groff/manual/groff.html.node/Formatter-Instructions.html
https://github.com/mamccollum/troff-resources/blob/main/cstr-54.pdf
[5] Tellingly, groff added the `year` register in its 1.16 release,
dated 2000-05-23.
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/NEWS?h=1.24.0.rc1#n3650
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/ChangeLog.116?h=1.24.0.rc1#n261
[6] https://www.gnu.org/software/groff/manual/groff.html.node/Requests-and-Macros.html
https://www.gnu.org/software/groff/manual/groff.html.node/groff.html_fot.html#FOOT26
[7] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/NEWS?h=1.24.0.rc1#n4192
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/ChangeLog.old?h=1.24.0.rc1#n2714
[8] https://github.com/vim/vim/commit/638bbc57c151b0360d953e1e4ad372e3c9f0d3ce

closes: #19221

Signed-off-by: G. Branden Robinson <g.branden...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 95317823e..8989e6937 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1,4 +1,4 @@
-*syntax.txt* For Vim version 9.1. Last change: 2026 Jan 18
+*syntax.txt* For Vim version 9.1. Last change: 2026 Jan 20


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -2702,26 +2702,23 @@ If you don't want to highlight these errors, leave it unset.

NROFF *nroff.vim* *ft-nroff-syntax*

-The nroff syntax file works with AT&T n/troff out of the box. You need to
-activate the GNU groff extra features included in the syntax file before you
-can use them.
-
-For example, Linux and BSD distributions use groff as their default text
-processing package. In order to activate the extra syntax highlighting
-features for groff, arrange for files to be recognized as groff (see
+The nroff syntax file works with AT&T n/troff as-is. To support GNU troff
+(groff), which Linux and BSD distributions use as their default typesetting
+package, arrange for files to be recognized as groff input (see
|ft-groff-syntax|) or add the following option to your start-up files: >

:let nroff_is_groff = 1

-Groff is different from the old AT&T n/troff that you may still find in
-Solaris. Groff macro and request names can be longer than 2 characters and
-there are extensions to the language primitives. For example, in AT&T troff
-you access the year as a 2-digit number with the request \(yr. In groff you
-can use the same request, recognized for compatibility, or you can use groff's
-native syntax, \[yr]. Furthermore, you can use a 4-digit year directly:
-\[year]. Macro requests can be longer than 2 characters; for example, GNU mm
-accepts the requests ".VERBON" and ".VERBOFF" for creating verbatim
-environments.
+GNU troff differs from older AT&T n/troff programs (that you may still find in
+Solaris or Plan 9) by extending the *roff language syntax. For example, in
+AT&T troff, you access the count of years since 1900 with the escape sequence
+\(yr. In groff you can do the same, which it recognizes for compatibility, or
+use groff's extended syntax, \[yr]. AT&T troff documented the yr register as
+storing the "last two digits of current year", but had a Y2K problem; in
+groff, you can access the Gregorian year correctly: \[year]. In groff, font,
+register, macro, string, and request names can exceed two characters; for
+example, with groff's mm package, the control lines ".VERBON" and ".VERBOFF"
+call macros of those names to bracket displays of "verbatim" content.

In order to obtain the best formatted output g/troff can give you, you should
follow a few simple rules about spacing and punctuation.
@@ -2741,7 +2738,10 @@ follow a few simple rules about spacing and punctuation.
The reason for these tips is that g/n/troff attempts to detect the ends of
sentences, and can use that information to apply inter-sentence space. Using
them also minimizes the size of diffs where lines change due only to refilling
-in the text editor.
+in the text editor. Macro packages typically employ inter-paragraph spacing
+amounts other than one vee (which is the result of a blank input line), and
+typically store that spacing amount, and that of paragraph indentation, in
+user-configurable registers so that pages lay out consistently.

Unlike TeX, troff fills text line-by-line, not paragraph-by-paragraph. If you
desire consistent spacing between words and sentences in formatted output, you
@@ -2769,7 +2769,7 @@ Further, the syntax file adds an extra paragraph marker for the XP
paragraphing macro in the ms package, a Berkeley and GNU extension.

Finally, there is a |groff.vim| syntax file that can be used to enable groff
-syntax highlighting either on a file basis or globally by default.
+syntax highlighting either on a per-file basis or globally by default.


OCAML *ocaml.vim* *ft-ocaml-syntax*