From: G. Branden Robinson Date: Sun, 18 Jan 2026 21:14:52 +0000 (+0000) Subject: runtime(doc): Update advice for [gnt]roff users X-Git-Tag: v9.1.2095~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=638bbc57c151b0360d953e1e4ad372e3c9f0d3ce;p=thirdparty%2Fvim.git 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 Signed-off-by: Christian Brabandt --- diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 700d51c213..95317823e5 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*