gbranden pushed a commit to branch master
in repository groff.
commit 27730904f02cf71dd924dc9df62a9b4b47c1b75a
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Jan 16 12:54:29 2025 -0600
[NEWS,doc,man]: Fix Savannah #66673.
* NEWS: Add item noting incompatible change to `cf`, `hpf`, `hpfa`,
`mso`, `msoquiet`, `nx`, `open`, `opena`, `so`, `soquiet`, and `trf`
request syntax affecting users/documents that apply comment escape
sequences to them loosely.
* doc/groff.texi.in (Manipulating Hyphenation, Using Symbols, Strings)
(I/O):
* man/groff.7.man (Strings): Apply cautionary note (even with respect to
requests where behavior hasn't actually changed).
Fixes <https://savannah.gnu.org/bugs/?66673>. Thanks to Dave Kemper for
the report.
---
ChangeLog | 15 ++++++++++
NEWS | 25 +++++++++++++++++
doc/groff.texi.in | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
man/groff.7.man | 34 ++++++++++++++++++++---
4 files changed, 151 insertions(+), 6 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 8590714fd..81b786478 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2025-01-16 G. Branden Robinson <[email protected]>
+
+ * NEWS: Add item noting incompatible change to `cf`, `hpf`,
+ `hpfa`, `mso`, `msoquiet`, `nx`, `open`, `opena`, `so`,
+ `soquiet`, and `trf` request syntax affecting users/documents
+ that apply comment escape sequences to them loosely.
+
+ * doc/groff.texi.in (Manipulating Hyphenation, Using Symbols)
+ (Strings, I/O):
+ * man/groff.7.man (Strings): Apply cautionary note (even with
+ respect to requests where behavior hasn't actually changed).
+
+ Fixes <https://savannah.gnu.org/bugs/?66673>. Thanks to Dave
+ Kemper for the report.
+
2025-01-15 G. Branden Robinson <[email protected]>
Further rationalize header file inclusions.
diff --git a/NEWS b/NEWS
index 7cc72191f..feecd0f35 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,31 @@ not described. There are more details in the man and info
pages.
VERSION next
============
+Noteworthy incompatible changes
+-------------------------------
+* If your roff(7) documents follow any of the requests `cf`, `hpf`,
+ `hpfa`, `mso`, `msoquiet`, `nx`, `open`, `opena`, `so`, `soquiet`, or
+ `trf` with a comment after their file name argument, and did not place
+ that comment immediately after the end of the file name, you are
+ likely to get a diagnostic message.
+
+ warning: cannot open macro file 'e.tmac ': No such file or directory
+
+ That is because these requests are now able to process file names
+ containing space characters. (This change also makes the request
+ syntax consistent with that of `ds`, `as`, and others.) A quick fix
+ is to place the comment escape sequence as early as possible. For
+ example, we would change:
+
+ .mso e.tmac \" Load Eric Allman's package.
+
+ to:
+
+ .mso e.tmac\" Load Eric Allman's package.
+
+ to tell the formatter to load the "e.tmac" file rather than "e.tmac ".
+ See the items below for further details.
+
troff
-----
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index c886e6101..73b042317 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -9006,6 +9006,27 @@ hyphenation patterns with the new ones. Invoking
@code{hpf} or
@code{hpf} request is specified (either in the document, in a file
loaded at startup, or in a macro package), GNU @code{troff} won't
automatically hyphenate at all.
+
+@cindex trailing spaces in file name arguments
+@cindex comments, after file name arguments
+@cindex @code{hpf} request, and comments
+@cindex @code{hpfa} request, and comments
+@strong{Caution:@:}
+The
+@code{hpf}
+and
+@code{hpfa}
+requests interpret the remainder of the input line as the file name
+argument,
+including trailing spaces,
+up to a newline or comment escape sequence.
+Suffixing the file name with a comment,
+even an empty one,
+prevents unwanted space from creeping into it during source document
+maintenance.
+See the discussion of the
+@code{ds}
+request in @ref{Strings}.
@endDefreq
For automatic hyphenation to work, the formatter must know which letters
@@ -11410,6 +11431,12 @@ after the character can't be suppressed since the
neighboring character
on the right doesn't get examined.
@endDefreq
+@cindex trailing spaces in character definitions
+@cindex comments, after character definitions
+@cindex @code{char} request, and comments
+@cindex @code{fchar} request, and comments
+@cindex @code{fschar} request, and comments
+@cindex @code{schar} request, and comments
@DefreqList {char, c [@code{"}][@Var{contents}]}
@DefreqItemx {fchar, c [@code{"}][@Var{contents}]}
@DefreqItemx {fschar, f c [@code{"}][@Var{contents}]}
@@ -11501,6 +11528,15 @@ list of fonts declared as global special fonts with
the @code{special}
request, but before the already mounted special fonts.
@xref{Character Classes}.
+
+@strong{Caution:@:}
+These requests treats the remainder of the input line
+as their second argument,
+including trailing spaces,
+up to a newline or comment escape sequence.
+See the discussion of the
+@code{ds}
+request in @ref{Strings}.
@endDefreq
@DefreqList {rchar, c @dots{}}
@@ -12711,13 +12747,17 @@ Gray codes are explored in \*[cite Morgan 1998].
@c @endExample
@cindex trailing spaces in string definitions and appendments
-@cindex comments, with @code{ds}
+@cindex comments, with string definitions and appendments
+@cindex @code{as} request, and comments
+@cindex @code{as1} request, and comments
@cindex @code{ds} request, and comments
+@cindex @code{ds1} request, and comments
@strong{Caution:@:}
The
@code{ds}
request treats the remainder of the input line as its second argument,
-including trailing spaces.
+including trailing spaces,
+up to a newline or comment escape sequence.
Ending string definitions
(and appendments)
with a comment,
@@ -12842,6 +12882,9 @@ Strings can be queried (@code{length}) and modified
(@code{chop},
can be manipulated through renaming, removal, and aliasing (@code{rn},
@code{rm}, @code{als}).
+@cindex trailing spaces in string length measurement
+@cindex comments, with string length measurements
+@cindex @code{length} request, and comments
@Defreq {length, reg contents}
@cindex length of a string (@code{length})
@cindex string, length of (@code{length})
@@ -12861,6 +12904,16 @@ the end of the input line in copy mode.
\n[yyy]
@result{} 14
@endExample
+
+@strong{Caution:@:}
+The
+@code{length}
+request treats the remainder of the input line as its second argument,
+including trailing spaces,
+up to a newline or comment escape sequence.
+See the discussion of the
+@code{ds}
+request above.
@endDefreq
@Defreq {chop, object}
@@ -16373,6 +16426,32 @@ permits the reading of files and, when unsafe mode is
enabled at the
command line, the execution of an external commands, with or without
inclusion of their output in the document.
+@cindex trailing spaces in file name or system command arguments
+@cindex comments, after file name or system command arguments
+@cindex @code{cf} request, and comments
+@cindex @code{mso} request, and comments
+@cindex @code{msoquiet} request, and comments
+@cindex @code{nx} request, and comments
+@cindex @code{open} request, and comments
+@cindex @code{opena} request, and comments
+@cindex @code{pi} request, and comments
+@cindex @code{so} request, and comments
+@cindex @code{soquiet} request, and comments
+@cindex @code{sy} request, and comments
+@cindex @code{trf} request, and comments
+@strong{Caution:@:}
+The requests discussed below that accept a file name or system command
+as an argument treat the remainder of the input line as that argument,
+including trailing spaces,
+up to a newline or comment escape sequence.
+Suffixing the file name or command with a comment,
+even an empty one,
+prevents unwanted space from creeping into it during source document
+maintenance.
+See the discussion of the
+@code{ds}
+request in @ref{Strings}.
+
@DefreqList {so, [@code{"}]@Var{file}}
@DefreqListEndx {soquiet, [@code{"}]@Var{file}}
@cindex including a file (@code{so})
diff --git a/man/groff.7.man b/man/groff.7.man
index 5c50e4f7e..3533ee394 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -6241,10 +6241,10 @@ string is later interpolated.
.
.P
.I Caution:
-The
-.B ds
-request treats the remainder of the input line as its second argument,
-including trailing spaces.
+These requests treat the remainder of the input line
+as their second argument,
+including trailing spaces,
+up to a newline or comment escape sequence.
.
Ending string definitions
(and appendments)
@@ -6253,6 +6253,32 @@ even an empty one,
prevents unwanted space from creeping into them during source document
maintenance.
.
+This rule and suggestion also applies to the second argument of the
+.RB \[lq] length \[rq]
+request,
+to requests that define characters
+.RB ( char ,
+.BR fchar ,
+.BR fschar ,
+and
+.BR schar ),
+and to the file name or command arguments of the
+.BR cf ,
+.BR hpf ,
+.BR hpfa ,
+.BR mso ,
+.BR msoquiet ,
+.BR nx ,
+.RB \[lq] open \[rq],
+.BR opena ,
+.BR pi ,
+.BR pso ,
+.RB \[lq] so \[rq],
+.BR soquiet ,
+and
+.B trf
+requests.
+.
.
.br
.ne 3v
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
