]> git.ipfire.org Git - thirdparty/vim.git/commit
runtime(doc): Update [gnt]roff information
authorG. Branden Robinson <g.branden.robinson@gmail.com>
Tue, 20 Jan 2026 19:12:26 +0000 (19:12 +0000)
committerChristian Brabandt <cb@256bit.org>
Tue, 20 Jan 2026 19:12:26 +0000 (19:12 +0000)
commitf338a2f1a6fdb89bd4764c38b4cf8954526b632e
tree403af320afb6a4da54ea2f4414c43d1a830d0cab
parentcbb72e42160f0b827a748ebacd995ebbadbab4e5
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>
runtime/doc/syntax.txt