Dave
2020-03-24 08:11:42 UTC
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/
<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/