[groff] 01/01: Call out altered behavior of .sp in -me documents.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7a83f7f5003e24f020306f09f4d497e04e82cb14
Author: G. Branden Robinson <address@hidden>
Date:   Sun Nov 4 01:47:55 2018 -0400

    Call out altered behavior of .sp in -me documents.
    
        * doc/meintro.me:
        * doc/meref.me:
        * doc/groff_me.7.man: Explain that .sp will not generate
        vertical space at the top of the page, and that .bl must be used
        if that behavior is desired.
    
        Based on a patch by Dave Kemper originally submitted in 2011(!);
        thanks to Dave for his reminders and Herculean patience.
    
        Fixes <https://savannah.gnu.org/bugs/index.php?40967>.
    
        * doc/groff_me.7.man: Also stop using the .UC macro; this
        implementation of "me" is not {part of, maintained by} a
        Berkeley distribution.  A quick grep indicates that no other
        groff man pages are using .AT or .UC.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 doc/meintro.me      |  8 ++++++++
 doc/meref.me        |  6 +++---
 tmac/groff_me.7.man | 15 ++++++++++++++-
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/doc/meintro.me b/doc/meintro.me
index 61965f2..512d47b 100644
--- a/doc/meintro.me
+++ b/doc/meintro.me
@@ -456,6 +456,14 @@ followed by the line
 .q "My thoughts on the subject" ,
 followed by a single blank line.
 .pp
+This request will not leave space at the top of a page.
+If you need the requested space to appear regardless of page position,
+use the
+.b .bl
+macro, which has the same syntax as
+.b .sp
+but always leaves the requested space, even at the top of a page.
+.pp
 The
 .b .in \ \c
 .i +N
diff --git a/doc/meref.me b/doc/meref.me
index 62b9958..2f7f26c 100644
--- a/doc/meref.me
+++ b/doc/meref.me
@@ -1298,7 +1298,7 @@ Leave
 contiguous white space,
 on the next page if not enough room
 on this page.
-Equivalent to a
+Equivalent to putting a
 .b .sp
 .i N
 inside a block.
@@ -2088,7 +2088,7 @@ NAME      TYPE    DESCRIPTION
 \&.bc  M       begin new column
 \&.bi  M       bold italic
 \en(bi R       display (block) indent
-\&.bl  M       blank lines (even at top of page)
+\&.bl  M       blank lines (even at top of page, in contrast to .sp)
 \en(bm R       bottom title margin
 \&.bp  M\(sc   begin page
 \&.br  M\(sc   break (start new line)
@@ -2198,7 +2198,7 @@ NAME      TYPE    DESCRIPTION
 \&.sm  M       set argument in a smaller pointsize
 \&.so  M\(sc   source input file
 \en(so R       additional section title offset
-\&.sp  M\(sc   vertical space
+\&.sp  M\(sc   vertical space (except at top of page, in contrast to .bl)
 \en(sp R       section title pointsize
 \en(ss R       section prespace
 \&.sx  M       change section depth
diff --git a/tmac/groff_me.7.man b/tmac/groff_me.7.man
index e5e7fad..44b9f0f 100644
--- a/tmac/groff_me.7.man
+++ b/tmac/groff_me.7.man
@@ -1,7 +1,6 @@
 '\" t
 .hc %
 .TH GROFF_ME @MAN7EXT@ "@MDATE@" "@VERSION@"
-.UC 3
 .SH NAME
 groff_me \- \(lqme\(rq macro package for formatting documents with GNU roff
 .
@@ -87,6 +86,20 @@ l l.
 \fB.ul\fP \fIn\fP      underline next \fIn\fP lines
 .TE
 .PP
+.I Note:
+In contrast to its behavior with other macro packages and \(lqraw\(rq
+.IR roff ,
+when using the
+.I me
+package,
+the
+.B .sp
+request will
+.I not
+put space at the top of a page.
+.
+.
+.PP
 Output of the
 .IR pic ,
 .IR eqn ,