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).  `\n(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.robinson@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 95317823e5264f730b1231f2945cc1a34683905b..8989e6937719b43bfe1df166b105826949bf0820 100644 (file)
--- 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*