neovim

Neovim text editor
git clone https://git.dasho.dev/neovim.git
Log | Files | Refs | README

commit 68e0b1bd0163bded3d957b77a1dcb74507cb8bec
parent 15b9118ac0b6afabe821369e7a8bea8776bee416
Author: zeertzjq <zeertzjq@outlook.com>
Date:   Wed, 21 Jan 2026 06:58:21 +0800

vim-patch:f338a2f: runtime(doc): Update [gnt]roff information (#37476)

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: vim/vim#19221

https://github.com/vim/vim/commit/f338a2f1a6fdb89bd4764c38b4cf8954526b632e

Co-authored-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Diffstat:
Mruntime/doc/syntax.txt | 36++++++++++++++++++------------------
1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt @@ -2212,26 +2212,23 @@ If you don't want to highlight these errors, leave it unset. NROFF *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. @@ -2251,7 +2248,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 @@ -2278,7 +2278,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 |ft-groff-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 *ft-ocaml-syntax*