[groff] 01/01: -ms: Add inter-paragraph space to .QS and .QE

[Carsten Kunze]

carstenkunze pushed a commit to branch master
in repository groff.

commit d2dbec050f357a945dab44da7954ebc3a27946f9
Author: Carsten Kunze <address@hidden>
Date:   Tue Feb 2 22:40:22 2016 +0100

    -ms: Add inter-paragraph space to .QS and .QE
    
    In the groff implementation of -ms .QS/.QE had been derived from
    .RS/.RE.  Since the latter macros don't add vertical space this had
    been the behaviour of .QS/.QE too.  Although it is not clear and
    unambiguously documented that they insert space it is consistent if
    they behave like .QP.
    
    The documentation of -ms .QP, .QS, and .QE in the manual and info page
    had been made more detailed.
    
    The issue had been reported by Douglas McIlroy <address@hidden>
    (See mail thread starting at
    http://lists.gnu.org/archive/html/groff/2016-01/msg00033.html)
---
 ChangeLog           |   16 ++++++++++++++++
 doc/groff.texi      |   21 ++++++++++++++++++---
 tmac/groff_ms.7.man |   38 +++++++++++++++++++++++++++++++++++++-
 tmac/s.tmac         |    6 ++++++
 4 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8c1dbc4..4f4c7a8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2016-02-02  Carsten Kunze  <address@hidden>
+
+       * tmac/s.tmac: Macros .QS and .QE changed to insert vertical
+       inter-paragraph space.  A paragraph bracketed with .QS/.QE
+       should appear identical to a .QP paragraph followed by .LP.
+
+       * tmac/groff_ms.7.man, doc/groff.texi: Documentation of macros
+       .QS and .QE added and .QP information improved (effect of
+       registers QI and PD).
+
+       See also discussion at address@hidden, thread starting at
+
+       http://lists.gnu.org/archive/html/groff/2016-01/msg00033.html
+
+       Issue reported by Douglas McIlroy <address@hidden>
+
 2015-12-26  Carsten Kunze  <address@hidden>
 
        * contrib/mm/m.tmac: Disable macro address@hidden in case output
diff --git a/doc/groff.texi b/doc/groff.texi
index e781486..8db136e 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3089,7 +3089,8 @@ Default: address@hidden
 @endDefmpreg
 
 @Defmpreg {QI, ms}
-Defines the indentation on both sides of a quoted (@code{QP} macro)
+Defines the indentation on both sides of a quoted (@code{QP},
address@hidden, and @code{QE} macros)
 paragraph.
 
 Effective: next paragraph.
@@ -3361,9 +3362,23 @@ Sets a paragraph without an initial indentation.
 @endDefmac
 
 @Defmac {QP, , ms}
-Sets a paragraph that is indented at both left and right margins.  The
-effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
+Sets a paragraph that is indented at both left and right margins
+by the amount of the register @code{QI}.
+The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
 The next paragraph or heading returns margins to normal.
address@hidden inserts vertical space of amount set by register @code{PD}
+before the paragraph.
address@hidden
+
address@hidden {QS, , ms}
address@hidden {QE, , ms}
+These macros begin and end a quoted section.
+The @code{QI} register
+controls the amount of indentation.
+Both @code{QS} and @code{QE} insert inter-paragraph vertical space
+set by register @code{PD}.
+The text between @code{QS} and @code{QE} can be structured further
+by use of the macros @code{LP} or @code{PP}.
 @endDefmac
 
 @Defmac {XP, , ms}
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 9464bab..53d868a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -386,13 +386,49 @@ macro to create paragraphs with no initial indent.
 .PP
 The
 .B QP
-macro indents all text at both left and right margins.
+macro indents all text at both left and right margins
+by the amount of the register
+.BR QI .
 .
 The effect is identical to the HTML
 .B <BLOCKQUOTE>
 .
 The next paragraph or heading returns margins to normal.
 .
+.B QP
+inserts the vertical space specified in register
+.B PD
+as inter-paragraph spacing.
+.
+.
+.PP
+A paragraph bracketed between the macros
+.B QS
+and
+.B QE
+has the same appearance as a paragraph started with
+.B QP
+and a following paragraph started with
+.BR LP .
+.
+Both
+.B QS
+and
+.B QE
+insert the inter-paragraph spacing specified in
+.B PD
+and the text is indented on both sides by the amount of
+.BR QI .
+.
+The text between
+.B QS
+and
+.B QE
+can be split into further paragraphs by using
+.B \&.LP
+or
+.BR \&.PP .
+.
 .
 .PP
 The
diff --git a/tmac/s.tmac b/tmac/s.tmac
index cf0eca8..190ee11 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -1298,6 +1298,10 @@ along with this program. If not, see 
<http://www.gnu.org/licenses/>.
 .\}
 .el address@hidden unbalanced \\$0
 address@hidden
+.if '\\$0'QE' \{\
+.      sp \\n[\\n[.ev]:PD]u
+.      ne \\n[PORPHANS]v+\\n(.Vu
+.\}
 ..
 .de @QS
 .br
@@ -1311,6 +1315,8 @@ along with this program. If not, see 
<http://www.gnu.org/licenses/>.
 .nr \\n[.ev]:ri +\\n[QI]
 .nr \\n[.ev]:ai \\n[\\n[.ev]:PI]
 address@hidden
+.sp \\n[\\n[.ev]:PD]u
+.ne \\n[PORPHANS]v+\\n(.Vu
 ..
 .als @QE @RE
 .\" start boxed text