[gtk-doc] docs: small doc update

[Stefan Kost <stefkost src gnome org>]

commit 70abe37062ace247e8941afc73f2dba0da39a431
Author: Stefan Kost <ensonic users sf net>
Date:   Wed Sep 8 23:01:40 2010 +0300

    docs: small doc update
    
    Mention in more places that tmpl-files and sgml support is legacy.

 README                           |    7 +++++--
 help/manual/C/gtk-doc-manual.xml |   17 +++++++++--------
 2 files changed, 14 insertions(+), 10 deletions(-)
---
diff --git a/README b/README
index 4a6b8c7..51d35ea 100644
--- a/README
+++ b/README
@@ -17,7 +17,7 @@ GTK-Doc allows your documentation to be written in 2 ways:
   a) Embedded inside the source code in specially-formatted comments.
  or
   b) Added to the 'template' files which gtk-doc outputs after scanning all
-     the header files and parsing the declarations.
+     the header files and parsing the declarations (deprecated now).
 
 From these source code comments and template files GTK-Doc generates a Docbook
 XML (or SGML) document, which is then transformed into HTML.
@@ -25,6 +25,9 @@ The generated HTML documentation can be browsed in an ordinary web browser or
 by using the special Devhelp API browser
 (see http://developer.imendio.com/wiki/Devhelp).
 
+Please don't use template files in new projects. Support for for those will
+be removed at some point in the future (together with gtkdoc-mktmpl). Please
+also use DoxBook XML instead of DocBook SGML. 
 
 Requirements
 ============
@@ -41,7 +44,7 @@ The DocBook XML DTD.
 The DocBook XSL Stylesheets.
     http://docbook.sourceforge.net/projects/xsl/
 
-libxslt & libxml2 2.3.6.
+libxslt & libxml2 >= 2.3.6.
     http://xmlsoft.org/
 
 
diff --git a/help/manual/C/gtk-doc-manual.xml b/help/manual/C/gtk-doc-manual.xml
index 9063be9..2217edf 100644
--- a/help/manual/C/gtk-doc-manual.xml
+++ b/help/manual/C/gtk-doc-manual.xml
@@ -222,7 +222,8 @@
             or <filename class='directory'>xml/</filename> subdirectory.
             If the source code contains documentation on functions, using the
             special comment blocks, it gets merged in here. If there are no tmpl files used
-            it only reads docs from sources and introspection data.
+            it only reads docs from sources and introspection data. We recommend
+            to use Docbook XML.
           </para>
           <para>
             <application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML
@@ -697,13 +698,13 @@ make
       </para>
 
       <tip>
-	<para>
-          If you need to use the special characters '&lt;', '&gt;', '()', '@',
-          '%', or '#' in your documentation without GTK-Doc changing them you
-          can use the XML entities "&amp;lt;", "&amp;gt;", "&amp;lpar;",
-          "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and "&amp;num;"
-          respectively or escape them with a backslash '\'.
-	</para>
+	  <para>
+        If you need to use the special characters '&lt;', '&gt;', '()', '@',
+        '%', or '#' in your documentation without GTK-Doc changing them you
+        can use the XML entities "&amp;lt;", "&amp;gt;", "&amp;lpar;",
+        "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and "&amp;num;"
+        respectively or escape them with a backslash '\'.
+	  </para>
       </tip>
 
       <para>