gbranden pushed a commit to branch master
in repository groff.
commit 645537cbffa7d973fed0d4a9f4fa734684b49977
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Dec 6 06:24:37 2025 -0600
[doc,man]: Update, resync `shift` req description.
* Document applicability to parameterized string interpolations.
* Favor active voice over passive.
---
doc/groff.texi.in | 25 +++++++++++++++++++------
man/groff.7.man | 23 +++++++++++++++++------
man/groff_diff.7.man | 22 ++++++++++++++--------
3 files changed, 50 insertions(+), 20 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 84b459585..91e225236 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -15365,12 +15365,25 @@ number of parameters.
@endDefesc
@Defreq {shift, [@Var{n}]}
-Shift the parameters @var{n} places (1@tie{}by default). This is a
-``left shift'': what was parameter@tie{}@var{i} becomes parameter
-@math{@var{i}-@var{n}}. The parameters formerly in positions 1
-to@tie{}@var{n} are no longer available. Shifting by a non-positive
-amount performs no operation. The register @code{.$} is adjusted
-accordingly.
+@c XXX: useless request warning if not interpreting a macro or string?
+Shift macro or string parameters
+@var{n}
+places
+(by@tie{}1 if
+@var{n}
+omitted):
+argument@tie{}@var{i}
+becomes argument
+@var{i}-@var{n};
+arguments 1
+to@tie{}@var{n}
+become unavailable.
+Shifting by a non-positive amount,
+or outside of a macro or string definition,
+performs no operation.
+The register
+@code{.$}
+adjusts its value accordingly.
@endDefreq
@c END Keep (roughly) parallel with subsection "Parameters" of
@c groff(7).
diff --git a/man/groff.7.man b/man/groff.7.man
index bcf3fe2cb..7ef291ce4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4806,15 +4806,26 @@ Set the soft hyphen character
.
.TPx
.REQ .shift
-In a macro definition,
-left-shift arguments by one position.
+Shift macro or string parameters one place
+.I n
+places:
+.RI argument\~ i
+becomes argument
+.IR i \|\-\| 1 ;
+argument 1
+becomes unavailable.
.
.TPx
.REQ .shift n
-In a macro definition,
-left-shift arguments by
-.IR n \~\c
-positions.
+Shift macro or string parameters
+.I n
+places:
+.RI argument\~ i
+becomes argument
+.IR i \|\-\| n ;
+arguments 1
+.RI to\~ n
+become unavailable.
.
.TPx
.REQ .sizes "s1 s2 \f[R].\|.\|.\&\f[] sn \f[R][\f[B]0\f[]]"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a9c32c034..a83fdd05c 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4166,22 +4166,28 @@ are considered when assigning the soft hyphen character.
.
.TP
.BR .shift\~ [\c
-.\" XXX: useless request warning if not interpreting a macro?
.IR n ]
-In a macro definition,
-shift arguments by
+.\" XXX: useless request warning if not interpreting a macro or string?
+Shift macro or string parameters
+.I n
+places
+(by\~1 if
.I n
-positions:
+omitted):
.RI argument\~ i
becomes argument
.IR i \|\-\| n ;
arguments 1
.RI to\~ n
-are no longer available.
+become unavailable.
.
-.RI If\~ n
-is missing,
-arguments are shifted by\~1.
+Shifting by a non-positive amount,
+or outside of a macro or string definition,
+performs no operation.
+.
+The register
+.B .$
+adjusts its value accordingly.
.
.
.TP
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
