[bug #64440] [docs] minor corrections and updates

[G. Branden Robinson]

Update of bug #64440 (project groff):

                  Status:             In Progress => Need Info              
             Assigned to:                gbranden => barx                   

    _______________________________________________________

Follow-up Comment #2:

[comment #0 original submission:]
> 0 A sentence in the .sp section reads: "If invoked with the no-break control
character, @code{sp} moves the pending output line's text baseline by
@var{distance}."
> 
> This is accurate, but might it be ambiguous?  When I read it, my
interpretation was that it moved the baseline from the point in the pending
line at which the 'sp was invoked (a la the \v escape) rather than moving the
baseline of the entire line.
> 
> Maybe that's just me.  But if others agree that's a valid reading of that
sentence, it should be clarified (maybe by inserting "entire" before
"pending"?).
> 
> The way Branden explained it on the email list a few months ago
(http://lists.gnu.org/r/groff/2023-05/msg00031.html) also seems unambiguous:
"the position of the text baseline is one of those properties of the output
line that is not determined until the line has been broken.  And what the `sp`
request really does is decide where your next text baseline is going to be."

I think I already tackled this one, or tried to.


commit 2d613077eba413f444f0c2a5d9f607164db69182
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat May 6 19:05:30 2023 -0500

    doc/groff.texi: Revise vertical spacing material.
    
    * Document text baseline location as a property of the output line.
    * Recast description of `sp` request entirely, describing more aspects
      of its behavior.  Add forward cross references to implicated topics.
      Drop some material about trap interaction spread amid examples since we
now handle that
      both earlier, in the initial presentation, and later, via cross
      references to the presentation of vertical position traps.
[...]
diff --git a/doc/groff.texi b/doc/groff.texi
index 9f87fda54..0ec47245c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -7926,16 +7926,19 @@ @node Manipulating Filling and Adjustment
 @noindent
 @cindex pending output line
 @cindex partially collected line
-Output line properties like page offset, indentation, and adjustment are
-not determined until the line has been broken.  An output line is said
-to be @dfn{pending} if some input has been collected but an output line
-corresponding to it has not yet been written; such an output line is
-also termed @dfn{partially collected}.  If no output line is pending, it
-is as if a break has already happened; additional breaks, whether
-explicit or implicit, have no effect.  If the vertical drawing
-position is negative---as it is when the formatter starts up---a break
-starts a new page (even if no output line is pending) unless an
-end-of-input macro is being interpreted.  @xref{End-of-input Traps}.
+@cindex output line properties
+@cindex properties of output lines
+Output line properties like page offset, indentation, adjustment, and
+even the location of its text baseline, are not determined until the
+line has been broken.  An output line is said to be @dfn{pending} if
+some input has been collected but an output line corresponding to it has
+not yet been written; such an output line is also termed @dfn{partially
+collected}.  If no output line is pending, it is as if a break has
+already happened; additional breaks, whether explicit or implicit, have
+no effect.  If the vertical drawing position is negative---as it is when
+the formatter starts up---a break starts a new page (even if no output
+line is pending) unless an end-of-input macro is being interpreted.
+@xref{End-of-input Traps}.
 
 @Defreq {br, }
 Break the line: emit any pending output line without adjustment.
[...]
@@ -8814,16 +8814,22 @@ @node Manipulating Spacing
 @cindex spacing, manipulating
 
 @Defreq {sp, [@Var{distance}]}
-Space downward by @var{distance}.  Inside a diversion, any
-@var{distance} argument is ignored.  Otherwise, a negative argument
-moves the drawing position up the page.  This request causes a break.
-The default scaling unit is @samp{v}.  If @var{distance} is not
-specified, @samp{1v} is assumed.
+Break the line and place the next text baseline @var{distance} lower
+than it would otherwise be, or until springing a page location
+trap.@footnote{@xref{Page Location Traps}.}  If invoked with the
+no-break control character, @code{sp} moves the pending output line's
+text baseline by @var{distance}.  If @var{distance} would move the
+text baseline below the bottom of the page, the page is broken and
+any leftover distance discarded.  A negative distance moves the text
+baseline up the page, but will not reduce it below zero.  Inside a
+diversion, any @var{distance} argument is ignored.  The default scaling
+unit is @samp{v}.  If @var{distance} is not specified, @samp{1v} is
+assumed.


Does this clarify the point?  Tossing to you for feedback.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64440>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/