runtime(doc): Update advice for [gnt]roff users
Commit:
https://github.com/vim/vim/commit/638bbc57c151b0360d953e1e4ad372e3c9f0d3ce
Author: G. Branden Robinson <[email protected]>
Date: Sun Jan 18 21:14:52 2026 +0000
runtime(doc): Update advice for [gnt]roff users
Content:
* Offer more specific guidance regarding input line breaks and sentence
endings.
* Advise what to do when a line ends with sentence-ending punctuation
but doesn't end a sentence.
* Advise against use of blanks lines and leading spaces for formatting
when a macro package is in use.
* Advise how to achieve visual separation in the document without
affecting formatting.
* Point out how the newline/end-of-sentence rules aid diffing.
* Distinguish the separate processes of inter-sentence space
supplementation and filling.
* Use conventional (but accessible) terms from typography instead of
more casual, approximate ones.
* Clarify what sort of extension the ms package's `XP` macro is.
Style:
* Fix comma splice with a semicolon.
* Use slightly more standard/idiomatic English.
Sources:
* https://rhodesmill.org/brandon/2012/one-sentence-per-line/
*
https://www.ualberta.ca/en/computing-science/media-library/docs/unix-beginners.pdf
(p. 20)
*
https://www.gnu.org/software/groff/manual/groff.html.node/Input-Conventions.html
*
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/doc/ms.ms?h=1.23.0#n1131
* https://docs-archive.freebsd.org/44doc/usd/18.msdiffs/paper.pdf
closes: #19193
Signed-off-by: G. Branden Robinson <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 700d51c21..95317823e 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 06
+*syntax.txt* For Vim version 9.1. Last change: 2026 Jan 18
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -2719,33 +2719,33 @@ 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
+\[year]. Macro requests can be longer than 2 characters; for example, GNU mm
accepts the requests ".VERBON" and ".VERBOFF" for creating verbatim
environments.
In order to obtain the best formatted output g/troff can give you, you should
follow a few simple rules about spacing and punctuation.
-1. Do not leave empty spaces at the end of lines.
+1. Break the line (put a carriage return) at the end of every sentence. Don't
+ permit trailing spaces before the newline.
-2. Leave one space and one space only after an end-of-sentence period,
- exclamation mark, etc.
+2. If a line ends with a period, question mark, or exclamation point that does
+ not end a sentence, follow it with the dummy character escape sequence \&.
-3. For reasons stated below, it is best to follow all period marks with a
- carriage return.
+3. If you're using a macro package, employ its paragraphing macros to achieve
+ indentation of paragraphs and spacing between them.
-The reason behind these unusual tips is that g/n/troff have a line breaking
-algorithm that can be easily upset if you don't follow the rules given above.
+4. Use the empty request, a '.' on a line by itself, freely to visually
+ separate material for ease of document maintenance.
-Unlike TeX, troff fills text line-by-line, not paragraph-by-paragraph and,
-furthermore, it does not have a concept of glue or stretch, all horizontal and
-vertical space input will be output as is.
+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.
-Therefore, you should be careful about not using more space between sentences
-than you intend to have in your final document. For this reason, the common
-practice is to insert a carriage return immediately after all punctuation
-marks. If you want to have "even" text in your final processed output, you
-need to maintain regular spacing in the input text. To mark both trailing
+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
+must maintain consistent spacing in the input text. To mark both trailing
spaces and two or more spaces after a punctuation as an error, use: >
:let nroff_space_errors = 1
@@ -2765,11 +2765,11 @@ file: >
let b:preprocs_as_sections = 1
-As well, the syntax file adds an extra paragraph marker for the extended
-paragraph macro (.XP) in the ms package.
+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 for enabling
-groff syntax highlighting either on a file basis or globally by default.
+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.
OCAML *ocaml.vim* *ft-ocaml-syntax*
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1vha6z-0022aG-BE%40256bit.org.
