[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 03/40: doc/groff.texi: Update "Built-in Registers".
From: |
G. Branden Robinson |
Subject: |
[groff] 03/40: doc/groff.texi: Update "Built-in Registers". |
Date: |
Mon, 12 Dec 2022 19:28:03 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit 7b136a482f9471189bf0c2ab4168342c4ba7f13b
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Dec 9 08:16:10 2022 -0600
doc/groff.texi: Update "Built-in Registers".
Recast introduction and sync with register descriptions in groff(7).
---
doc/groff.texi | 104 +++++++++++++++++++++++++++++----------------------------
1 file changed, 53 insertions(+), 51 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index a5a6cf35c..a40255b1f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -468,7 +468,7 @@ developing GNU and promoting software freedom.''
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle Edition 1.23.0
-@subtitle November 2022
+@subtitle December 2022
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -7657,26 +7657,38 @@ desirable to test the page number independently of its
format.
@cindex built-in registers
@cindex registers, built-in
-The following lists some built-in registers that are not described
-elsewhere in this manual. Any register name that begins with a @samp{.}
-is read-only. A complete listing of all built-in registers can be found
-in @ref{Register Index}.
+Predefined registers whose identifiers start with a dot are read-only.
+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.
+
+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}.
+
+We present here a few built-in registers that are not described
+elsewhere in this manual; they have to do with invariant properties of
+GNU @code{troff}, or obtain information about the formatter's
+command-line options or the operating environment. Date- and
+time-related registers are set to the local time as determined by
+@cite{ctime@r{(5)}} when the formatter launches. This initialization
+can be overridden by @env{SOURCE_DATE_EPOCH} and @env{TZ}; see
+@ref{Environment}.
@table @code
@item \n[.F]
@cindex current input file name register (@code{.F})
@cindex input file name, current, register (@code{.F})
@vindex .F
-This read-only string-valued register stores the name of the file being
-formatted.
+Name of input file (string-valued).
@item \n[.R]
@cindex number of registers register (@code{.R})
@cindex registers, number of, register (@code{.R})
@vindex .R
-The count of available unused registers. This is always 10000 in GNU
-@code{troff};@footnote{GNU @code{troff} dynamically allocates memory for
-as many registers as required.} it exists for backward compatibility.
+Count of available unused registers; always 10,000 in GNU
+@code{troff}.@footnote{GNU @code{troff} dynamically allocates memory for
+as many registers as required.}
@item \n[.U]
@cindex safer mode
@@ -7684,67 +7696,62 @@ as many registers as required.} it exists for backward
compatibility.
@cindex unsafe mode
@cindex mode, unsafe
@vindex .U
-1 if GNU @code{troff} is called with the @option{-U} command-line option
-to activate unsafe mode, and zero otherwise. @xref{Groff Options}.
+Unsafe mode enablement (Boolean-valued); see @command{groff}
+@option{-U} option (@ref{Groff Options}).
@item \n[seconds]
@cindex seconds, current time (@code{seconds})
@cindex time, current, seconds (@code{seconds})
@cindex current time, seconds (@code{seconds})
@vindex seconds
-The number of seconds after the minute, normally in the range@tie{}0
-to@tie{}59, but can be up to@tie{}61 to allow for leap seconds.
-Initialized at startup of GNU @code{troff}.
+Count of seconds elapsed in the minute (0--60). @c not 59; see POSIX
@item \n[minutes]
@cindex minutes, current time (@code{minutes})
@cindex time, current, minutes (@code{minutes})
@cindex current time, minutes (@code{minutes})
@vindex minutes
-The number of minutes after the hour, in the range@tie{}0 to@tie{}59.
-Initialized at startup of GNU @code{troff}.
+Count of minutes elapsed in the hour (0--59).
@item \n[hours]
@cindex hours, current time (@code{hours})
@cindex time, current, hours (@code{hours})
@cindex current time, hours (@code{hours})
@vindex hours
-The number of hours past midnight, in the range@tie{}0 to@tie{}23.
-Initialized at startup of GNU @code{troff}.
+Count of hours elapsed since midnight (0--23).
@item \n[dw]
@cindex day of the week register (@code{dw})
@cindex date, day of the week register (@code{dw})
@vindex dw
-Day of the week (1--7). Initialized at startup of GNU @code{troff}.
+Day of the week (1--7; 1 is Sunday).
@item \n[dy]
@cindex day of the month register (@code{dy})
@cindex date, day of the month register (@code{dy})
@vindex dy
-Day of the month (1--31). Initialized at startup of GNU @code{troff}.
+Day of the month (1--31).
@item \n[mo]
@cindex month of the year register (@code{mo})
@cindex date, month of the year register (@code{mo})
@vindex mo
-Current month (1--12). Initialized at startup of GNU @code{troff}.
+Month of the year (1--12).
@item \n[year]
@cindex date, year register (@code{year}, @code{yr})
@cindex year, current, register (@code{year}, @code{yr})
@vindex year
-The current year. Initialized at startup of GNU @code{troff}.
+Gregorian year.
@cindex CSTR@tie{}#54 errata
@cindex CSTR@tie{}#54 erratum, @code{yr} register
@item \n[yr]
@vindex yr
-The current year minus@tie{}1900. Initialized at startup of GNU
-@code{troff}. This register is incorrectly documented in the
-@acronym{AT&T} @code{troff} manual as storing the last two digits of the
-current year. That claim stopped being true in 2000. Old @code{troff}
-input that looks like:
+Gregorian year minus@tie{}1900. This register is incorrectly documented
+in the @acronym{AT&T} @code{troff} manual as storing the last two digits
+of the current year. That claim stopped being true in 2000. Old
+@code{troff} input that looks like:
@Example
'\" The year number is a surprise after 1999.
@@ -7773,7 +7780,7 @@ This document was formatted in \n(y4.
@vindex c.
@cindex input line number register (@code{.c}, @code{c.})
@cindex line number, input, register (@code{.c}, @code{c.})
-The current @emph{input} line number. @samp{c.} is a writable synonym,
+Input line number. @samp{c.} is a writable synonym,
@c introduced in AT&T device-independent troff (CSTR #54, 1981-01)
affecting subsequent interpolations of both @samp{.c} and @samp{c.}.
@@ -7781,14 +7788,14 @@ affecting subsequent interpolations of both @samp{.c}
and @samp{c.}.
@vindex ln
@cindex output line number register (@code{ln})
@cindex line number, output, register (@code{ln})
-The current @emph{output} line number after a call to the @code{nm}
-request to activate line numbering. @xref{Miscellaneous}.
+Output line number associated with the @code{nm} request to activate
+line numbering. @xref{Miscellaneous}.
@item \n[.x]
@vindex .x
@cindex major version number register (@code{.x})
@cindex version number, major, register (@code{.x})
-The major version number of the running GNU @code{troff} formatter. For
+Major version number of the running GNU @code{troff} formatter. For
example, if the version number is 1.23.0, then @code{.x}
contains@tie{}@samp{1}.
@@ -7796,16 +7803,15 @@ contains@tie{}@samp{1}.
@vindex .y
@cindex minor version number register (@code{.y})
@cindex version number, minor, register (@code{.y})
-The minor version number of the running GNU @code{troff} formatter. For
+Minor version number of the running GNU @code{troff} formatter. For
example, if the version number is 1.23.0, then @code{.y}
contains@tie{}@samp{23}.
@item \n[.Y]
@vindex .Y
@cindex revision number register (@code{.Y})
-The revision number of the running GNU @code{troff} formatter. For
-example, if the version number is 1.23.0, then @code{.Y}
-contains@tie{}@samp{0}.
+Revision number of the running GNU @code{troff} formatter. For example,
+if the version number is 1.23.0, then @code{.Y} contains@tie{}@samp{0}.
@item \n[$$]
@vindex $$
@@ -7813,41 +7819,37 @@ contains@tie{}@samp{0}.
@cindex PID of GNU @code{troff} register (@code{$$})
@cindex GNU @code{troff}, process ID register (@code{$$})
@cindex GNU @code{troff}, PID register (@code{$$})
-The process identifier (PID) of the GNU @code{troff} program in its
+Process identifier (PID) of the GNU @code{troff} program in its
operating environment.
@item \n[.g]
@vindex .g
@cindex GNU @code{troff}, identification register (@code{.g})
@cindex GNU-specific register (@code{.g})
-Always@tie{}1. Macros should use this to determine whether they are
-running under GNU @code{troff}.
+Always true in GNU @code{troff} (Boolean-valued). Documents can use
+this to ask the formatter if it claims @code{groff} compatibility.
@item \n[.A]
@vindex .A
@cindex approximation output register (@code{.A})
@cindex plain text approximation output register (@code{.A})
-1 if GNU @code{troff} is called with the @option{-a} command-line option
-to produce a plain text approximation of the output, and zero otherwise.
-@xref{Groff Options}.
+Approximate output is being formatted (Boolean-valued); see
+@command{groff} @option{-a} option (@ref{Groff Options}).
@item \n[.O]
@vindex .O
-The suppression nesting level applied by @code{\O} escape sequences.
-@xref{Suppressing Output}.
+Output suppression nesting level applied by @code{\O} escape sequences;
+see @ref{Suppressing Output}.
@item \n[.P]
@vindex .P
-1 if the current page is selected for printing and zero if it is not.
-GNU @code{troff} can be called with the @option{-o} command-line option
-to format a subset of a document by page number(s). @xref{Groff
-Options}.
+Output page selection status (Boolean-valued); see @command{groff}
+@option{-o} option (@ref{Groff Options}).
@item \n[.T]
@vindex .T
-1 if GNU @code{troff} is called with the @option{-T} command-line option
-to specify the typesetter device, and zero otherwise. @xref{Groff
-Options}.
+Indicator of output device selection (Boolean-valued); see
+@command{groff} @option{-T} option (@ref{Groff Options}).
@end table
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 03/40: doc/groff.texi: Update "Built-in Registers".,
G. Branden Robinson <=