[groff] 01/01: roff(7): Reorganize and expand "EDITING ROFF".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit af69dcaf67fcdb31e3ca60a9b87d11dc1da0f14b
Author: G. Branden Robinson <address@hidden>
Date:   Mon Nov 6 10:30:16 2017 -0500

    roff(7): Reorganize and expand "EDITING ROFF".
    
    * Move editor-program-neutral material to the beginning of the section.
    
    * Make subsections for Emacs and Vim material.
    
    * Expand material on Vim so it actually offers guidance.
    
    * Render "Xemacs" as "XEmacs" as that appears to be the maintainers'
      preference.
    
    * Add comment justifying placement of Vim modelines.
    
    * Add comment indicating future directions.
    
    * Style fix: gerund -> infinitive and use a better verb in any case.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 man/roff.7.man | 173 ++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 110 insertions(+), 63 deletions(-)

diff --git a/man/roff.7.man b/man/roff.7.man
index 8a92ab8..4e6e2f6 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -984,9 +984,81 @@ can be found at
 .SH "EDITING ROFF"
 .\" ====================================================================
 .
+All
+.I roff
+formatters provide automated line breaks and horizontal and vertical
+spacing.
+.
+In order to not disturb this, the following tips can be helpful.
+.
+.IP \(bu
+Never include empty or blank lines in a
+.I roff
+document.
+.
+Instead, use the empty request (a line consisting of a dot only) or a
+line comment
+.B .\[rs]"\""
+if a structuring element is needed.
+.
+.IP \(bu
+Never start a line with whitespace because this can lead to unexpected
+behavior.
+.
+Indented paragraphs can be constructed in a controlled way by
+.I roff
+requests.
+.
+.IP \(bu
+Start each sentence on a line of its own, for the spacing after a dot
+is handled differently depending on whether it terminates an
+abbreviation or a sentence.
+.
+To distinguish both cases, do a line break after each sentence.
+.
+.IP \(bu
+To additionally use the auto-fill mode in Emacs, it is best to insert
+an empty
+.I roff
+request (a line consisting of a dot only) after each sentence.
+.
+.
+.P
+The following example shows judicious line breaking in a
+.I roff
+input file.
+.
+.RS
+.P
+.EX
+.\" Keep the text width to 65 columns or fewer in this example so that
+.\" it doesn't overrun the right margin when set in Courier (-Tps,
+.\" -Tpdf).
+This is an example of a
+\&.I roff
+document that you can type into your text editor.
+\&.
+.
+This is the next sentence in the same paragraph.
+\&.
+.
+This is a longer sentence stretching over several input lines;
+abbreviations like cf. are easily identified because the dot is
+not followed by a line break.
+\&.
+.
+In the output, this sentence continues the same paragraph.
+.EE
+.RE
+.
+.
+.\" ====================================================================
+.SS "Editing with Emacs"
+.\" ====================================================================
+.
 The best program for editing a
 .I roff
-document is Emacs (or Xemacs), see
+document is Emacs (or XEmacs); see
 .BR emacs (1).
 .
 It provides an
@@ -1007,7 +1079,7 @@ means to hold down the
 .B Meta
 key (or
 .BR Alt )
-and hitting the
+and press the
 .BR x\~ key
 at the same time.
 .
@@ -1055,83 +1127,58 @@ Unfortunately, some applications such as the
 program are confused by this; so this is deprecated.
 .
 .
-.P
-All
-.I roff
-formatters provide automated line breaks and horizontal and vertical
-spacing.
+.\" ====================================================================
+.SS "Editing with Vim"
+.\" ====================================================================
 .
-In order to not disturb this, the following tips can be helpful.
+.\" TODO: elvis, vile.  Nvi does not support highlighting at all, and
+.\" gedit does but has no rules for roff yet.  Other editors TBD.
+Besides Emacs, some other editors provide
+.I nroff
+style files too, e.g.\&
+.BR vim (1),
+an extension of the
+.BR vi (1)
+program.
 .
-.IP \(bu
-Never include empty or blank lines in a
+Vim's highlighting can be made to recognize
 .I roff
-document.
-.
-Instead, use the empty request (a line consisting of a dot only) or a
-line comment
-.B .\[rs]"\""
-if a structuring element is needed.
+files by setting the
+.I filetype
+option in a Vim
+.IR modeline .
 .
-.IP \(bu
-Never start a line with whitespace because this can lead to unexpected
-behavior.
+For this feature to work, your copy of
+.B vim
+must be built with support for, and configured to enable, several
+features; consult the editor's online help topics
+\[lq]auto\-setting\[rq], \[lq]filetype\[rq], and \[lq]syntax\[rq].
 .
-Indented paragraphs can be constructed in a controlled way by
+Then put the following at the end of your
 .I roff
-requests.
-.
-.IP \(bu
-Start each sentence on a line of its own, for the spacing after a dot
-is handled differently depending on whether it terminates an
-abbreviation or a sentence.
-.
-To distinguish both cases, do a line break after each sentence.
-.
-.IP \(bu
-To additionally use the auto-fill mode in Emacs, it is best to insert
-an empty
-.I roff
-request (a line consisting of a dot only) after each sentence.
-.
+files, after any Emacs configuration:
+.\" ...because Emacs pattern-matches against ~3000 bytes from the end of
+.\" the buffer for "Local variables:", but Vim only checks as many lines
+.\" as its 'modelines' variable tells it to.  A common default is "5",
+.\" but Emacs settings can be longer than that.
 .
 .P
-The following example shows judicious line breaking in a
-.I roff
-input file.
 .
 .RS
-.P
+.IP
 .EX
-.\" Keep the text width to 65 columns or fewer in this example so that
-.\" it doesn't overrun the right margin when set in Courier (-Tps,
-.\" -Tpdf).
-This is an example of a
-\&.I roff
-document that you can type into your text editor.
-\&.
-.
-This is the next sentence in the same paragraph.
-\&.
-.
-This is a longer sentence stretching over several input lines;
-abbreviations like cf. are easily identified because the dot is
-not followed by a line break.
-\&.
-.
-In the output, this sentence continues the same paragraph.
+\&.\[rs]" vim: set filetype=groff:
 .EE
 .RE
 .
 .
 .P
-Besides Emacs, some other editors provide
-.I nroff
-style files too, e.g.\&
-.BR vim (1),
-an extension of the
-.BR vi (1)
-program.
+Replace \[lq]groff\[rq] in the above with \[lq]nroff\[rq] if you want
+highlighing that does
+.I not
+recognize many of the \f[CR]GNU\f[] extensions to
+.IR roff ,
+such as request, register, and string names longer than two characters.
 .
 .
 .\" ====================================================================