summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Boddie <david.boddie@nokia.com>2011-05-02 13:39:41 (GMT)
committerDavid Boddie <david.boddie@nokia.com>2011-05-02 13:39:41 (GMT)
commit6d5963486c8c2a154caf3a2a391bce19cbbeb881 (patch)
tree57a132edba61391ef795f3f8ccaa5ea7425cacde
parent63e89c45fcc07759c928231ac27cc25928116d45 (diff)
parent781967478a0ddc5b69663a49bb081d752f85dc99 (diff)
downloadQt-6d5963486c8c2a154caf3a2a391bce19cbbeb881.zip
Qt-6d5963486c8c2a154caf3a2a391bce19cbbeb881.tar.gz
Qt-6d5963486c8c2a154caf3a2a391bce19cbbeb881.tar.bz2
Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-doc-review into 4.7
-rw-r--r--doc/doc.pri4
-rw-r--r--doc/src/examples/ftp.qdoc4
-rwxr-xr-xdoc/src/template/scripts/functions.js2
-rw-r--r--examples/network/qftp/ftpwindow.cpp6
-rw-r--r--src/gui/itemviews/qdatawidgetmapper.cpp2
-rw-r--r--src/gui/kernel/qwidget.cpp2
-rw-r--r--tools/qdoc3/codemarker.h3
-rw-r--r--tools/qdoc3/config.cpp27
-rw-r--r--tools/qdoc3/config.h1
-rw-r--r--tools/qdoc3/ditaxmlgenerator.cpp102
-rw-r--r--tools/qdoc3/ditaxmlgenerator.h13
-rw-r--r--tools/qdoc3/doc/corefeatures.qdoc35
-rw-r--r--tools/qdoc3/doc/qdoc-manual.qdoc206
-rw-r--r--tools/qdoc3/htmlgenerator.cpp103
-rw-r--r--tools/qdoc3/pagegenerator.cpp6
15 files changed, 312 insertions, 204 deletions
diff --git a/doc/doc.pri b/doc/doc.pri
index 68d729b..253e1b4 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -13,12 +13,14 @@ win32:!win32-g++* {
unixstyle = true
}
+COPYWEBKITGUIDE = $$QT_SOURCE_TREE/examples/webkit/webkit-guide
+
$$unixstyle {
QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && QT_BUILD_TREE=$$QT_BUILD_TREE QT_SOURCE_TREE=$$QT_SOURCE_TREE $$QT_BUILD_TREE/bin/qdoc3 $$DOCS_GENERATION_DEFINES
- COPYWEBKITGUIDE = $$QT_SOURCE_TREE/examples/webkit/webkit-guide
} else {
QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && set QT_BUILD_TREE=$$QT_BUILD_TREE&& set QT_SOURCE_TREE=$$QT_SOURCE_TREE&& $$QT_BUILD_TREE/bin/qdoc3.exe $$DOCS_GENERATION_DEFINES
QDOC = $$replace(QDOC, "/", "\\")
+ COPYWEBKITGUIDE = $$replace(COPYWEBKITGUIDE, "/", "\\")
}
ADP_DOCS_QDOCCONF_FILE = qt-build-docs-online.qdocconf
QT_DOCUMENTATION = ($$QDOC qt-api-only.qdocconf assistant.qdocconf designer.qdocconf \
diff --git a/doc/src/examples/ftp.qdoc b/doc/src/examples/ftp.qdoc
index 4fa2cfd..841d298 100644
--- a/doc/src/examples/ftp.qdoc
+++ b/doc/src/examples/ftp.qdoc
@@ -131,7 +131,9 @@
\snippet examples/network/qftp/ftpwindow.cpp 5
- QFtp supports canceling the download of files.
+ QFtp supports canceling the download of files. We make sure that
+ any file that is currently being written to is closed and removed,
+ and tidy up by deleting the file object.
\snippet examples/network/qftp/ftpwindow.cpp 6
diff --git a/doc/src/template/scripts/functions.js b/doc/src/template/scripts/functions.js
index 62bc535..3ab4a08 100755
--- a/doc/src/template/scripts/functions.js
+++ b/doc/src/template/scripts/functions.js
@@ -184,7 +184,7 @@ var blankRE=/^\s*$/;
function CheckEmptyAndLoadList()
{
/* Start Extracting information for feedback and adding this to the feedback form */
- var pageUrl = window.location.href;
+ var pageUrl = window.location.pathname;
var pageVal = $('title').html();
$('#pageType').removeClass('red');
$('#feedUrl').remove();
diff --git a/examples/network/qftp/ftpwindow.cpp b/examples/network/qftp/ftpwindow.cpp
index c3e629f..159cad6 100644
--- a/examples/network/qftp/ftpwindow.cpp
+++ b/examples/network/qftp/ftpwindow.cpp
@@ -243,6 +243,12 @@ void FtpWindow::downloadFile()
void FtpWindow::cancelDownload()
{
ftp->abort();
+
+ if (file->exists()) {
+ file->close();
+ file->remove();
+ }
+ delete file;
}
//![5]
diff --git a/src/gui/itemviews/qdatawidgetmapper.cpp b/src/gui/itemviews/qdatawidgetmapper.cpp
index 745ef5a..dac4613 100644
--- a/src/gui/itemviews/qdatawidgetmapper.cpp
+++ b/src/gui/itemviews/qdatawidgetmapper.cpp
@@ -291,7 +291,7 @@ void QDataWidgetMapperPrivate::_q_modelDestroyed()
\snippet doc/src/snippets/code/src_gui_itemviews_qdatawidgetmapper.cpp 0
After the call to toFirst(), \c mySpinBox displays the value \c{1}, \c myLineEdit
- displays \c {Nokia Corporation and/or its subsidiary(-ies)} and \c myCountryChooser displays \c{Oslo}. The
+ displays \c{Qt Norway} and \c myCountryChooser displays \c{Oslo}. The
navigational functions toFirst(), toNext(), toPrevious(), toLast() and setCurrentIndex()
can be used to navigate in the model and update the widgets with contents from
the model.
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/codemarker.h b/tools/qdoc3/codemarker.h
index 21bc31f..00660e7 100644
--- a/tools/qdoc3/codemarker.h
+++ b/tools/qdoc3/codemarker.h
@@ -165,10 +165,11 @@ class CodeMarker
static const Node *nodeForString(const QString& string);
static QString stringForNode(const Node *node);
+ QString typified(const QString &string);
+
protected:
virtual QString sortName(const Node *node);
QString protect(const QString &string);
- QString typified(const QString &string);
QString taggedNode(const Node* node);
#ifdef QDOC_QML
QString taggedQmlNode(const Node* node);
diff --git a/tools/qdoc3/config.cpp b/tools/qdoc3/config.cpp
index 838f6ac..eaec327 100644
--- a/tools/qdoc3/config.cpp
+++ b/tools/qdoc3/config.cpp
@@ -48,7 +48,7 @@
#include <QFile>
#include <QTemporaryFile>
#include <QTextStream>
-
+#include <qdebug.h>
#include "config.h"
#include <stdlib.h>
@@ -175,6 +175,7 @@ Config::Config(const QString& programName)
}
/*!
+ The destructor has nothing special to do.
*/
Config::~Config()
{
@@ -202,6 +203,30 @@ void Config::load(const QString& fileName)
}
/*!
+ Writes the qdoc configuration data to the named file.
+ The previous contents of the file are overwritten.
+ */
+void Config::unload(const QString& fileName)
+{
+
+ QStringMultiMap::ConstIterator v = stringValueMap.begin();
+ while (v != stringValueMap.end()) {
+ qDebug() << v.key() << " = " << v.value();
+#if 0
+ if (v.key().startsWith(varDot)) {
+ QString subVar = v.key().mid(varDot.length());
+ int dot = subVar.indexOf(QLatin1Char('.'));
+ if (dot != -1)
+ subVar.truncate(dot);
+ t.insert(subVar,v.value());
+ }
+#endif
+ ++v;
+ }
+ qDebug() << "fileName:" << fileName;
+}
+
+/*!
Joins all the strings in \a values into a single string with the
individual \a values separated by ' '. Then it inserts the result
into the string list map with \a var as the key.
diff --git a/tools/qdoc3/config.h b/tools/qdoc3/config.h
index 8e19ed2..94f0060 100644
--- a/tools/qdoc3/config.h
+++ b/tools/qdoc3/config.h
@@ -63,6 +63,7 @@ class Config
~Config();
void load(const QString& fileName);
+ void unload(const QString& fileName);
void setStringList(const QString& var, const QStringList& values);
const QString& programName() const { return prog; }
diff --git a/tools/qdoc3/ditaxmlgenerator.cpp b/tools/qdoc3/ditaxmlgenerator.cpp
index 1bc4992..5f44cd8 100644
--- a/tools/qdoc3/ditaxmlgenerator.cpp
+++ b/tools/qdoc3/ditaxmlgenerator.cpp
@@ -92,6 +92,7 @@ QString DitaXmlGenerator::ditaTags[] =
"apiDesc",
"APIMap",
"apiName",
+ "apiRelation",
"audience",
"author",
"b",
@@ -284,14 +285,15 @@ void DitaXmlGenerator::writeCharacters(const QString& text)
with the \a href attribute and the \a text.
*/
void DitaXmlGenerator::addLink(const QString& href,
- const QStringRef& text)
+ const QStringRef& text,
+ DitaTag t)
{
if (!href.isEmpty()) {
- writeStartTag(DT_xref);
+ writeStartTag(t);
// formathtml
xmlWriter().writeAttribute("href", href);
writeCharacters(text.toString());
- writeEndTag(); // </xref>
+ writeEndTag(); // </t>
}
else {
writeCharacters(text.toString());
@@ -767,6 +769,7 @@ int DitaXmlGenerator::generateAtom(const Atom *atom,
case Atom::Code:
{
writeStartTag(DT_codeblock);
+ xmlWriter().writeAttribute("outputclass","cpp");
QString chars = trimmedTrailing(atom->string());
writeText(chars, marker, relative);
writeEndTag(); // </codeblock>
@@ -774,6 +777,7 @@ int DitaXmlGenerator::generateAtom(const Atom *atom,
break;
case Atom::Qml:
writeStartTag(DT_codeblock);
+ xmlWriter().writeAttribute("outputclass","qml");
writeText(trimmedTrailing(atom->string()), marker, relative);
writeEndTag(); // </codeblock>
break;
@@ -1718,7 +1722,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
*/
generateHeader(inner, fullTitle);
generateBrief(inner, marker); // <shortdesc>
- writeProlog(inner,marker);
+ writeProlog(inner);
writeStartTag(DT_cxxClassDetail);
writeStartTag(DT_cxxClassDefinition);
@@ -1838,7 +1842,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
generateHeader(inner, fullTitle);
generateBrief(inner, marker); // <shortdesc>
- writeProlog(inner,marker);
+ writeProlog(inner);
writeStartTag(DT_cxxClassDetail);
writeStartTag(DT_cxxClassDefinition);
@@ -1974,7 +1978,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
*/
generateHeader(inner, fullTitle);
generateBrief(inner, marker); // <shortdesc>
- writeProlog(inner,marker);
+ writeProlog(inner);
writeStartTag(DT_cxxClassDetail);
enterApiDesc(QString(),title);
@@ -2093,7 +2097,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark
generateHeader(inner, fullTitle);
generateBrief(inner, marker); // <shortdesc>
- writeProlog(inner,marker);
+ writeProlog(inner);
writeStartTag(DT_cxxClassDetail);
enterApiDesc(QString(),title);
@@ -2195,7 +2199,7 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker
generateHeader(fake, fullTitle);
generateBrief(fake, marker); // <shortdesc>
- writeProlog(fake, marker);
+ writeProlog(fake);
writeStartTag(DT_body);
enterSection(QString(),QString());
@@ -4712,7 +4716,7 @@ void DitaXmlGenerator::writeLocation(const Node* n)
Write the <cxxFunction> elements.
*/
void DitaXmlGenerator::writeFunctions(const Section& s,
- const Node* n,
+ const InnerNode* parent,
CodeMarker* marker,
const QString& attribute)
{
@@ -4775,7 +4779,7 @@ void DitaXmlGenerator::writeFunctions(const Section& s,
}
}
- if (fn->name() == n->name()) {
+ if (fn->name() == parent->name()) {
writeStartTag(DT_cxxFunctionConstructor);
xmlWriter().writeAttribute("name","constructor");
xmlWriter().writeAttribute("value","constructor");
@@ -4789,7 +4793,8 @@ void DitaXmlGenerator::writeFunctions(const Section& s,
}
else {
writeStartTag(DT_cxxFunctionDeclaredType);
- writeCharacters(fn->returnType());
+ QString src = marker->typified(fn->returnType());
+ replaceTypesWithLinks(fn,parent,marker,src);
writeEndTag(); // <cxxFunctionDeclaredType>
}
@@ -4825,7 +4830,7 @@ void DitaXmlGenerator::writeFunctions(const Section& s,
writeEndTag(); // </cxxFunctionReimplemented>
}
}
- writeParameters(fn);
+ writeParameters(fn,parent,marker);
writeLocation(fn);
writeEndTag(); // <cxxFunctionDefinition>
@@ -4846,10 +4851,51 @@ void DitaXmlGenerator::writeFunctions(const Section& s,
}
}
+static const QString typeTag("type");
+static const QChar charLangle = '<';
+static const QChar charAt = '@';
+
+/*!
+ This function replaces class and enum names with <apiRelation>
+ elements, i.e. links.
+ */
+void DitaXmlGenerator::replaceTypesWithLinks(const Node* n,
+ const InnerNode* parent,
+ CodeMarker* marker,
+ QString& src)
+{
+ QStringRef arg;
+ QStringRef par1;
+ int srcSize = src.size();
+ QString text;
+ for (int i=0; i<srcSize;) {
+ if (src.at(i) == charLangle && src.at(i+1) == charAt) {
+ if (!text.isEmpty()) {
+ writeCharacters(text);
+ text.clear();
+ }
+ i += 2;
+ if (parseArg(src, typeTag, &i, srcSize, &arg, &par1)) {
+ const Node* tn = marker->resolveTarget(arg.toString(), myTree, parent, n);
+ addLink(linkForNode(tn,parent),arg,DT_apiRelation);
+ }
+ }
+ else {
+ text += src.at(i++);
+ }
+ }
+ if (!text.isEmpty()) {
+ writeCharacters(text);
+ text.clear();
+ }
+}
+
/*!
This function writes the <cxxFunctionParameters> element.
*/
-void DitaXmlGenerator::writeParameters(const FunctionNode* fn)
+void DitaXmlGenerator::writeParameters(const FunctionNode* fn,
+ const InnerNode* parent,
+ CodeMarker* marker)
{
const QList<Parameter>& parameters = fn->parameters();
if (!parameters.isEmpty()) {
@@ -4858,7 +4904,9 @@ void DitaXmlGenerator::writeParameters(const FunctionNode* fn)
while (p != parameters.end()) {
writeStartTag(DT_cxxFunctionParameter);
writeStartTag(DT_cxxFunctionParameterDeclaredType);
- writeCharacters((*p).leftType());
+ QString src = marker->typified((*p).leftType());
+ replaceTypesWithLinks(fn,parent,marker,src);
+ //writeCharacters((*p).leftType());
if (!(*p).rightType().isEmpty())
writeCharacters((*p).rightType());
writeEndTag(); // <cxxFunctionParameterDeclaredType>
@@ -5664,29 +5712,29 @@ QString DitaXmlGenerator::metadataDefault(DitaTag t) const
\list
\o <audience> *
\o <author> *
- \o <brand>
+ \o <brand> not used
\o <category> *
\o <compomnent> *
\o <copyrholder> *
\o <copyright> *
- \o <created>
+ \o <created> not used
\o <copyryear> *
- \o <critdates>
- \o <keyword>
- \o <keywords>
+ \o <critdates> not used
+ \o <keyword> not used
+ \o <keywords> not used
\o <metadata> *
- \o <othermeta>
+ \o <othermeta> *
\o <permissions> *
- \o <platform>
+ \o <platform> not used
\o <prodinfo> *
\o <prodname> *
\o <prolog> *
\o <publisher> *
- \o <resourceid>
- \o <revised>
- \o <source>
- \o <tm>
- \o <unknown>
+ \o <resourceid> not used
+ \o <revised> not used
+ \o <source> not used
+ \o <tm> not used
+ \o <unknown> not used
\o <vrm> *
\o <vrmlist> *
\endlist
@@ -5695,7 +5743,7 @@ QString DitaXmlGenerator::metadataDefault(DitaTag t) const
*/
void
-DitaXmlGenerator::writeProlog(const InnerNode* inner, CodeMarker* marker)
+DitaXmlGenerator::writeProlog(const InnerNode* inner)
{
if (!inner)
return;
diff --git a/tools/qdoc3/ditaxmlgenerator.h b/tools/qdoc3/ditaxmlgenerator.h
index ffca234..0044eff 100644
--- a/tools/qdoc3/ditaxmlgenerator.h
+++ b/tools/qdoc3/ditaxmlgenerator.h
@@ -87,6 +87,7 @@ class DitaXmlGenerator : public PageGenerator
DT_apiDesc,
DT_APIMap,
DT_apiName,
+ DT_apiRelation,
DT_audience,
DT_author,
DT_b,
@@ -292,11 +293,15 @@ class DitaXmlGenerator : public PageGenerator
void writeDerivations(const ClassNode* cn, CodeMarker* marker);
void writeLocation(const Node* n);
void writeFunctions(const Section& s,
- const Node* n,
+ const InnerNode* parent,
CodeMarker* marker,
const QString& attribute = QString());
void writeNestedClasses(const Section& s, const Node* n);
- void writeParameters(const FunctionNode* fn);
+ void replaceTypesWithLinks(const Node* n,
+ const InnerNode* parent,
+ CodeMarker* marker,
+ QString& src);
+ void writeParameters(const FunctionNode* fn, const InnerNode* parent, CodeMarker* marker);
void writeEnumerations(const Section& s,
CodeMarker* marker,
const QString& attribute = QString());
@@ -315,7 +320,7 @@ class DitaXmlGenerator : public PageGenerator
void writePropertyParameter(const QString& tag, const NodeList& nlist);
void writeRelatedLinks(const FakeNode* fake, CodeMarker* marker);
void writeLink(const Node* node, const QString& tex, const QString& role);
- void writeProlog(const InnerNode* inner, CodeMarker* marker);
+ void writeProlog(const InnerNode* inner);
bool writeMetadataElement(const InnerNode* inner,
DitaXmlGenerator::DitaTag t,
bool force=true);
@@ -438,7 +443,7 @@ class DitaXmlGenerator : public PageGenerator
virtual void generateInnerNode(const InnerNode* node);
QXmlStreamWriter& xmlWriter();
void writeApiDesc(const Node* node, CodeMarker* marker, const QString& title);
- void addLink(const QString& href, const QStringRef& text);
+ void addLink(const QString& href, const QStringRef& text, DitaTag t = DT_xref);
void writeDitaMap();
void writeStartTag(DitaTag t);
void writeEndTag(DitaTag t=DT_NONE);
diff --git a/tools/qdoc3/doc/corefeatures.qdoc b/tools/qdoc3/doc/corefeatures.qdoc
new file mode 100644
index 0000000..ee579cf
--- /dev/null
+++ b/tools/qdoc3/doc/corefeatures.qdoc
@@ -0,0 +1,35 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page corefeatures.html
+ \title Core Features
+
+ \input examples/signalandslots.qdocinc
+ \input examples/objectmodel.qdocinc
+ \input examples/layoutmanagement.qdocinc
+*/
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 0e4055b..da0646e 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
@@ -3999,20 +4000,11 @@
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
- <h1>Core Features</h1>
- \endraw
-
- \input examples/signalandslots.qdocinc
- \input examples/objectmodel.qdocinc
- \input examples/layoutmanagement.qdocinc
- \endquotation
+ \l{layoutmanagement.qdocinc}. QDoc renders this page
+ \l{corefeatures.html} {as shown here}.
\target 2-argument-form}
- \section2 \\include filename snippet-identifier
+ \section2 \\include filename snippet-identifier \span {class="newStuff"} {(new)}
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
@@ -4046,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 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.
-
- \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.
+ 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.
- ...
- * /
- \endcode
+ 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:
- 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
- <head>
- ...
- <meta name="author" content="Summerfield" />
- ...
- </head>
- \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
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
+ <!--qwidget.cpp-->
+ <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
+ <apiName>QWidget</apiName>
+ <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
+ <prolog>
+ <author>Qt Development Frameworks</author>
+ <publisher>Nokia</publisher>
+ <copyright>
+ <copyryear year="2011"/>
+ <copyrholder>Nokia</copyrholder>
+ </copyright>
+ <permissions view="all"/>
+ <metadata>
+ <audience type="designer"/>
+ <audience type="programmer"/>
+ <audience type="user"/>
+ <category>Class reference</category>
+ <prodinfo>
+ <prodname>Qt Reference Documentation</prodname>
+ <vrmlist>
+ <vrm version="4" release="7" modification="3"/>
+ </vrmlist>
+ <component>QtGui</component>
+ </prodinfo>
+ <othermeta name="platform" content="MeeGo"/>
+ <othermeta name="platform" content="Symbian"/>
+ <othermeta name="platform" content="OS X 10.6"/>
+ <othermeta name="technology" content="User Interface"/>
+ </metadata>
+ </prolog>
+ \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
@@ -6932,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
@@ -6951,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 = "&aacute;"
+ macro.Aring.DITAXML = "&Aring;"
+ macro.aring.DITAXML = "&aring;"
+ macro.Auml.DITAXML = "&Auml;"
+ macro.br.DITAXML = " "
+ macro.BR.DITAXML = " "
+ macro.copyright.DITAXML = "&copy;"
+ macro.eacute.DITAXML = "&eacute;"
+ macro.hr.DITAXML = " "
+ macro.iacute.DITAXML = "&iacute;"
+ macro.oslash.DITAXML = "&oslash;"
+ macro.ouml.DITAXML = "&ouml;"
+ macro.raisedaster.DITAXML = "<sup>*</sup>"
+ macro.rarrow.DITAXML = "&rarr;"
+ macro.reg.DITAXML = "<sup>&reg;</sup>"
+ macro.uuml.DITAXML = "&uuml;"
+ macro.mdash.DITAXML = "&mdash;"
+ macro.emptyspan.DITAXML = " "
+ \endcode
+
+ You can also set default values for some of the tags in the DITA
+ \c {<prolog>} and \c {<metadata>} 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
@@ -6981,7 +7061,7 @@
information see the \l {Compatibility Issues} {compatibility
section}.
- See also \l {macro-command} {macro}.
+ See also \l {macro-variable} {macro}.
\target codeindent-variable
\section1 codeindent
@@ -7480,23 +7560,27 @@
\target macro-variable
\section1 macro
- The \c macro variable can be used to create your own QDoc
- commands.
+ The \c macro variable is used to create your own simple QDoc
+ commands. The syntax is \tt {macro.\e{command} = \e{definition}},
+ where the definition is written using QDoc syntax.
- The general syntax is \tt {macro.\e{command} =
- "\e{definition}}". The definition can be described using QDoc
- syntax. In addition it is possible to provide an HTML definition
- by appending .HTML to the variable.
-
- For example in \l qt.qdocconf:
+ A macro variable can be restricted for use in one type of output
+ generation. By appending \c {.HTML} to the macro name, for
+ example, the macro is only used when generating HTML output. By
+ appending \c {.DITAXML} to the macro name, the macro is only used
+ when generating DITA XML.
\code
macro.gui = "\\bold"
macro.raisedaster.HTML = "<sup>*</sup>"
\endcode
- makes sure that the \\gui command renders its argument using a
- bold font, and that \\raisedaster renders a '*'.
+ The first macro defines the \\gui command to render its argument
+ using a bold font. The second macro defines the \\raisedaster
+ command to render a superscript asterisk, but only when generating
+ HTML.
+
+ See also \l {alias-variable} {alias}.
\target naturallanguage-variable
\section1 naturallanguage
diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp
index 114db26..a6cf646 100644
--- a/tools/qdoc3/htmlgenerator.cpp
+++ b/tools/qdoc3/htmlgenerator.cpp
@@ -93,104 +93,6 @@ static QRegExp typeTag("(<@(type|headerfile|func)(?: +[^>]*)?>)(.*)(</@\\2>)");
static QRegExp spanTag("</@(?:comment|preprocessor|string|char|number|op|type|name|keyword)>");
static QRegExp unknownTag("</?@[^>]*>");
-bool parseArg(const QString &src,
- const QString &tag,
- int *pos,
- int n,
- QStringRef *contents,
- QStringRef *par1 = 0,
- bool debug = false)
-{
-#define SKIP_CHAR(c) \
- if (debug) \
- qDebug() << "looking for " << c << " at " << QString(src.data() + i, n - i); \
- if (i >= n || src[i] != c) { \
- if (debug) \
- qDebug() << " char '" << c << "' not found"; \
- return false; \
- } \
- ++i;
-
-
-#define SKIP_SPACE \
- while (i < n && src[i] == ' ') \
- ++i;
-
- int i = *pos;
- int j = i;
-
- // assume "<@" has been parsed outside
- //SKIP_CHAR('<');
- //SKIP_CHAR('@');
-
- if (tag != QStringRef(&src, i, tag.length())) {
- if (0 && debug)
- qDebug() << "tag " << tag << " not found at " << i;
- return false;
- }
-
- if (debug)
- qDebug() << "haystack:" << src << "needle:" << tag << "i:" <<i;
-
- // skip tag
- i += tag.length();
-
- // parse stuff like: linkTag("(<@link node=\"([^\"]+)\">).*(</@link>)");
- if (par1) {
- SKIP_SPACE;
- // read parameter name
- j = i;
- while (i < n && src[i].isLetter())
- ++i;
- if (src[i] == '=') {
- if (debug)
- qDebug() << "read parameter" << QString(src.data() + j, i - j);
- SKIP_CHAR('=');
- SKIP_CHAR('"');
- // skip parameter name
- j = i;
- while (i < n && src[i] != '"')
- ++i;
- *par1 = QStringRef(&src, j, i - j);
- SKIP_CHAR('"');
- SKIP_SPACE;
- } else {
- if (debug)
- qDebug() << "no optional parameter found";
- }
- }
- SKIP_SPACE;
- SKIP_CHAR('>');
-
- // find contents up to closing "</@tag>
- j = i;
- for (; true; ++i) {
- if (i + 4 + tag.length() > n)
- return false;
- if (src[i] != '<')
- continue;
- if (src[i + 1] != '/')
- continue;
- if (src[i + 2] != '@')
- continue;
- if (tag != QStringRef(&src, i + 3, tag.length()))
- continue;
- if (src[i + 3 + tag.length()] != '>')
- continue;
- break;
- }
-
- *contents = QStringRef(&src, j, i - j);
-
- i += tag.length() + 4;
-
- *pos = i;
- if (debug)
- qDebug() << " tag " << tag << " found: pos now: " << i;
- return true;
-#undef SKIP_CHAR
-}
-
static void addLink(const QString &linkTarget,
const QStringRef &nestedStuff,
QString *res)
@@ -1494,8 +1396,10 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker)
QString allQmlMembersLink = generateAllQmlMembersFile(qml_cn, marker);
if (!allQmlMembersLink.isEmpty()) {
+ out() << "<ul>\n";
out() << "<li><a href=\"" << allQmlMembersLink << "\">"
<< "List of all members, including inherited members</a></li>\n";
+ out() << "</ul>\n";
}
s = sections.begin();
@@ -2847,7 +2751,7 @@ QString HtmlGenerator::highlightedCode(const QString& markedCode,
static const QString headerTag("headerfile");
static const QString funcTag("func");
static const QString linkTag("link");
-
+
// replace all <@link> tags: "(<@link node=\"([^\"]+)\">).*(</@link>)"
bool done = false;
for (int i = 0, srcSize = src.size(); i < srcSize;) {
@@ -2882,6 +2786,7 @@ QString HtmlGenerator::highlightedCode(const QString& markedCode,
if (src.at(i) == charLangle && src.at(i + 1) == charAt) {
i += 2;
if (parseArg(src, funcTag, &i, srcSize, &arg, &par1)) {
+
const Node* n = marker->resolveTarget(par1.toString(),
myTree,
relative);
diff --git a/tools/qdoc3/pagegenerator.cpp b/tools/qdoc3/pagegenerator.cpp
index d5564f7..d331d41 100644
--- a/tools/qdoc3/pagegenerator.cpp
+++ b/tools/qdoc3/pagegenerator.cpp
@@ -70,12 +70,6 @@ PageGenerator::~PageGenerator()
endSubPage();
}
-static QRegExp linkTag("(<@link node=\"([^\"]+)\">).*(</@link>)");
-static QRegExp funcTag("(<@func target=\"([^\"]*)\">)(.*)(</@func>)");
-static QRegExp typeTag("(<@(type|headerfile|func)(?: +[^>]*)?>)(.*)(</@\\2>)");
-static QRegExp spanTag("</@(?:comment|preprocessor|string|char)>");
-static QRegExp unknownTag("</?@[^>]*>");
-
bool PageGenerator::parseArg(const QString& src,
const QString& tag,
int* pos,