Merge earth-team into origin/master'

1 files changed, 159 insertions, 92 deletions

diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 712dcea..0e4055b 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -58,7 +58,7 @@
         \endlist
       \o \l {The QDoc Configuration File}
         \list
-          \o \l {General Configuration Variables}
+          \o \l {Generic Configuration Variables}
           \o \l {Creating Help Project Files}
           \o \l {C++ Specific Configuration Variables}
           \o \l {HTML Specific Configuration Variables}
@@ -79,12 +79,13 @@
 
     \title Introduction to QDoc
 
-    QDoc is a tool used by Qt Developers to generate documentation of
-    software projects by extracting the documentation from the project
-    source files and then formatting it as HTML pages or DITA XML
-    documents, etc. The documentation is embedded in the source files
-    in \e {qdoc comments}. A qdoc comment begins with an exclamation
-    mark \bold{(!)} e.g.:
+    QDoc is a tool used by Qt Developers to generate documentation for
+    software projects. It works by extracting \e {qdoc comments} from
+    project source files and then formatting these comments as HTML
+    pages or DITA XML documents, etc. QDoc finds qdoc comments in \c
+    {.cpp} files and in \c {.qdoc} files. QDoc does not look for qdoc
+    comments in \c {.h} files. A qdoc comment always begins with an
+    exclamation mark \bold{!} e.g.:
 
     \code 
         / *! 
@@ -124,13 +125,14 @@
 	* /
     \endcode
 
-    From this snippet, QDoc generates the now famous HTML page \l
-    {http://doc.trolltech.com/4.7/qobject.html#details} {QObject Class Reference}.
+    From the qdoc comment above, QDoc generates the now famous HTML
+    page \l {http://doc.trolltech.com/4.7/qobject.html#details}
+    {QObject Class Reference}.
     
-    This manual explains how to use the QDoc commands to write useful
-    qdoc comments in your source files. It also explains how to create
-    a \l {The QDoc Configuration File} {QDoc configuration file},
-    which you must pass to QDoc on the command line when you run it.
+    This manual explains how to use the QDoc commands in qdoc comments
+    to embed good documentation in your source files. It also explains
+    how to make a \l {The QDoc Configuration File} {QDoc configuration
+    file}, which you will pass to QDoc on the command line.
 
     \section1 Running QDoc
 
@@ -138,17 +140,64 @@
     from the command line, give it the name of a configuration file:
 
     \quotation
-        \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf}
+        \c {$ ../../bin/qdoc3 ./config.qdocconf}
     \endquotation
 
-    \c{config.qdocconf} is your \l{The QDoc Configuration File} {QDoc
-    configuration file}. The configuration file is where tell QDoc
-    where to find the source files from which it will extract the QDoc
-    comments it will use to generate the documentation. It is also
-    where you tell QDoc what kind of output to generate (HTML, DITA
-    XML,...), and where to put the generated output. The configuration
+    QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
+    Configuration File} {QDoc configuration file}. The configuration
+    file is where you tell QDoc where to find the project source
+    files, header files, and \c {.qdoc} files. It is also where you
+    tell QDoc what kind of output to generate (HTML, DITA XML,...),
+    and where to put the generated documentation. The configuration
     file also contains other information for QDoc.
 
+    See \l{The QDoc Configuration File} for a instructions on how to
+    build a Qdoc configuration file.
+
+    \section1 How QDoc Works
+
+    QDoc begins by reading the configuarion file you specified on the
+    command line. It stores all the variables from the configuration
+    file for later use. One of the first variables it uses is \c
+    {outputformats}. This variable tells QDoc which output generators
+    it will run. The default value is \e {HTML}, so if you don't set
+    \c {outputformats} in your configuration file, QDoc will generate
+    HTML output. That's usually what you will want anyway, but you can
+    also specify \e {DITAXML} to get DITA XML output instead.
+
+    Next, QDoc uses the values of the \l
+    {22-qdoc-configuration-generalvariables.html#headerdirs-variable}
+    {headerdirs} variable and/or the \l
+    {22-qdoc-configuration-generalvariables.html#headers-variable}
+    {headers} variable to find and parse all the header files for your
+    project. QDoc does \e not scan header files for qdoc comments. It
+    parses the header files to build a master tree of all the items
+    that should be documented (i.e. the items that QDoc should find 
+    qdoc comments for).
+
+    After parsing all the header files and building the master tree of
+    items to be documented, QDoc uses the value of the \l
+    {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
+    {sourcedirs} variable and/or the value of the \l
+    {22-qdoc-configuration-generalvariables.html#sources-variable}
+    {sources} variable to find and parse all the \c {.cpp} and \c
+    {.qdoc} files for your project. These are the files QDoc scans for
+    \e {qdoc comments}. Remember that a qdoc comment begins with 
+    an exclamation mark, i.e. \bold {/*!} .
+
+    For each qdoc comment it finds, it searches the master tree for
+    the item where the documentation belongs. The it interprets the
+    qdoc commands in the comment and stores the interpreted commands
+    and the comment text in the tree node for the item. 
+
+    Finally, QDoc traverses the master tree. For each node, if the
+    node has stored documentation, QDoc calls the output generator
+    specified by the \c {outputformats} variable to format and write
+    the documentation in the directory specified in the configuration
+    file in the \l
+    {22-qdoc-configuration-generalvariables.html#outputdir-variable}
+    {outputdir} variable.
+
     \section1 Command Types
 
     QDoc interprets three types of commands: 
@@ -210,6 +259,7 @@
     \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
     \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
     \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
+    \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\input}
     \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
     \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
     \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
@@ -1388,9 +1438,6 @@
                application up and running.
            \endquotation
 
-    \warning If you use the \l {Compatibility Issues}
-    {compat.qdocconf} file this command is called \\include.
-
     See also \l {quotefromfile-command} {\\quotefromfile} and
     \l {code-command} {\\code}.
 
@@ -3916,24 +3963,28 @@
     \target include-command
     \section1 \\include 
 
-    The \\include command  expands to the contents of the
-    file specified by the command's argument.
-
-    \warning This is preliminary functionality. For more information,
-    see the \l
-    {26-qdoc-commands-compatibility.html#include-versus-input}
-    {compatibility} section.
-
-    The command takes a file name as an argument, and is useful when
-    some piece of the documentation is used repeatedly: Move the
-    repetetive text into a separate file, and use the \\include
-    command whenever you want to insert the separate documentation.
-
-    The contents of such a file should follow QDoc syntax, excluding
-    the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks.  To ensure that
-    QDoc won't attempt to read the file as a stand-alone piece of
-    documentation, we recommend that you use the \c .qdocinc
-    extension.
+    The \\include command sends all or part of the file specified by
+    its first argument to the QDoc input stream to be processed as a
+    qdoc comment snippet.  This command is often assigned the alias,
+    \e {input}, in the QDoc configuration file, e.g. \e {alias.include
+    = input}.
+
+    The command is useful when some snippet of commands and text is to
+    be used in multiple places in the documentation. In that case,
+    move the snippet into a separate file and use the \\include
+    command wherever you want to insert the snippet into the
+    documentation. To prevent QDoc from reading the file as a
+    stand-alone page of documentation, we recommend that you use the
+    \c .qdocinc extension for these \e {include} files.
+
+    The command can have either one or two arguments. The first
+    argument is always a file name. The contents of the file must be
+    QDoc input, i.e. a sequence of QDoc commands and text, but without
+    the enclosing qdoc comment \c{/}\c{*!}  ... \c{*}\c{/} delimeters.
+    If you want to include the entire named file, don't use the second
+    argument. If you want to include only part of the file, see the
+    \l{2-argument-form}{two argument form} below. Here is an example
+    of the one argument form:
 
             \code
             / *!
@@ -3946,7 +3997,9 @@
             * /
             \endcode
 
-    QDoc renders this as:
+    Here are links to the \c .qdocinc files used above:
+    \l{signalandslots.qdocinc}, \l{objectmodel.qdocinc},
+    \l{layoutmanagement.qdocinc}. QDoc renders this page as:
 
             \quotation
                 \raw HTML
@@ -3958,8 +4011,40 @@
                 \input examples/layoutmanagement.qdocinc
             \endquotation
 
-    Here is the actual \c .qdocinc files: \l signalandslots.qdocinc,
-    \l objectmodel.qdocinc, \l layoutmanagement.qdocinc
+    \target 2-argument-form}
+    \section2 \\include filename snippet-identifier
+
+    It is kind of a pain to make a separate \c .qdocinc file for every
+    QDoc include snippet you want to use in multiple places in the
+    documentation, especially given that you probably have to put the
+    copyright/license notice in every one of these files. So if you
+    have lots of these include snippets, you can put them all in a
+    single file if you want, and surround each one with:
+    \code
+        //! [snippet-id1]
+
+           QDoc commands and text...
+
+	//! [snippet-id1]
+
+        //! [snippet-id2]
+
+           More QDoc commands and text...
+
+	//! [snippet-id2]
+    \endcode
+
+    Then you can use the two-argument form of the command:
+
+    \code
+        \input examples/signalandslots.qdocinc snippet-id2
+        \input examples/objectmodel.qdocinc another-snippet-id
+    \endcode
+
+    It works as expected. The sequence of QDoc commands and text found
+    between the two tags with the same name as the second argument is
+    sent to the QDoc input stream. You can even nest these snippets,
+    although it's not clear why you would want to do that.
 
     \target meta-command
     \section1 \\meta 
@@ -6736,63 +6821,45 @@
     \page 21-0-qdoc-configuration.html
     \previouspage Miscellaneous
     \contentspage Table of Contents
-    \nextpage General Configuration Variables
+    \nextpage Generic Configuration Variables
 
     \title The QDoc Configuration File
 
-    Before running QDoc to to extract and format your QDOC comments,
-    you must create a QDoc configuration file to tell QDoc where to find 
-    them.
+    Before running QDoc, you must create a QDoc configuration file to
+    tell QDoc where to find the source files that contain the QDoc
+    comments. The pathname to your configuration file is passed to
+    QDoc on the command line:
 
-    \list
-    \o \l {Supporting Derived Projects}
-    \o \l {Compatibility Issues}
-    \endlist
-
-    When running QDoc to generate the documentation, you must specify
-    a configuration file on the command line:
+    \quotation
+        \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf}
+    \endquotation
 
     \section1 General Description
 
-    The configuration file is a list of entries of entries of the form
-    \e {"variable = value"}. Using the configuration variables, you
-    can define where QDoc should find the various source files, images
-    and examples, where to put generated documentation etc. The
+    The configuration file is a list of entries of the form \e
+    {"variable = value"}. Using the configuration variables, you can
+    define where QDoc should find the various source files, images and
+    examples, where to put generated documentation etc. The
     configuration file can also contain directives like \c
     include. For an example, see the \l minimum.qdocconf file.
 
-    In addition, you can use some particular configuration variables
-    to make QDoc support derived projects, i.e make the projects, for
-    example Qt Solutions, contain links to the online Qt
-    documentation. These variables are documented in the \l
-    {Supporting Derived projects} section. In this section you can
-    also find out how to use these variables to support your derived
-    projects.
-
-    If some of the variable keys have the same values, they can be set
-    at the same time.
-
-    \code
-    {header, source}dirs = kernel
-    \endcode
-
-    is equivalent to
-
-    \code
-    headerdirs = kernel
-    sourcedirs = kernel
-    \endcode
+    You can also use configuration variables to get QDoc to support
+    \l{Supporting Derived Projects} {derived projects}, i.e QDoc can
+    generate links in your project's documentation to elements in the
+    Qt online documentation. See the \l {Supporting Derived projects}
+    section. 
 
-    A variable's value can be set using either '=' or '+='. The
-    difference is that '=' overrides any previously set value, while
-    '+=' only adds the value to the previously set ones.
+    The value of a configuration variable can be set using either '='
+    or '+='. The difference is that '=' overrides the previous value,
+    while '+=' adds a new value to the current one.
 
-    In general, some of the variables accepts a list of strings as
-    their value, while others only accept a single string. If you
-    provide a variable of the latter type with several strings they
-    will simply be concatenated. The quotes around the value string
-    are optional. But applying them allows you to use special
-    characters like '=' and ' \" ' within the string.
+    Some configuration variables accept a list of strings as their
+    value, e.g. 
+    \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
+    {\c{sourcedirs}}, while others accept only a single string. Double
+    quotes around a value string are optional, but including them allows 
+    you to use special characters like '=' and ' \" ' within the valuem
+    string, e.g.:
 
     \code
     HTML.postheader = "<a href=\"index.html\">Home</a>"
@@ -6848,7 +6915,7 @@
     \section1 Categories
 
     \list
-    \o \l {General Configuration Variables}
+    \o \l {Generic Configuration Variables}
     \o \l {C++ Specific Configuration Variables}
     \o \l {HTML Specific Configuration Variables}
     \endlist
@@ -6889,7 +6956,7 @@
     \contentspage Table of Contents
     \nextpage Creating Help Project Files
 
-    \title General Configuration Variables
+    \title Generic Configuration Variables
 
     With the general QDoc configuration variables, you can define
     where QDoc will find the various source files it needs to generate
@@ -7766,7 +7833,7 @@
 
 /*!
     \page 22-creating-help-project-files.html
-    \previouspage General Configuration Variables
+    \previouspage Generic Configuration Variables
     \contentspage Table of Contents
     \nextpage C++ Specific Configuration Variables