Index: incr-gengtype-gcc/gcc/doc/gty.texi
===================================================================
--- incr-gengtype-gcc/gcc/doc/gty.texi	(revision 163987)
+++ incr-gengtype-gcc/gcc/doc/gty.texi	(working copy)
@@ -69,6 +69,7 @@ These don't need to be marked.
 * GTY Options::         What goes inside a @code{GTY(())}.
 * GGC Roots::           Making global variables GGC roots.
 * Files::               How the generated files work.
+* Generating GGC code with gengtype::               How to run the gengtype generator.
 * Invoking the garbage collector::   How to invoke the garbage collector.
 @end menu
 
@@ -183,6 +184,7 @@ The value of the expression given by @code{desc} i
 each @code{tag} value, each of which should be different.  If no
 @code{tag} is matched, the field marked with @code{default} is used if
 there is one, otherwise no field in the union will be marked.
+A union field can have at most one @code{tag}.
 
 In the @code{desc} option, the ``current structure'' is the union that
 it discriminates.  Use @code{%1} to mean the structure containing it.
@@ -312,6 +314,12 @@ and the @var{from expression} returns the original
 the pointer.  The pointer will be available using the @code{%h}
 escape.
 
+@findex ptr_alias
+@item ptr_alias (@var{type})
+
+When applied to a type, @code{ptr_alias} indicates that the GTY-ed
+type is an alias or synonym of the given @var{type}.
+
 @findex chain_next
 @findex chain_prev
 @findex chain_circular
@@ -472,12 +480,55 @@ somewhere.  It will be called @file{gtype-@var{lan
 @var{lang} is the name of the subdirectory the language is contained in.
 
 Plugins can add additional root tables.  Run the @code{gengtype}
-utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
-@var{file-list} @var{plugin*.c}} with your plugin files
-@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
-The GCC build tree is needed to be present in that mode.
+utility in plugin mode as @code{gengtype -P @var{gt-pluginout.h} -r
+@var{gtype.state} @var{plugin*.c}} with your plugin files
+@var{plugin*.c} using @code{GTY} to generate the @var{gt-pluginout.h}
+file. The @var{gtype.state} is usually in the plugin directory.
 
 
+@node Generating GGC code with gengtype
+@section How to run the gengtype generator.
+@cindex garbage collector, generation, gengtype
+@findex gengtype
+
+The @code{gengtype} utility (which may be installed as
+@code{gcc-gengtype} or some other name on your system) is a C code
+generator program.  It generates suitable marking and type-walking C
+routines for GGC.  Generated GC marking routines ensure that every
+live data is ultimately marked, so that GGC can delete, at the end of
+its @code{ggc_collect} function, every non-marked data (which is
+unreachable and dead).  Generated PCH type-walking routines are used
+for ``compilation'' of header files @var{*.h} into a @var{*.gch}
+file.  The @code{gengtype} utility is used when building GCC itself
+from its source tree, and also for plugins dealing with their own
+GTY-ed data.
+
+The @code{gengtype} utility is run once specially when compiling GCC
+itself.  It parses many GCC source files (mostly internal GCC headers
+declaring @code{GTY}-ed types and internal GCC files declaring
+@code{GTY}-ed variables). It saves its state in a persistent textual
+file @file{gtype.state}.  This file has a format tied to a particular
+GCC release and configuration.  This @file{gtype.state} file should be
+parsed only by @code{gengtype} (of the same version which has
+generated it).  Following GNU usage, @code{gengtype} accepts the usual
+@code{--version} or @code{-V} and @code{--help} arguments.  It also
+accepts @code{--verbose} or @code{-v} to show what it is doing, and
+@code{--debug} or @code{-D} for debugging purposes. It may dump its
+state in human readable form with @code{--dump} or @code{-d}.
+
+During GCC build process, a file @file{gtyp-input.list} is built and
+contains a long list of files to be parsed.  Then, @code{gengtype} is
+run once to generate its state with @code{gengtype -S
+@file{source-directory} -I @file{gtyp-input.list} -w
+@file{gtype.state}}. Immediately after, it is re-run to read its just
+generated state and generate @file{gt*.[ch]} files with @code{gengtype
+-r @file{gtype.state}}. 
+
+Plugin developers using @code{GTY} in their plugin source code should
+run @code{gengtype -P @var{gt-pluginout.h} -r @file{gtype.state}
+@var{plugin*.c}}
+
+
 @node Invoking the garbage collector
 @section How to invoke the garbage collector
 @cindex garbage collector, invocation