gbranden pushed a commit to branch master
in repository groff.
commit d48e961ee406d2cc4b3e013d4bb4a325e993ca52
Author: G. Branden Robinson <[email protected]>
AuthorDate: Wed Jan 1 21:58:38 2025 -0600
[doc,man]: Revise `aln`, `als` presentation.
---
doc/groff.texi.in | 81 ++++++++++++++++++++++++++++++++++++++--------------
man/groff.7.man | 18 ++++++------
man/groff_diff.7.man | 70 ++++++++++++++++++++++-----------------------
3 files changed, 104 insertions(+), 65 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 0b9ae03c7..5aeed2ab3 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -7692,21 +7692,36 @@ exist, the request is ignored. Renaming a built-in
register does not
otherwise alter its properties.
@endDefreq
-@Defreq {aln, new old}
+@Defreq {aln, new-register old-register}
@cindex alias, register, creating (@code{aln})
@cindex creating alias of register (@code{aln})
@cindex register, creating alias of (@code{aln})
-Create an alias @var{new} for an existing register @var{old}, causing
-the names to refer to the same stored object. If @var{old} is
-undefined, a warning in category @samp{reg} is produced and the request
-is ignored. @xref{Warnings}, regarding the enablement and suppression
-of warnings.
+Create alias
+(additional name)
+@var{new-register}
+of
+@var{existing-register},
+causing the names to refer to the same stored object.
+If
+@var{existing-register}
+is undefined,
+GNU
+@command{troff}
+produces a warning in category
+@samp{reg}
+and ignores the request.
+@xref{Warnings},
+regarding the enablement and suppression of warnings.
@cindex alias, register, removing (@code{rr})
@cindex removing alias of register (@code{rr})
@cindex register, removing alias of (@code{rr})
-To remove a register alias, invoke @code{rr} on its name. A register's
-contents do not become inaccessible until it has no more names.
+To remove a register alias,
+invoke
+@code{rr}
+on its name.
+A register's contents do not become inaccessible until it has no more
+names.
@endDefreq
@c END Keep (roughly) parallel with section "Registers" of groff(7).
@@ -12928,7 +12943,7 @@ This request is incorrectly documented in the
@acronym{AT&T}
@endDefreq
@anchor{als}
-@Defreq {als, new old}
+@Defreq {als, new-name existing-name}
@cindex alias, string, creating (@code{als})
@cindex alias, macro, creating (@code{als})
@cindex alias, diversion, creating (@code{als})
@@ -12938,12 +12953,29 @@ This request is incorrectly documented in the
@acronym{AT&T}
@cindex string, creating alias of (@code{als})
@cindex macro, creating alias of (@code{als})
@cindex diversion, creating alias of (@code{als})
-Create an alias @var{new} for the existing request, string, macro, or
-diversion object named @var{old}, causing the names to refer to the same
-stored object. If @var{new} already exists, its contents are lost
-unless already aliased. If @var{old} is undefined, a warning in
-category @samp{mac} is produced, and the request is ignored.
-@xref{Warnings}, regarding the enablement and suppression of warnings.
+Create alias
+(additional name)
+@var{new-name}
+of request,
+string,
+macro,
+or diversion
+@var{existing-name},
+causing the names to refer to the same stored object.
+If
+@var{new-name}
+already exists,
+its contents are lost unless already aliased.
+If
+@var{existing-name}
+is undefined,
+GNU
+@command{troff}
+produces a warning in category
+@samp{mac}
+and ignores the request.
+@xref{Warnings},
+regarding the enablement and suppression of warnings.
To understand how the @code{als} request works, consider two different
storage pools:@: one for objects (macros, strings, etc.), and another
@@ -12987,12 +13019,19 @@ an error. @xref{Writing Macros}.
@cindex string, removing alias of (@code{rm})
@cindex macro, removing alias of (@code{rm})
@cindex diversion, removing alias of (@code{rm})
-To remove an alias, call @code{rm} on its name. The object itself is
-not destroyed until it has no more names.
-
-Redefinitions and appendments ``write through'' request, macro, string,
-and diversion names. To replace an aliased object with a separately
-defined one, you must use the @code{rm} request on its name first.
+To remove an alias,
+call
+@code{rm}
+on its name.
+The object itself is not destroyed until it has no more names.
+
+When a request,
+macro,
+string,
+or diversion is aliased
+redefinitions and appendments ``write through'' alias names.
+To replace an alias with a separately defined object,
+remove its name first.
@endDefreq
@c END Keep (roughly) parallel with section "Strings" of groff(7).
diff --git a/man/groff.7.man b/man/groff.7.man
index 0fcee10cd..8c05f2a2e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2495,26 +2495,26 @@ The default is
.BR 0 .
.
.TPx
-.REQ .aln "new old"
+.REQ .aln "new-register existing-register"
Create alias
(additional name)
-.I new
-for existing register named
-.IR old .
+.I new-register
+of
+.IR existing-register .
.
.TPx
-.REQ .als "new old"
+.REQ .als "new-name existing-name"
Create alias
(additional name)
-.I new
-for existing request,
+.I new-name
+of request,
string,
macro,
or diversion
-.IR old .
+.IR existing-name .
.
If
-.I new
+.I new-name
already exists,
its contents are lost unless already aliased.
.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index f38204de0..e26b19035 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1544,19 +1544,25 @@ permitting inclusion of leading spaces.
.
.
.TP 8n \" ".break" + 2n
-.BI .aln\~ "new old"
+.BI .aln\~ "new-register existing-register"
Create alias
-.I new
-for existing register named
-.IR old ,
-causing the names to refer to the same stored value.
+(additional name)
+.I new-register
+of
+.IR existing-register .
.
If
-.I old
+.I existing-register
is undefined,
-a warning in category
-.B reg
-is generated and the request is ignored.
+GNU
+.I troff \" GNU
+produces a warning in category
+.RB \[lq] reg \[rq]
+and ignores the request.
+.
+See section \[lq]Warnings\[rq] of
+.MR @g@groff 1 ,
+regarding the enablement and suppression of warnings.
.
To remove a register alias,
invoke
@@ -1568,40 +1574,34 @@ names.
.
.
.TP
-.BI .als\~ "new old"
+.BI .als\~ "new-name existing-name"
Create alias
-.I new
-for existing request,
+(additional name)
+.I new-name
+of request,
string,
macro,
-or diversion named
-.IR old ,
+or diversion
+.IR existing-name ,
causing the names to refer to the same stored object.
.
If
-.I old
+.I new-name
+already exists,
+its contents are lost unless already aliased.
+.
+If
+.I existing-name
is undefined,
-a warning in category
-.B mac
-is produced,
-and the request is ignored.
+GNU
+.I troff \" GNU
+produces a warning in category
+.RB \[lq] mac \[rq]
+and ignores the request.
.
-The
-.RB \[lq] am \[rq],
-.RB \[lq] as \[rq],
-.BR da ,
-.BR de ,
-.BR di ,
-and
-.B ds
-requests
-(together with their variants)
-create a new object only if the name of the macro,
-diversion,
-or string is currently undefined
-or if it is defined as a request;
-normally,
-they modify the value of an existing object.
+See section \[lq]Warnings\[rq] of
+.MR @g@groff 1 ,
+regarding the enablement and suppression of warnings.
.
To remove an alias,
invoke
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
