Fix computation of .trunc register. Additionally, its value (and

the value of the .ne register) is now always set before entering the
trap.

* src/roff/troff/div.cc (diversion::need): Set `truncated_space' and
`needed_space' before calling `space'.
(top_level_diversion::space): Remove special code for 'sp before the
first page.
Call `begin_page' with the discarded space as a parameter.
(top_level_diversion::begin_page): Add optional parameter to set
`truncated_space'.
* src/roff/troff/div.h: Updated.

* doc/groff.texinfo: Improve documentation of .sp, \n[.trunc], and
\n[.ne].

* tmac/an-old.tmac (SH, SS, TP, IP, HP, TS): Undo change 2002-10-26.
(LP): Remove superfluous call to `br'.
* tmac/doc-common (doc-paragraph): Undo change 2002-10-26.
* tmac/doc.tmac (Bd, Bl, doc-set-vertical-and-indent): Ditto.

7 files changed, 93 insertions, 35 deletions

diff --git a/ChangeLog b/ChangeLog
index ce405969..1f478b8f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,26 @@
+2002-10-29  Werner LEMBERG  <wl@gnu.org>
+
+	Fix computation of .trunc register.  Additionally, its value (and
+	the value of the .ne register) is now always set before entering the
+	trap.
+
+	* src/roff/troff/div.cc (diversion::need): Set `truncated_space' and
+	`needed_space' before calling `space'.
+	(top_level_diversion::space): Remove special code for 'sp before the
+	first page.
+	Call `begin_page' with the discarded space as a parameter.
+	(top_level_diversion::begin_page): Add optional parameter to set
+	`truncated_space'.
+	* src/roff/troff/div.h: Updated.
+
+	* doc/groff.texinfo: Improve documentation of .sp, \n[.trunc], and
+	\n[.ne].
+
+	* tmac/an-old.tmac (SH, SS, TP, IP, HP, TS): Undo change 2002-10-26.
+	(LP): Remove superfluous call to `br'.
+	* tmac/doc-common (doc-paragraph): Undo change 2002-10-26.
+	* tmac/doc.tmac (Bd, Bl, doc-set-vertical-and-indent): Ditto.
+
 2002-10-26  Werner LEMBERG  <wl@gnu.org>
 
 	* tmac/doc-ditroff: Remove useless switch/variable -rC.
@@ -9,10 +32,9 @@
 	* tmac/doc-common (doc-header): Call `ns'.
 	(doc-paragraph): Protect .sp with .br so that it survives traps
 	possibly set by the user.
-	* tmac/doc.tmac (Bp, Bl, doc-set-vertical-and-indent): Ditto.
+	* tmac/doc.tmac (Bd, Bl, doc-set-vertical-and-indent): Ditto.
 
-	* tmac/doc*:Replace ' with . for consistency in all mdoc-related
-	files if no effect.
+	* tmac/doc*: Replace ' with . for consistency if no effect.
 
 2002-10-26  Werner LEMBERG  <wl@gnu.org>
 
diff --git a/doc/groff.texinfo b/doc/groff.texinfo
index 3c02247b..32bf480b 100644
--- a/doc/groff.texinfo
+++ b/doc/groff.texinfo
@@ -6252,6 +6252,50 @@ Space downwards @var{distance}.  With no argument it advances 1@w{
 the specified distance.  If the argument is preceded by a @samp{|}
 then @code{gtroff} moves that distance from the top of the page.  This
 request causes a line break.  The default scaling indicator is @samp{v}.
+
+If a vertical trap is sprung during execution of @code{sp}, the amount of
+vertical space after the trap is discarded.  For example, this
+
+@Example
+.de xxx
+..
+.
+.wh 0 xxx
+.
+.pl 5v
+foo
+.sp 2
+bar
+.sp 50
+baz
+@endExample
+
+@noindent
+results in
+
+@Example
+foo
+
+
+bar
+
+baz
+@endExample
+
+@cindex @code{sp} request, and traps
+@cindex discarded space in traps
+@cindex space, discarded, in traps
+@cindex traps, and discarded space
+The amount of discarded space is available in the number register
+@code{.trunc}.
+
+To protect @code{sp} against vertical traps, use the @code{vpt} request:
+
+@Example
+.vpt 0
+.sp -3
+.vpt 1
+@endExample
 @endDefreq
 
 @DefreqList {ls, [@Var{nnn}]}
@@ -10569,6 +10613,8 @@ vertical position traps.  The parameter that controls whether vertical
 position traps are enabled is global.  Initially vertical position traps
 are enabled.  The current setting of this is available in the
 @code{.vpt} read-only number register.
+
+Note that a page can't be ejected if @code{vpt} is set to zero.
 @endDefreq
 
 @Defreq {wh, dist [@Var{macro}]}
@@ -10684,6 +10730,9 @@ The read-only number register @code{.ne} contains the amount of space
 that was needed in the last @code{ne} request that caused a trap to be
 sprung.  Useful in conjunction with the @code{.trunc} register.
 @xref{Page Control}, for more information.
+
+Since the @code{.ne} register is only set by traps and it doesn't make
+much sense to use it outside of trap macros.
 @endDefreg
 
 @Defreg {.trunc}
@@ -10696,6 +10745,9 @@ produced by the @code{ne} request.  In other words, at the point a trap
 is sprung, it represents the difference of what the vertical position
 would have been but for the trap, and what the vertical position
 actually is.
+
+Since the @code{.trunc} register is only set by traps and it doesn't make
+much sense to use it outside of trap macros.
 @endDefreg
 
 @c ---------------------------------------------------------------------
diff --git a/src/roff/troff/div.cc b/src/roff/troff/div.cc
index 14c73997..52e99e9a 100644
--- a/src/roff/troff/div.cc
+++ b/src/roff/troff/div.cc
@@ -153,9 +153,9 @@ void diversion::need(vunits n)
 {
   vunits d = distance_to_next_trap();
   if (d < n) {
-    space(d, 1);
     truncated_space = -d;
     needed_space = n;
+    space(d, 1);
   }
 }
 
@@ -438,12 +438,8 @@ void top_level_diversion::space(vunits n, int forced)
       no_space_mode = 0;
   }
   if (before_first_page) {
-    if (begin_page()) {
-      // This happens if there's a top of page trap, and the first-page
-      // transition is caused by `'sp'.
-      truncated_space = n > V0 ? n : V0;
-      return;
-    }
+    begin_page(n);
+    return;
   }
   vunits next_trap_pos;
   trap *next_trap = find_next_trap(&next_trap_pos);
@@ -459,7 +455,7 @@ void top_level_diversion::space(vunits n, int forced)
     nl_reg_contents = vertical_position.to_units();
   }
   else if (vertical_position_traps_flag && y >= page_length && n >= V0)
-    begin_page();
+    begin_page(y - page_length);
   else {
     vertical_position = y;
     nl_reg_contents = vertical_position.to_units();
@@ -550,9 +546,9 @@ void cleanup_and_exit(int exit_code)
   exit(exit_code);
 }
 
-// returns non-zero if it sprung a top of page trap
-
-int top_level_diversion::begin_page()
+// Returns non-zero if it sprung a top-of-page trap.
+// The optional parameter is for the .trunc register.
+int top_level_diversion::begin_page(vunits n)
 {
   if (exit_started) {
     if (page_count == last_page_count
@@ -589,7 +585,7 @@ int top_level_diversion::begin_page()
   before_first_page = 0;
   nl_reg_contents = vertical_position.to_units();
   if (vertical_position_traps_flag && next_trap != 0 && next_trap_pos == V0) {
-    truncated_space = V0;
+    truncated_space = n;
     spring_trap(next_trap->nm);
     return 1;
   }
@@ -770,7 +766,8 @@ void blank_line()
   if (!trap_sprung_flag && !curdiv->no_space_mode) {
     curdiv->space(curenv->get_vertical_spacing());
     curenv->add_html_tag(1, ".sp", 1);
-  } else
+  }
+  else
     truncated_space += curenv->get_vertical_spacing();
 }
 
diff --git a/src/roff/troff/div.h b/src/roff/troff/div.h
index 31b9af3c..bde41a8f 100644
--- a/src/roff/troff/div.h
+++ b/src/roff/troff/div.h
@@ -1,5 +1,6 @@
 // -*- C++ -*-
-/* Copyright (C) 1989, 1990, 1991, 1992, 2001 Free Software Foundation, Inc.
+/* Copyright (C) 1989, 1990, 1991, 1992, 2001, 2002
+   Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
 This file is part of groff.
@@ -123,7 +124,7 @@ public:
   int get_page_number() { return page_number; }
   int get_next_page_number();
   void set_page_number(int n) { page_number = n; }
-  int begin_page();
+  int begin_page(vunits = V0);
   void set_next_page_number(int);
   void set_page_length(vunits);
   void copy_file(const char *filename);
diff --git a/tmac/an-old.tmac b/tmac/an-old.tmac
index 3958c36d..56d1b91b 100644
--- a/tmac/an-old.tmac
+++ b/tmac/an-old.tmac
@@ -264,7 +264,6 @@
 .if \n[cR] .em an-end
 .
 .de1 SH
-.  br
 .  sp \\n[PD]u
 .  nr an-level 1
 .  set-an-margin
@@ -283,7 +282,6 @@
 ..
 .
 .de1 SS
-.  br
 .  sp \\n[PD]u
 .  nr an-level 1
 .  set-an-margin
@@ -326,7 +324,6 @@
 ..
 .
 .de1 TP
-.  br
 .  sp \\n[PD]u
 .  if \\n[.$] .nr an-prevailing-indent (n;\\$1)
 .  it 1 an-trap
@@ -394,7 +391,6 @@
 ..
 .
 .de1 LP
-.  br
 .  sp \\n[PD]u
 .  ps \\n[PS]u
 .  vs \\n[VS]u
@@ -411,7 +407,6 @@
 .    ps \\n[PS]u
 .    vs \\n[VS]u
 .    ft R
-.    br
 .    sp \\n[PD]u
 .    ne (1v + 1u)
 .    in (\\n[an-margin]u + \\n[an-prevailing-indent]u)
@@ -427,7 +422,6 @@
 .  ps \\n[PS]u
 .  vs \\n[VS]u
 .  ft R
-.  br
 .  sp \\n[PD]u
 .  ne (1v + 1u)
 .  if \\n[.$] .nr an-prevailing-indent (n;\\$1)
@@ -537,7 +531,6 @@
 .\" table support
 .
 .de1 TS
-.  br
 .  sp \\n[PD]u
 .  HTML-IMAGE
 ..
diff --git a/tmac/doc-common b/tmac/doc-common
index 8eafa0e1..0cc0ea17 100644
--- a/tmac/doc-common
+++ b/tmac/doc-common
@@ -615,7 +615,6 @@
 .\" NS   insert a paragraph
 .
 .de doc-paragraph
-.  br
 .  sp \n[doc-paragraph-space]u
 .  if !\n[cR] \
 .    ne 2
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index c872b093..589fcafe 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -2698,10 +2698,8 @@
 .  if \n[doc-display-indent-stack\n[doc-display-depth]] \
 .    in +\n[doc-display-indent-stack\n[doc-display-depth]]u
 .
-.  if !\n[doc-is-compact] \{\
-.    br
+.  if !\n[doc-is-compact] \
 .    sp \n[doc-display-vertical]u
-.  \}
 .
 .  if !\n[cR] \
 .    ne 2v
@@ -3000,10 +2998,8 @@
 .    if "\*[doc-list-type-stack\n[doc-list-depth]]"column-list" \{\
 .      doc-set-column-tab \n[doc-num-columns]
 '      in -\n[doc-column-indent-width]u
-.      if !\n[doc-compact-list-stack\n[doc-list-depth]] \{\
-.        br
+.      if !\n[doc-compact-list-stack\n[doc-list-depth]] \
 .        sp \n[doc-display-vertical]u
-.      \}
 .
 .      nf
 .      nr doc-num-columns 0
@@ -4015,10 +4011,8 @@
 .\" NS   doc-list-have-indent-stackXXX
 .
 .de doc-set-vertical-and-indent
-.  if !\n[doc-compact-list-stack\n[doc-list-depth]] \{\
-.    br
+.  if !\n[doc-compact-list-stack\n[doc-list-depth]] \
 .    sp \n[doc-display-vertical]u
-.  \}
 .
 .  if \n[doc-list-have-indent-stack\n[doc-list-depth]] \{\
 .    nr doc-list-have-indent-stack\n[doc-list-depth] 0