Doc: Updated the qdoc manual with i18n info. Fixed a code example.

Reviewed-by: Trust Me

2 files changed, 90 insertions, 18 deletions

diff --git a/tools/qdoc3/doc/examples/main.cpp b/tools/qdoc3/doc/examples/main.cpp
index e2cf6c5..e439d3e 100644
--- a/tools/qdoc3/doc/examples/main.cpp
+++ b/tools/qdoc3/doc/examples/main.cpp
@@ -46,7 +46,7 @@ int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);
 
-    QPushButton *hello("Hello world!");
+    QPushButton hello("Hello world!");
     hello.resize(100, 30);
 
     hello.show();
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index e2f670c..482af46 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -78,10 +78,10 @@
        \endlist
     \o \l{QDoc Configuration}
        \list
-       \o \l{General Variables}
+       \o \l{General Configuration Variables}
        \o \l{Creating Help Project Files}
-       \o \l{C++ Specific Variables}
-       \o \l{HTML Specific Variables}
+       \o \l{C++ Specific Configuration Variables}
+       \o \l{HTML Specific Configuration Variables}
        \o \l{Supporting Derived Projects}
        \o \l{QDoc Compatibility}
        \o \l{qt.qdocconf}
@@ -1425,6 +1425,7 @@
 
                \quotefromfile examples/main.cpp
 
+               \skipto QApplication
                \printline QApplication
 
                This line includes the QApplication class
@@ -1652,6 +1653,7 @@
                can press and release.
 
                \quotefromfile examples/main.cpp
+               \skipto QApplication
                \skipline QApplication
                \printline QPushButton
 
@@ -6974,7 +6976,7 @@
     \page 21-0-qdoc-configuration.html
     \previouspage Title Commands
     \contentspage QDoc Manual - Table of Contents
-    \nextpage General Variables
+    \nextpage General Configuration Variables
 
     \title QDoc Configuration
 
@@ -7094,9 +7096,9 @@
     \section2 Categories
 
     \list
-    \o \l {General Variables}
-    \o \l {C++ Specific Variables}
-    \o \l {HTML Specific Variables}
+    \o \l {General Configuration Variables}
+    \o \l {C++ Specific Configuration Variables}
+    \o \l {HTML Specific Configuration Variables}
     \endlist
 
     \section1 Configuration File Examples
@@ -7133,7 +7135,7 @@
     \contentspage QDoc Manual - Table of Contents
     \nextpage Creating Help Project Files
 
-    \title General Variables
+    \title General Configuration Variables
 
     With the general QDoc configuration variables, you can define
     where QDoc will find the various source files it needs to generate
@@ -7215,7 +7217,7 @@
            QDoc originally used a hard-coded value of four spaces for
            code indentation to ensure that code snippets could be easily
            distinguished from surrounding text. Since we can use
-           \l{HTML Specific Variables#HTML.stylesheets}{stylesheets} to
+           \l{HTML Specific Configuration Variables#HTML.stylesheets}{stylesheets} to
            adjust the appearance of certain types of HTML elements, this
            level of indentation is not always required.
 
@@ -7572,7 +7574,7 @@
            \code
            header.fileextensions += *.H
            \endcode
-           
+
            \warning The above assignment may not work as described.
 
            See also \l headerdirs.
@@ -7730,6 +7732,27 @@
            bold font, and that \\raisedaster renders a '*'.
 
     \row
+        \o \bold naturallanguage \target naturallanguage
+        \o \bold {The \c naturallanguage variable specifies the natural
+           language used for the documentation generated by qdoc.}
+
+           For example:
+
+           \code
+           naturallanguage = zh-Hans
+           \endcode
+
+           By default, the natural language is \c en for compatibility
+           with legacy documentation.
+
+           qdoc will add the natural language information to the HTML
+           it generates, using the \c lang and \c xml:lang attributes.
+
+           See also \l sourceencoding, \l outputencoding,
+           \l{http://www.w3.org/TR/xhtml1/#C_7}{C.7. The lang and xml:lang Attributes} and
+           \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}{Best Practice 13: Using Hans and Hant codes}.
+
+    \row
         \o \bold outputdir \target outputdir
         \o \bold {The \c outputdir variable specifies the directory
            where QDoc will put the generated documentation.}
@@ -7754,6 +7777,31 @@
            directory, all files from the previous run will be lost.
 
     \row
+        \o \bold outputencoding \target outputencoding
+        \o \bold {The \c outputencoding variable specifies the encoding
+           used for the documentation generated by qdoc.}
+
+           For example:
+
+           \code
+           outputencoding = UTF-8
+           \endcode
+
+           By default, the output encoding is \c ISO-8859-1 (Latin1) for
+           compatibility with legacy documentation. When generating
+           documentation for some languages, particularly non-European
+           languages, this is not sufficient and an encoding such as UTF-8
+           is required.
+
+           qdoc will encode HTML using this encoding and generate the
+           correct declarations to indicate to browsers which encoding
+           is being used. The \l naturallanguage configuration variable
+           should also be specified to provide browsers with a complete
+           set of character encoding and language information.
+
+           See also \l outputencoding and \l naturallanguage.
+
+    \row
         \o \bold outputformats \target outputformats
         \o \bold {The \c outputformats variable specifies the format of
            the generated documentation.}
@@ -7831,6 +7879,30 @@
            See also \l sources and \l sources.fileextensions.
 
     \row
+        \o \bold sourceencoding \target sourceencoding
+        \o \bold {The \c sourceencoding variable specifies the encoding
+           used for the source code and documentation.}
+
+           For example:
+
+           \code
+           sourceencoding = UTF-8
+           \endcode
+
+           By default, the source encoding is \c ISO-8859-1 (Latin1) for
+           compatibility with legacy documentation. For some languages,
+           particularly non-European languages, this is not sufficient
+           and an encoding such as UTF-8 is required.
+
+           Although qdoc will use the encoding to read source and
+           documentation files, limitations of C++ compilers may prevent
+           you from using non-ASCII characters in source code comments.
+           In cases like these, it is possible to write API documentation
+           completely in documentation files.
+
+           See also \l naturallanguage and \l outputencoding.
+
+    \row
         \o \bold sources \target sources
         \o \bold {The \c sources variable allows you to specify
            individual source files in addition to those located in the
@@ -7973,9 +8045,9 @@
 
 /*!
     \page 22-creating-help-project-files.html
-    \previouspage General Variables
+    \previouspage General Configuration Variables
     \contentspage QDoc Manual - Table of Contents
-    \nextpage C++ Specific Variables
+    \nextpage C++ Specific Configuration Variables
 
     \title Creating Help Project Files
 
@@ -8023,9 +8095,9 @@
     \page 23-qdoc-configuration-cppvariables.html
     \previouspage Creating Help Project Files
     \contentspage QDoc Manual - Table of Contents
-    \nextpage HTML Specific Variables
+    \nextpage HTML Specific Configuration Variables
 
-    \title C++ Specific Variables
+    \title C++ Specific Configuration Variables
 
     The C++ specific configuration variables are provided to avoid
     erroneous documentation due to non-standard C++ constructs.
@@ -8159,11 +8231,11 @@
 
 /*!
     \page 24-qdoc-configuration-htmlvariables.html
-    \previouspage C++ Specific Variables
+    \previouspage C++ Specific Configuration Variables
     \contentspage QDoc Manual - Table of Contents
     \nextpage Supporting Derived Projects
 
-    \title HTML Specific Variables
+    \title HTML Specific Configuration Variables
 
     The HTML specific configuration variables define the generated
     documentation's style, or define the contents of the
@@ -8289,7 +8361,7 @@
 
 /*!
     \page 25-qdoc-configuration-derivedprojects.html
-    \previouspage HTML Specific Variables
+    \previouspage HTML Specific Configuration Variables
     \contentspage QDoc Manual - Table of Contents
     \nextpage QDoc Compatibility