From 90de2bb100b2f4a23655b2e914b93c644f1a4841 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Thu, 7 Apr 2011 09:59:57 +0200 Subject: qdoc: Updated the QDoc manual. --- src/gui/kernel/qwidget.cpp | 2 +- tools/qdoc3/doc/qdoc-manual.qdoc | 165 ++++++++++++++++++++++++++++++--------- 2 files changed, 128 insertions(+), 39 deletions(-) diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp index ac35d42..9d9cd75 100644 --- a/src/gui/kernel/qwidget.cpp +++ b/src/gui/kernel/qwidget.cpp @@ -598,7 +598,7 @@ void QWidget::setAutoFillBackground(bool enabled) \brief The QWidget class is the base class of all user interface objects. \ingroup basicwidgets - + The widget is the atom of the user interface: it receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen. Every widget is rectangular, and they are sorted in a diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 5b15fca..31c56a1 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -66,6 +66,7 @@ \o \l {Compatibility Issues} \o \l {qt.qdocconf} \o \l {minimum.qdocconf} + \o \l {Generating DITA XML Output} \endlist \endlist @@ -4037,48 +4038,77 @@ 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 + \target meta-command \section1 \\meta - The \\meta command is the QDoc equivalent to the HTML - \c meta tag. + The \\meta command is mainly used for including metadata in DITA + XML files. It is also used when generating HTML output for specifying + the \e maintainer(s) of a C++ class. - The command accepts two arguments: The first argument (the - following word) is equivalent to the HTML meta tag's \e name - variable, and the second argument (the rest of the line) is - equivalent to the tag's \e contents variable. + The command has two arguments: The first argument is the name of the + metadata attribute you wish to set, and the second argument is the + value for the attribute. Each argument should be enclosed in curly + brackets, as shown in this example: - \code - / *! - \meta author Summerfield - - \section1 Automatic Dialogs - - \abstract - This article shows how to maintain sets of - "attributes" (QVariant values), and how to allow - users to view and edit them using dialogs that are - created dynamically based on the attributes and - their types. - \endabstract - - The Attributes class described in this article holds a - set of QVariants, and can create a dialog to present - the QVariants to the user in an appropriate way. - - ... - * / - \endcode - - QDoc renders this as: + \code + / *! + \class QWidget + \brief The QWidget class is the base class of all user interface objects. + + \ingroup basicwidgets + + \meta {technology} {User Interface} + \meta {platform} {OS X 10.6} + \meta {platform} {Symbian} + \meta {platform} {MeeGo} + \meta {audience} {user} + \meta {audience} {programmer} + \meta {audience} {designer} + * / + \endcode - \code - - ... - - ... - - \endcode + When running QDoc to generate HTML, the example above will have no + effect on the generated output, but if you run QDoc to generate + DITA XML, the example will generate the following: + + \code + + + + + QWidget + the QWidget class is the base class of all user interface objects. + + Qt Development Frameworks + Nokia + + + Nokia + + + + + + + Class reference + + Qt Reference Documentation + + + + QtGui + + + + + + + + \endcode + + In the example output, several values have been set using defualt + values obtained from the QDoc configuration file. See \l + {Generating DITA XML Output} for details. \target omit-command \section1 \\omit @@ -6923,7 +6953,7 @@ \page 21-1-minimum-qdocconf.html \previouspage qt.qdocconf \contentspage Table of Contents - \nextpage Table of Contents + \nextpage Generating DITA XML Output \title minimum.qdocconf @@ -6942,6 +6972,65 @@ */ /*! + \page 21-3-qt-dita-xml-output.html + \previouspage minimum.qdocconf + \contentspage Table of Contents + \nextpage Table of Contents + + \title Generating DITA XML Output + + QDoc can generate \l {http://dita.xml.org} {DITA XML output}. + + In your confifiguration file, set your \c {outputformats} variable + to \c {DITAXML}, and send the output to an appropriate directory: + + \code + outputdir = $QTDIR/doc/ditaxml + outputformats = DITAXML + \endcode + + And include these macros in your configuration file to prevent + QDoc from doing some escaping that doesn't validate in XML: + + \code + macro.aacute.DITAXML = "á" + macro.Aring.DITAXML = "Å" + macro.aring.DITAXML = "å" + macro.Auml.DITAXML = "Ä" + macro.br.DITAXML = " " + macro.BR.DITAXML = " " + macro.copyright.DITAXML = "©" + macro.eacute.DITAXML = "é" + macro.hr.DITAXML = " " + macro.iacute.DITAXML = "í" + macro.oslash.DITAXML = "ø" + macro.ouml.DITAXML = "ö" + macro.raisedaster.DITAXML = "*" + macro.rarrow.DITAXML = "→" + macro.reg.DITAXML = "®" + macro.uuml.DITAXML = "ü" + macro.mdash.DITAXML = "—" + macro.emptyspan.DITAXML = " " + \endcode + + You can also set default values for some of the tags in the DITA + \c {} and \c {} elements: + + \code + dita.metadata.default.author = Qt Development Frameworks + dita.metadata.default.permissions = all + dita.metadata.default.publisher = Nokia + dita.metadata.default.copyryear = 2011 + dita.metadata.default.copyrholder = Nokia + dita.metadata.default.audience = programmer + \endcode + + See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command} + {\\meta} command for more details on DITA metadata. + +*/ + +/*! \page 22-qdoc-configuration-generalvariables.html \previouspage The QDoc Configuration File \contentspage Table of Contents -- cgit v0.12