[bug #58035] clarify wording in doc/groff.texi

[Dave]

URL:
  <https://savannah.gnu.org/bugs/?58035>

                 Summary: clarify wording in doc/groff.texi
                 Project: GNU troff
            Submitted by: barx
            Submitted on: Tue 24 Mar 2020 03:11:40 AM CDT
                Category: Core
                Severity: 3 - Normal
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

doc/groff.texi has a couple of curious sentences that could be clarified with
small rewrites.

== .po ==

.po "does not cause a break, so changing the page offset in the middle of text
being filled may not yield the expected result."  This fails to say what the
actual result is, just that it "may not yield" some other result that is also
unspecified.

If the behavior is intentionally undefined, the documentation should
explicitly state this.  CSTR #54 (section 3) does not define this behavior, so
perhaps the behavior is by definition undefined (if one defines back
compatibility as complying with historical documentation rather than a
particular historical implementation).  If it is well defined but
nonintuitive, the details should be explained.

== .spreadwarn ==

The documentation states, "This request is active only if text is justified to
both margins (using '.ad b')."  The condition that .spreadwarn warns about
only occurs when spaces are stretched, and spaces are stretched only in fully
justified text.  Whether the request "is active" in other modes seems less
material than the fact that, even if active in _all_ modes (which I presume is
the actual case in the groff code), it can only ever be triggered in mode ".ad
b".

But rather than trying to reword this sentence, it might make more sense to
make the request's scope clear in its initial description; that is, where the
first sentence says "emit a warning if the additional space inserted for each
space between words in an output line", I would change the end of this to say
"...in an output line that is justified to both margins."  (I would ideally
prefer to phrase it more concisely, as "...in a fully justified output line,"
but the term "fully justified" is used nowhere else in the groff manual, so a
reader unfamiliar with the concept who sees this phrase here cannot learn more
by searching the manual.)




    _______________________________________________________

Reply to this item at:

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

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