gty.texi (GGC Roots): Clarify that the list of syntaxes is exhaustive.

	* doc/gty.texi (GGC Roots): Clarify that the list of syntaxes
	is exhaustive.
	(Files): Improve documentation on generated source files.

	* doc/extend.texi (Translation implementation): Document what
	diagnostics look like.
	(Identifiers implementation): Document that there's normally no
	limit on identifier names.
	(Integers implementation): Document two's complement.
	(Hints implementation): Document that GCC honours 'inline', mostly.
	(Preprocessing directives implementation): Document that GCC
	requires the current time.

From-SVN: r55857

gcc/ChangeLog

+2002-07-29  Geoffrey Keating  <geoffk@redhat.com>
+
+	* doc/gty.texi (GGC Roots): Clarify that the list of syntaxes
+	is exhaustive.
+	(Files): Improve documentation on generated source files.
+
+	* doc/extend.texi (Translation implementation): Document what
+	diagnostics look like.
+	(Identifiers implementation): Document that there's normally no
+	limit on identifier names.
+	(Integers implementation): Document two's complement.
+	(Hints implementation): Document that GCC honours 'inline', mostly.
+	(Preprocessing directives implementation): Document that GCC
+	requires the current time.
+
 2002-07-30  Gabriel Dos Reis  <gdr@nerim.net>
 
 	* c-pretty-print.h (struct c_pretty_print_info): Add new member.

gcc/doc/extend.texi

@@ -35,6 +35,8 @@ along with the section number from the ISO/IEC 9899:1999 standard.
 @item
 @cite{How a diagnostic is identified (3.10, 5.1.1.3).}
 
+Diagnostics consist of all the output sent to stderr by GCC.
+
 @item
 @cite{Whether each nonempty sequence of white-space characters other than
 new-line is retained or replaced by one space character in translation
@@ -58,6 +60,11 @@ and their correspondence to universal character names (6.4.2).}
 @item
 @cite{The number of significant initial characters in an identifier
 (5.2.4.1, 6.4.2).}
+
+For internal names, all characters are significant.  For external names,
+the number of significant characters are defined by the linker; for
+almost all targets, all characters are significant.
+
 @end itemize
 
 @node Characters implementation
@@ -123,6 +130,9 @@ sequence not represented in the execution character set (6.4.5).}
 two's complement, or one's complement, and whether the extraordinary value
 is a trap representation or an ordinary value (6.2.6.2).}
 
+GCC supports only two's complement integer types, and all bit patterns
+are ordinary values.
+
 @item
 @cite{The rank of any extended integer type relative to another extended
 integer type with the same precision (6.3.1.1).}
@@ -242,6 +252,11 @@ storage-class specifier are effective (6.7.1).}
 @cite{The extent to which suggestions made by using the inline function
 specifier are effective (6.7.4).}
 
+GCC will not inline any functions if the @option{-fno-inline} option is
+used or if @option{-O0} is used.  Otherwise, GCC may still be unable to
+inline a function for many reasons; the @option{-Winline} option may be
+used to determine if a function has not been inlined and why not.
+
 @end itemize
 
 @node Structures unions enumerations and bit-fields implementation
@@ -315,6 +330,8 @@ name (6.10.2).}
 @item
 @cite{The nesting limit for @code{#include} processing (6.10.2).}
 
+GCC imposes a limit of 200 nested @code{#include}s.
+
 @item
 @cite{Whether the @samp{#} operator inserts a @samp{\} character before
 the @samp{\} character that begins a universal character name in a
@@ -328,6 +345,8 @@ directive (6.10.6).}
 @cite{The definitions for @code{__DATE__} and @code{__TIME__} when
 respectively, the date and time of translation are not available (6.10.8).}
 
+GCC assumes that the date and time is always available.
+
 @end itemize
 
 @node Library functions implementation

gcc/doc/gty.texi

@@ -218,6 +218,14 @@ two syntaxes it accepts to indicate a root:
 @verb{|static GTY (([options])) [type] ID;|}
 @end enumerate
 
+These are the only syntaxes that are accepted.  In particular, if you
+want to mark a variable that is only declared as
+@verbatim
+int ID;
+@end verbatim
+or similar, you should either make it @code{static} or you should create
+a @code{extern} declaration in a header file somewhere.
+
 @node Files
 @section Source Files Containing Type Information
 @cindex generated files
@@ -254,16 +262,28 @@ should be included in the @file{gtfiles} variable for such front ends.
 @end enumerate
 
 @item
-You need to include the file that the type machinery will generate in
-the source file you just changed.  The file will be called
-@file{gt-@var{path}.h} where @var{path} is the pathname from the
-@file{gcc} directory with slashes replaced by @verb{|-|}.  Don't forget
-to mention this file as a dependency in the @file{Makefile}!
+If the file was a header file, you'll need to check that it's included
+in the right place to be visible to the generated files.  For a back-end
+header file, this should be done automatically.  For a front-end header
+file, it needs to be included by the same file that includes
+@file{gtype-@var{lang}.h}.  For other header files, it needs to be
+included in @file{gtype-desc.c}, which is a generated file, so add it to
+@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.  
+
+For source files that aren't header files, the machinery will generate a
+header file that should be included in the source file you just changed.
+The file will be called @file{gt-@var{path}.h} where @var{path} is the
+pathname relative to the @file{gcc} directory with slashes replaced by
+@verb{|-|}, so for example the header file to be included in
+@file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}.  The
+generated header file should be included after everything else in the
+source file.  Don't forget to mention this file as a dependency in the
+@file{Makefile}!
 
 @item
-Finally, you need to arrange to add a @file{Makefile} rule that will
-ensure this file can be built.  This is done by making it a dependency
-of @code{s-gtype}, like this:
+If a new @file{gt-@var{path}.h} file is needed, you need to arrange to
+add a @file{Makefile} rule that will ensure this file can be built.
+This is done by making it a dependency of @code{s-gtype}, like this:
 @verbatim
 gt-path.h : s-gtype ; @true
 @end verbatim