1 files changed, 235 insertions, 0 deletions
diff --git a/gnu/usr.bin/cc/doc/templates.texi b/gnu/usr.bin/cc/doc/templates.texi
new file mode 100644
index 0000000..2a6db07
--- /dev/null
+++ b/gnu/usr.bin/cc/doc/templates.texi
@@ -0,0 +1,235 @@
+@node Templates
+@chapter The Template Implementation
+
+@cindex templates
+@cindex function templates
+@cindex class templates
+@cindex parameterized types
+@cindex types, parameterized
+The C++ template@footnote{Class templates are also known as
+@dfn{parameterized types}.} facility, which effectively allows use of
+variables for types in declarations, is one of the newest features of
+the language.
+
+@sc{gnu} C++ is one of the first compilers to implement many
+of the template facilities currently defined by the @sc{ansi} committee.
+
+Nevertheless, the template implementation is not yet complete.  This
+chapter maps the current limitations of the @sc{gnu} C++ template
+implementation.
+
+@menu
+* Template limitations:: Limitations for function and class templates
+* Function templates::   Limitations for function templates
+* Class templates::      Limitations for class templates
+* Template debugging::   Debugging information for templates
+@end menu
+
+@node Template limitations
+@section Limitations for function and class templates
+
+@cindex template limitations
+@cindex template bugs
+@cindex bugs, templates
+These limitations apply to any use of templates (function templates or
+class templates) with @sc{gnu} C++:
+
+@table @emph
+@item Template definitions must be visible
+When you compile code with templates, the template definitions must come
+first (before the compiler needs to expand them), and template
+definitions you use must be visible in the current scope.
+@c FIXME! Is this a defined property of templates, rather than a
+@c temporary limitation?
+@c ANSWER: It's a limitation, but it's hard to say why it's a limitation
+@c to someone.  We need an infinite link-cycle, in one camp, to
+@c accomplish things so you don't need the template definitions around.
+
+@cindex static data in template classes
+@cindex template classes, static data in
+@item Individual initializers needed for static data
+Templates for static data in template classes do not work.  @xref{Class
+templates,,Limitations for class templates}.
+@end table
+
+@node Function templates
+@section Limitations for function templates
+
+@cindex function template limitations
+Function templates are implemented for the most part.  The compiler can
+correctly determine template parameter values, and will delay
+instantiation of a function that uses templates until the requisite type
+information is available.
+
+@noindent
+The following limitations remain: 
+
+@itemize @bullet
+@cindex template vs declaration, functions
+@cindex declaration vs template, functions
+@cindex function declaration vs template
+@item
+Narrowed specification: function declarations should not prevent
+template expansion.  When you declare a function, @sc{gnu} C++
+interprets the declaration as an indication that you will provide a
+definition for that function.  Therefore, @sc{gnu} C++ does not use a
+template expansion if there is also an applicable declaration.  @sc{gnu}
+C++ only expands the template when there is no such declaration.
+
+The specification in Bjarne Stroustrup's @cite{The C++ Programming
+Language, Second Edition} is narrower, and the @sc{gnu} C++
+implementation is now clearly incorrect.  With this new specification, a
+declaration that corresponds to an instantiation of a function template
+only affects whether conversions are needed to use that version of the
+function.  It should no longer prevent expansion of the template
+definition.
+
+For example, this code fragment must be treated differently:
+
+@smallexample
+template <class X> X min (X& x1, X& x2) @{ @dots{} @}
+int min (int, int);
+@dots{}
+int i; short s;
+min (i, s); // @r{should call} min(int,int)
+            // @r{derived from template}
+@dots{}
+@end smallexample
+
+@item
+The compiler does not yet understand function signatures where types are
+nested within template parameters.  For example, a function like the
+following produces a syntax error on the closing @samp{)} of the
+definition of the function @code{f}:
+
+@smallexample
+template <class T> class A @{ public: T x; class Y @{@}; @};
+template <class X> int f (A<X>::Y y) @{ @dots{} @}
+@end smallexample
+
+@cindex @code{inline} and function templates
+@cindex function templates and @code{inline}
+@item
+If you declare an @code{inline} function using templates, the compiler
+can only inline the code @emph{after} the first time you use
+that function with whatever particular type signature the template
+was instantiated.
+
+Removing this limitation is akin to supporting nested function
+definitions in @sc{gnu} C++; the limitation will probably remain until the
+more general problem of nested functions is solved.
+
+@item
+All the @emph{method} templates (templates for member functions) for a
+class must be visible to the compiler when the class template is
+instantiated. 
+@end itemize
+
+@node Class templates
+@section Limitations for class templates
+
+@cindex class template limitations
+@ignore
+FIXME!!  Include a comprehensible version of this if someone can explain it.
+         (Queried Brendan and Raeburn w/full orig context, 26may1993---pesch)
+   - [RHP: I don't understand what the following fragment refers to.  If it's
+     the "BIG BUG" section in the original, why does it say "overriding class
+     declarations" here when the more detailed text refers to *function*
+     declarations?  Here's the fragment I don't understand:] 
+     there are problems with user-supplied overriding class declarations (see
+     below). 
+@end ignore
+
+@itemize @bullet
+@ignore
+@cindex static data, not working in templates
+@item
+Templates for static data in template classes do not work.
+Currently, you must initialize each case of such data
+individually. 
+@c FIXME!! Brendan to see if still true.
+@c ANSWER: This section presumes that it's incorrect to have to
+@c initialize for each type you instantiate with.  It's not, it's the
+@c right way to do it.
+@end ignore
+
+Unfortunately, individual initializations of this sort are likely to be
+considered errors eventually; since they're needed now, you might want to
+flag places where you use them with comments to mark the need for a
+future transition.
+
+@cindex nested type results vs templates
+@item
+Member functions in template classes may not have results of nested
+type; @sc{gnu} C++ signals a syntax error on the attempt.  The following
+example illustrates this problem with an @code{enum} type @code{alph}:
+
+@smallexample
+template <class T> class list @{
+  @dots{}
+  enum alph @{a,b,c@};
+  alph bar();
+  @dots{}
+@};
+
+template <class T>
+list<int>::alph list<int>::bar()  // @i{Syntax error here}
+@{
+@dots{}
+@}
+@end smallexample
+
+@cindex preprocessor conditionals in templates
+@cindex conditionals (preprocessor) in templates
+@item
+A parsing bug makes it difficult to use preprocessor conditionals within
+templates.  For example, in this code:
+
+@smallexample
+template <class T>
+class list @{
+  @dots{}
+#ifdef SYSWRONG
+  T x;
+#endif
+  @dots{}
+@}
+@end smallexample
+
+The preprocessor output leaves sourcefile line number information (lines
+like @samp{# 6 "foo.cc"} when it expands the @code{#ifdef} block.  These
+lines confuse the compiler while parsing templates, giving a syntax
+error.
+
+If you cannot avoid preprocessor conditionals in templates, you can
+suppress the line number information using the @samp{-P} preprocessor
+option (but this will make debugging more difficult), by compiling the
+affected modules like this:
+
+@smallexample
+g++ -P foo.cc -o foo
+@end smallexample
+
+@cindex parsing errors, templates
+@item
+Parsing errors are reported when templates are first
+@emph{instantiated}---not on the template definition itself.  In
+particular, if you do not instantiate a template definition at all, the
+compiler never reports any parsing errors that may be in the template
+definition.
+@end itemize
+
+@node Template debugging
+@section Debugging information for templates
+
+@cindex templates and debugging information
+@cindex debugging information and templates
+Debugging information for templates works for some object code formats,
+but not others.  It works for stabs@footnote{Except that insufficient
+debugging information for methods of template classes is generated in
+stabs.} (used primarily in @sc{a.out} object code, but also in the Solaris 2
+version of @sc{elf}), and the @sc{mips} version of @sc{coff} debugging
+format.
+
+@sc{dwarf} support is currently minimal, and requires further
+development.