[Groff-commit] groff ChangeLog doc/groff.texinfo

[Werner LEMBERG]

CVSROOT:        /cvsroot/groff
Module name:    groff
Changes by:     Werner LEMBERG <wl>     08/10/04 10:33:04

Modified files:
        .              : ChangeLog 
        doc            : groff.texinfo 

Log message:
        * doc/groff.texinfo: Improve documentation of `.als'.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/ChangeLog?cvsroot=groff&r1=1.1150&r2=1.1151
http://cvs.savannah.gnu.org/viewcvs/groff/doc/groff.texinfo?cvsroot=groff&r1=1.271&r2=1.272

Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/ChangeLog,v
retrieving revision 1.1150
retrieving revision 1.1151
diff -u -b -r1.1150 -r1.1151
--- ChangeLog   4 Oct 2008 06:23:07 -0000       1.1150
+++ ChangeLog   4 Oct 2008 10:33:03 -0000       1.1151
@@ -7,6 +7,8 @@
        * tmac/www.tmac (TS, TE, EQ, EN): Don't use .als for setting up
        default macros.  This causes endless loops (at least for TE).
 
+       * doc/groff.texinfo: Improve documentation of `.als'.
+
 2008-10-03  Werner LEMBERG  <address@hidden>
 
        * src/devices/grops/grops.man, src/roff/troff/troff.man,

Index: doc/groff.texinfo
===================================================================
RCS file: /cvsroot/groff/groff/doc/groff.texinfo,v
retrieving revision 1.271
retrieving revision 1.272
diff -u -b -r1.271 -r1.272
--- doc/groff.texinfo   28 Sep 2008 14:39:44 -0000      1.271
+++ doc/groff.texinfo   4 Oct 2008 10:33:04 -0000       1.272
@@ -10324,7 +10324,7 @@
 previously-defined string variable.  To be more precise, the stored
 string is pushed onto the input stack which is then parsed by
 @code{gtroff}.  Similar to number registers, it is possible to nest
-strings, i.e. string variables can be called within string variables.
+strings, i.e., string variables can be called within string variables.
 
 If the string named by the @code{\*} escape does not exist, it is
 defined as empty, and a warning of type @samp{mac} is emitted (see
@@ -10607,6 +10607,49 @@
 exactly equivalent (it is similar to a hard rather than a soft link). If
 @var{old} is undefined, @code{gtroff} generates a warning of type
 @samp{mac} and ignores the request.
+
+To understand how the @code{als} request works it is probably best to
+think of two different pools: one pool for objects (macros, strings,
+etc.), and another one for names.  As soon as an object is defined,
address@hidden adds it to the object pool, adds its name to the name
+pool, and creates a link between them.  When @code{als} creates an
+alias, it adds a new name to the name pool which gets linked to the same
+object as the old name.
+
+Now consider this example.
+
address@hidden
+.de foo
+..
+.
+.als bar foo
+.
+.de bar
+.  foo
+..
+.
+.bar
+    @result{} input stack limit exceeded
address@hidden
+
address@hidden
+The definition of macro @code{bar} replaces the old object this name is
+linked to.  However, the alias to @code{foo} is still active!  With
+other words, @code{foo} is still linked to the same object as
address@hidden, and the result of calling @code{bar} is an infinite,
+recursive loop which finally leads to an error.
+
address@hidden alias, string, removing (@code{rm})
address@hidden alias, macro, removing (@code{rm})
address@hidden alias, diversion, removing (@code{rm})
address@hidden removing alias, for string (@code{rm})
address@hidden removing alias, for macro (@code{rm})
address@hidden removing alias, for diversion (@code{rm})
address@hidden string, removing alias (@code{rm})
address@hidden macro, removing alias (@code{rm})
address@hidden diversion, removing alias (@code{rm})
+To undo an alias, simply call @code{rm} on the aliased name.  The object
+itself is not destroyed until there are no more aliases.
 @endDefreq
 
 @Defreq {chop, xx}
@@ -11127,7 +11170,8 @@
 @code{am1}.
 @endDefreq
 
address@hidden, for the @code{als} request to rename a macro.
address@hidden, for the @code{als} and @code{rn} request to create an
+alias and rename a macro, respectively.
 
 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and @code{as}
 requests (together with its variants) only create a new object if the