From 3bb570f656aec960df2d19b9e2be9e96abadc1af Mon Sep 17 00:00:00 2001 From: "G. Branden Robinson" Date: Thu, 4 May 2023 18:18:08 -0500 Subject: doc/groff.texi: Clarify register removal/renaming. * Explicitly state that register renaming doesn't affect read-only state or other special properties. * Add cautionary note above removing built-in registers. * Document difference from AT&T troff, which ignored attempts to remove read-only (but not writable built-in) registers. * Consistently use Texinfo @: command after prose colons. --- doc/groff.texi | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/doc/groff.texi b/doc/groff.texi index 9f410b4b7..dd447badd 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -7424,7 +7424,8 @@ any. @cindex renaming a register (@code{rnn}) @cindex register, renaming (@code{rnn}) Rename register @var{ident1} to @var{ident2}. If @var{ident1} doesn't -exist, the request is ignored. +exist, the request is ignored. Renaming a built-in register does not +otherwise alter its properties. @endDefreq @Defreq {aln, new old} @@ -7683,6 +7684,13 @@ Many are Boolean-valued, interpolating a true or false value testable with the @code{if}, @code{ie}, or @code{while} requests. Some read-only registers are string-valued, meaning that they interpolate text. +@cindex removing a built-in register +@cindex register, built-in, removing +@cindex built-in register, removing +@strong{Caution:@:} Built-in registers are subject to removal like +others; once removed, they can be recreated only as normal writable +registers and will not reflect formatter state. + A register name (without the dot) is often associated with a request of the same name. A complete listing of all built-in registers can be found in @ref{Register Index}. @@ -12183,7 +12191,7 @@ Gray codes are explored in \*[cite Morgan 1998]. @cindex trailing spaces in string definitions and appendments @cindex comments, with @code{ds} @cindex @code{ds} request, and comments -@strong{Caution:} Unlike other requests, the second argument to the +@strong{Caution:@:} Unlike other requests, the second argument to the @code{ds} request consumes the remainder of the input line, including trailing spaces. This means that comments on a line with such a request can introduce unwanted space into a string when they are set off from @@ -17155,6 +17163,13 @@ string is a common feature of post-CSTR@tie{}#54 Plan@tie{}9 @code{troff} all support it.} but valid values are specific to each implementation. +@cindex removal of read-only registers, incompatibility with @acronym{AT&T} @code{troff} +@cindex register, read-only, removal, incompatibility with @acronym{AT&T} @code{troff} +@cindex read-only register removal, incompatibility with @acronym{AT&T} @code{troff} +@acronym{AT&T} @code{troff} ignored attempts to remove read-only +registers; GNU @code{troff} honors such requests. @xref{Built-in +Registers}. + @cindex output device usage register (@code{.T}), incompatibility with @acronym{AT&T} @code{troff} The (read-only) register @code{.T} interpolates@tie{}1 if GNU @code{troff} is called with the @option{-T} command-line option, and -- cgit v1.2.1