qdoc: Updated the qdoc manual.

1 files changed, 44 insertions, 285 deletions

diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index dd65769..533e730 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -1118,57 +1118,10 @@
            \endquotation
 
            Each section level is a logical unit within the
-           document. Its title will appear on the table of contents
-           generated by the \l
-           {11-qdoc-commands-documentcontents.html#tableofcontents}
-           {\\tableofcontents} command. For example:
-
-           \code
-           / *!
-               Contents:
-
-               \tableofcontents
-
-               ...
-            * /
-            \endcode
-
-            will expand to
-
-            \quotation
-            \raw HTML
-                <p>Contents:</p>
-
-                <ul>
-                <li><a href="#Basic Qt">Basic Qt</a></li>
-                    <ul>
-                    <li><a href="#Getting Started">Getting Started</a></li>
-                        <ul>
-                        <li><a href="#Hello Qt">Hello Qt</a></li>
-                        <li><a href="#Making Connections">
-                            Making Connections</a></li>
-                        <li><a href="#Using the Reference Documentation">
-                            Using the Reference Documentation</a></li>
-                        </ul>
-                    <li><a href="#Creating Dialogs">Creating Dialogs</a></li>
-                        <ul>
-                        <li><a href="#Subclassing QDialog">
-                            Subclassing QDialog</a></li>
-                        </ul>
-                    </ul>
-                <li><a href="#Intermediate Qt">Intermediate Qt</a></li>
-                    <ul>
-                    <li><a href="#Layout Management">
-                        Layout Management</a></li>
-                        <ul>
-                        <li><a href="#Basic Layouts">Basic Layouts</a></li>
-                        </ul>
-                    </ul>
-                </ul>
-
-                ...
-            \endraw
-            \endquotation
+           document. Its title will appear in the table of contents
+           automatically generated by QDoc. The automatically 
+	   generated table of contents appears in the upper
+	   righthand corner of the page.
 
     \row
         \o \bold \\chapter \target chapter
@@ -3181,33 +3134,9 @@
            The abstract section is rendered as an indented italicized
            paragraph.
 
-           \warning This is preliminary funcionality. The
-           command is not fully implemented. Currently, the abstract
-           section is rendered as a regular HTML paragraph. For
-           example:
-
-           \code
-           / *!
-               \abstract
-                   Qt by Trolltech is a C++ toolkit for cross-platform
-                   GUI application development. Qt provides
-                   single-source portability across Microsoft Windows,
-                   Mac OS X, Linux, and all major commercial Unix
-                   variants. It is also available for embedded
-                   devices.
-               \endabstract
-           * /
-           \endcode
-
-           will be rendered as
-
-           \abstract
-              Qt by Trolltech is a C++ toolkit for cross-platform GUI
-              application development. Qt provides single-source
-              portability across Microsoft Windows, Mac OS X, Linux,
-              and all major commercial Unix variants. It is also
-              available for embedded devices.
-           \endabstract
+           \warning The \bold{\\abstract} and \bold{\\endabstract} commands 
+	   have not been implemented. The abstract section is rendered as a 
+	   regular HTML paragraph.
 
     \row
         \o \bold \\quotation \target quotation
@@ -3258,187 +3187,19 @@
         \o \bold {The \\footnote command and the corresponding
            \\endfootnote command delimit a footnote.}
 
-           The footnote follows the standard conventions, rendered at the
-           bottom of the page.
+           The footnote is rendered at the bottom of the page.
 
-           \warning This is preliminary funcionality. The
-           command is not fully implemented.
-
-           For example:
-
-           \code
-           / *!
-               In Qt 4 we have tried to simplify the constructors of
-               QObject/QWidget subclasses. This makes subclassing
-               easier, at the same time as it helps make the Qt
-               library more efficient.
-
-               \footnote
-               Constructors no longer take a "const char *name"
-               parameter. If you want to specify a name for a QObject,
-               you must call QObject::setObjectName() after
-               construction. The object name is now a QString.
-               \endfootnote
-
-               QWidget's WFlags data type has been split in two:
-               Qt::WindowFlags specifies low-level window flags (the
-               type of window and the frame style), whereas
-               Qt::WidgetAttribute specifies various higher-level
-               attributes about the widget (e.g.,
-               WA_StaticContents).
-           * /
-           \endcode
-
-           will be rendered as
-
-           \quotation
-               In Qt 4 we have tried to simplify the constructors of
-               QObject/QWidget subclasses. This makes subclassing
-               easier, at the same time as it helps make the Qt
-               library more efficient.
-
-               \footnote
-               Constructors no longer take a "const char *name"
-               parameter. If you want to specify a name for a QObject,
-               you must call QObject::setObjectName() after
-               construction. The object name is now a QString.
-               \endfootnote
-
-               QWidget's WFlags data type has been split in two:
-               Qt::WindowFlags specifies low-level window flags (the
-               type of window and the frame style), whereas
-               Qt::WidgetAttribute specifies various higher-level
-               attributes about the widget (e.g.,
-               WA_StaticContents).
-           \endquotation
+           \warning The \bold{\\footnote} and \bold{\\endfootnote} 
+	   commands have not been implemented. The footnote is 
+	   rendered as a regular HTML paragraph.
 
     \row
         \o \bold \\tableofcontents \target tableofcontents
-        \o \bold {The \\tableofcontents command generates a
-           table displaying the titles of the current documentation
-           unit's parts, chapters, sections, etc.}
-
-           The command accepts a single optional argument:
-
-           \code
-               \tableofcontents sectionN
-           \endcode
-
-           where \c sectionN is the deepest section to include (by
-           default all sections are included).
-
-           For example, it the documentation unit's structure looks
-           something like this:
-
-           \quotation
-           \raw HTML
-               <a name="Basic Qt">
-               <h1>Basic Qt</h1>
-               </a>
-               <p>This is the first part.</p>
-
-                   <a name="Getting started">
-                   <h2>Getting Started</h2>
-                   </a>
-                   This is the first part's first chapter.</p>
-
-                       <a name="Hello Qt">
-                       <h3>Hello Qt</h3>
-                       </a>
-                       <p>This is the first chapter's first section.</p>
-
-                       <a name="Making Connections">
-                       <h3>Making Connections</h3>
-                       </a>
-                       <p>This is the first chapter's second section.</p>
-
-                       <a name="Using the Reference Documentation">
-                       <h3>Using the Reference Documentation</h3>
-                       </a>
-                       <p>This is the first chapter's third section.</p>
-
-                   <a name="Creating Dialogs">
-                   <h2>Creating Dialogs</h2>
-                   </a>
-                   <p>This is the first part's second chapter.</p>
-
-                       <a name="Subclassing QDialog">
-                       <h3>Subclassing QDialog</h3>
-                       </a>
-                       <p>This is the second chapter's first section.</p>
-
-                       ...
-
-               <a name="Intermediate Qt">
-               <h1>Intermediate Qt</h1>
-               </a>
-               <p>This is the second part.</p>
-
-                   <a name="Layout Management">
-                   <h2>Layout Management</h2>
-                   </a>
-                   <p>This is the second part's first chapter.</p>
-
-                       <a name="Basic Layouts">
-                       <h3>Basic Layouts</h3>
-                       </a>
-                       <p>This is the first chapter's first section.</p>
-
-               ...
-
-           \endraw
-           \endquotation
-
-           Then
-
-           \code
-           / *!
-               Contents:
-
-               \tableofcontents
+        \o \bold {The \\tableofcontents command has been disabled because QDoc 
+	now generates a table of contents automatically.}
 
-               ...
-           * /
-           \endcode
-
-           will expand to
-
-           \quotation
-           \raw HTML
-               <p>Contents:</p>
-
-               <ul>
-               <li><a href="#Basic Qt">Basic Qt</a></li>
-                   <ul>
-                   <li><a href="#Getting Started">Getting Started</a></li>
-                       <ul>
-                       <li><a href="#Hello Qt">Hello Qt</a></li>
-                       <li><a href="#Making Connections">
-                           Making Connections</a></li>
-                       <li><a href="#Using the Reference Documentation">
-                           Using the Reference Documentation</a></li>
-                       </ul>
-                   <li><a href="#Creating Dialogs">Creating Dialogs</a></li>
-                       <ul>
-                       <li><a href="#Subclassing QDialog">
-                           Subclassing QDialog</a></li>
-                       </ul>
-                   </ul>
-               <li><a href="#Intermediate Qt">Intermediate Qt</a></li>
-                   <ul>
-                   <li><a href="#Layout Management">Layout Management</a></li>
-                       <ul>
-                       <li><a href="#Basic Layouts">Basic Layouts</a></li>
-                       </ul>
-                   </ul>
-               </ul>
-
-               ...
-           \endraw
-           \endquotation
-
-           Each table entry becomes a link to the corresponding part,
-           chapter or section.
+        The automatically generated table of contents appears in the upper
+	righthand corner of the page.
 
     \row
         \o \bold \\brief \target brief-command
@@ -3888,7 +3649,7 @@
            \code
            / *!
                \page classes.html
-               \title All Qt Classes (main index)
+               \title All Classes
 
                For a shorter list that only includes the most
                frequently used classes, see \l{Qt's Main Classes}. For
@@ -3899,7 +3660,7 @@
            * /
            \endcode
 
-           is used to generate \l {All Qt Classes (main index)}.
+           is used to generate \l {All Classes}.
 
            The command accepts the following arguments:
 
@@ -4188,7 +3949,7 @@
               {page} {\\page} and \l {group-command} {\\group}. The list omits
               examples and classes, and only lists the first page of
               documentation that contains two or more pages using
-              commands like \l {nextpage} {\\nextpage}.
+              commands like \l {nextpage-command} {\\nextpage}.
 
               For example:
 
@@ -5061,15 +4822,15 @@
            The command follows \l {topical argument} {the general
            topical command convention} for the argument. In particular
            the command's argument is the example's path relative to
-           the paths listed in the \l exampledirs configuration
-           variable.
+           the paths listed in the \l {exampledirs-variable}
+           {exampledirs} configuration variable.
 
            The documentation will be located in \i
            {path-to-example}.html, and QDoc will add a list of all the
            example files at the top of this documentation page.
 
-           For example, if \l exampledirs contain \c
-           $QTDIR/examples/widgets/imageviewer, then
+           For example, if \l {exampledirs-variable} {exampledirs}
+           contains \c $QTDIR/examples/widgets/imageviewer, then
 
            \code
            / *!
@@ -6057,7 +5818,7 @@
     \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule},
     \l {16-qdoc-commands-status.html#internal} {\\internal},
     \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass},
-    \l {15-qdoc-commands-navigation.html#nextpage} {\\nextpage},
+    \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage},
     \l {17-qdoc-commands-thread.html#nonreentrant} {\\nonreentrant},
     \l {16-qdoc-commands-status.html#obsolete} {\\obsolete},
     \l {18-qdoc-commands-relating.html#overload} {\\overload},
@@ -6098,7 +5859,7 @@
 
     \l {15-qdoc-commands-navigation.html#contentspage} {\\contentspage},
     \l {15-qdoc-commands-navigation.html#indexpage} {\\indexpage},
-    \l {15-qdoc-commands-navigation.html#nextpage} {\\nextpage},
+    \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage},
     \l {15-qdoc-commands-navigation.html#previouspage} {\\previouspage},
     \l {15-qdoc-commands-navigation.html#startpage} {\\startpage}
 
@@ -6260,7 +6021,7 @@
            Description} section.
 
     \row
-        \o \bold \\nextpage \target nextpage
+        \o \bold \\nextpage \target nextpage-command
         \o \bold {The \\nextpage command links the current
            page to the next page in an ordered series of documents}.
 
@@ -7295,7 +7056,7 @@
        {Cpp.ignoretokens},
     \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines},
     \l {22-qdoc-configuration-generalvariables.html#edition} {edition},
-    \l {22-qdoc-configuration-generalvariables.html#exampledirs} {exampledirs},
+    \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs},
     \l {22-qdoc-configuration-generalvariables.html#examples} {examples},
     \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions}
        {examples.fileextensions},
@@ -7384,7 +7145,7 @@
     \l {22-qdoc-configuration-generalvariables.html#codeindent} {codeindent},
     \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines},
     \l {22-qdoc-configuration-generalvariables.html#edition} {edition},
-    \l {22-qdoc-configuration-generalvariables.html#exampledirs} {exampledirs},
+    \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs},
     \l {22-qdoc-configuration-generalvariables.html#examples} {examples},
     \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions}
        {examples.fileextensions},
@@ -7543,7 +7304,7 @@
            \endcode
 
     \row
-        \o \bold exampledirs \target exampledirs
+        \o \bold exampledirs \target exampledirs-variable
         \o \bold {The \c exampledirs variable specifies the directories
            containing the source code of the example files.}
 
@@ -7602,31 +7363,29 @@
         \o \bold examples \target examples
         \o \bold {The \c examples variable allows you to specify individual
            example files in addition to those located in the directories
-           specified by the \l {exampledirs} {\c exampledirs} variable.}
+           specified by the \l {exampledirs-variable} {\c exampledirs} variable.}
 
-           The \c examples and \l {exampledirs} {\c exampledirs}
-           variables are used by the \l
-           {quotefromfile-command} {\\quotefromfile}, \l
-           {quotefile-command} {\\quotefile} and \l {example} {\\example}
-           commands. If both the \c examples and \l {exampledirs} {\c
-           exampledirs} variables are defined, QDoc will search in
-           both, first in \c examples then in \l {exampledirs} {\c
-           exampledirs}.
+           The \c examples and \l {exampledirs-variable} {\c exampledirs} 
+	   variables are used by the \l {quotefromfile-command} {\\quotefromfile}, 
+	   \l {quotefile-command} {\\quotefile} and \l {example}
+           {\\example} commands. If both the \c examples and \l {exampledirs-variable} 
+	   {\c exampledirs} variables are defined, QDoc will search in both, first in 
+	   \c examples then in \l {exampledirs-variable} {\c exampledirs}.
 
-           QDoc will search through the values listed for the \c
-           examples variable, in the specified order, and accept
-           the first one it finds.
+           QDoc will search through the values listed for the \c examples 
+	   variable, in the specified order, and accept the
+           first one it finds.
 
-           For an extensive example, see the \l {exampledirs} {\c
-           exampledirs} command. But note that if you know the file is
-           listed in the \c examples variable, you don't need to
-           specify its path:
+           For an extensive example, see the \l {exampledirs-variable} 
+	   {\c exampledirs} command. But note that if you know the file is
+           listed in the \c examples variable, you don't need to specify its 
+	   path:
 
            \code
                \quotefromfile calculator.cpp
            \endcode
 
-           See also \l exampledirs.
+           See also \l {exampledirs-variable} {exampledirs}.
 
     \row
         \o \bold examples.fileextensions \target examples.fileextensions
@@ -8963,7 +8722,7 @@
     \o \l {12-0-qdoc-commands-miscellaneous.html#meta} {\\meta}
     \o \l {13-qdoc-commands-topical.html#module} {\\module}
     \o \l {13-qdoc-commands-topical.html#namespace} {\\namespace}
-    \o \l {15-qdoc-commands-navigation.html#nextpage} {\\nextpage}
+    \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage}
     \o \l {06-qdoc-commands-verbatimcode.html#newcode} {\\newcode}
     \o \l {17-qdoc-commands-thread.html#nonreentrant} {\\nonreentrant}
     \o \l {10-qdoc-commands-container.html#o} {\\o}