diff options
| -rw-r--r-- | doc/src/qthelp.qdoc | 95 | ||||
| -rw-r--r-- | tools/assistant/lib/qhelpgenerator.cpp | 94 |
2 files changed, 99 insertions, 90 deletions
diff --git a/doc/src/qthelp.qdoc b/doc/src/qthelp.qdoc index 05bf3e3..2182606 100644 --- a/doc/src/qthelp.qdoc +++ b/doc/src/qthelp.qdoc @@ -96,7 +96,7 @@ generation of the compressed help file. As already mentioned, the Qt compressed help file contains all - data, so there is no need any longer to ship all single html + data, so there is no need any longer to ship all single html files. Instead, only the compressed help file and optionally the collection file has to be distributed. The collection file is optional since any existing collection file, e.g. from an older @@ -211,7 +211,7 @@ \section2 Using QHelpEngine API Instead of showing the help in an external application like the - Qt Assistant, it is also possible to embed the online help in + Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the QHelpEngine class and can be displayed in nearly any form. Showing it in a QTextBrowser is probably the most common way, but @@ -238,7 +238,7 @@ Qt Commercial Edition licensees that wish to distribute applications that use these features of the QtHelp module need to be aware of their - obligations under the GNU Lesser General Public License (LGPL). + obligations under the GNU Lesser General Public License (LGPL). Developers using the Open Source Edition can choose to redistribute the module under the appropriate version of the GNU LGPL; version 2.1 @@ -269,23 +269,23 @@ /*! \page qthelpproject.html \title Qt Help Project - + A Qt help project collects all data necessary to generate a compressed help file. Along with the actual help data, like the table of contents, index keywords and help documents, it contains some extra information like a namespace to identify the help file. One help project stands for one documentation, e.g. the Qt Assistant manual. - + \section1 Qt Help Project File Format - + The file format is XML based. For a better understanding of the format we'll discuss the following example: - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7 - + \section2 Namespace - + To enable the QHelpEngine to retrieve the proper documentation to a given link, every documentation set has to have a unique identifier. A unique identifier makes is also possible for the @@ -293,10 +293,10 @@ on its file name. The Qt help system uses a namespace as identifier which is defined by the mandatory namespace tags. In the example above, the namespace is "mycompany.com.myapplication.1_0". - + \target Virtual Folders \section2 Virtual Folders - + Having a namespace for every documentation naturally means that the documentation sets are quite separated. From the help engines point of view this is beneficial, but from the documentors view @@ -304,84 +304,86 @@ manual to another without having to specify absolute links. To solve this problem, the help system introduced the concept of virtual folders. - + A virtual folder will become the root directory of all files referenced in a compressed help file. When two documentations share the same virtual folder, they can use relative paths when defining hyperlinks pointing to the other documentation. If a file is contained in both documentations or manuals, the one from the current manual has precedence over the other. - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8 - + The above example specifies 'doc' as virtual folder. If another manual, e.g. for a small helper tool for 'My Application' specifies the same folder, it is sufficient to write 'doc.html#section1' to reference the first section in the 'My Application' manual. - + The virtual folder tag is mandatory and the folder must not contain any '/'. - + \target Custom Filters \section2 Custom Filters - + Next in the Qt help project file are the optional definitions of - custom filters. A custom filter contains a list of filter + custom filters. A custom filter contains a list of filter attributes which will be used later to display only the documentation which has all those attributes assigned to. So, when setting the current filter in the QHelpEngine to "My Application 1.0" only the documentation which has "myapp" and "1.0" set as filter attributes will be shown. - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9 - + It is possible to define any number of custom filters in a help project file. Important to know is, that the filter attributes have not to be specified in the same project file; they can be defined in any other help file. The definition of a filter attributes takes place by specifying them in a filter section. - + \target Filter Section - \section2 Filter Section - + \section2 Filter Section + A filter section contains the actual documentation. One Qt help project file may contain more than one filter sections. Every filter section consists of four parts, the filter attributes section, the table of contents, the keywords and the files list. In theory all parts are optional but not specifying anything there will result in an empty documentation. - + \section3 Filter Attributes - + Every filter section should have filter attributes assigned to it, to enable documentation filtering. If no filter attribute is defined, the documentation will only be shown if no filtering occurs, meaning the current custom filter in the QHelpEngine does not contain any filter attributes. - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10 - + In this case, the filter attributes 'myapp' and '1.0' are assigned to the filter section, i.e. all contents specified in this section will only be shown if the current custom filter has 'myapp' or '1.0' or both as filter attributes. - + \section3 Table of contents - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 11 - + One section tag represents one item in the table of contents. The sections can be nested to any degree, but from a users perspective - it shouldn't be more than four or five levels. A section is defined - by its title and reference. The reference, like all file references - in a Qt help project file are relative to the help project file - itself. - + it should not be more than four or five levels. A section is defined + by its title and reference. The reference, like all file references in a Qt + help project, are relative to the help project file itself. + \note The referenced files must be inside the same directory (or within a + subdirectory) as the help project file. An absolute file path is not supported + either. + \section3 Keywords - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 12 - + The keyword section lists all keywords of this filter section. A keyword consists basically of a name and a file reference. If the attribute 'name' is used then the keyword specified there will appear in @@ -389,15 +391,18 @@ If 'id' is used, the keyword does not appear in the index and is only accessible via the linksForIdentifier() function of the QHelpEngineCore. 'name' and 'id' can be specified at the same time. - + \section3 Files - + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13 - + Finally, the actual documentation files have to be listed. Make sure - that all files neccessary to display the help are mentioned, i.e. - stylesheets or similar files need to be there as well. All listed files - will be compressed and written to the Qt compressed help file. So, in the - end, one single Qt help file contains all documentation files along with - the contents and indices. + that all files neccessary to display the help are mentioned, i.e. + stylesheets or similar files need to be there as well. The file, like all + file references in a Qt help project, are relative to the help project file + itself. All listed files will be compressed and written to the Qt compressed + help file. So, in the end, one single Qt help file contains all + documentation files along with the contents and indices. \note The + referenced files must be inside the same directory (or within a subdirectory) + as the help project file. An absolute file path is not supported either. */ diff --git a/tools/assistant/lib/qhelpgenerator.cpp b/tools/assistant/lib/qhelpgenerator.cpp index 03df3cc..8512adb 100644 --- a/tools/assistant/lib/qhelpgenerator.cpp +++ b/tools/assistant/lib/qhelpgenerator.cpp @@ -467,8 +467,9 @@ bool QHelpGenerator::insertFiles(const QStringList &files, const QString &rootPa emit statusChanged(tr("Insert files...")); QList<int> filterAtts; - foreach (QString filterAtt, filterAttributes) { - d->query->prepare(QLatin1String("SELECT Id FROM FilterAttributeTable WHERE Name=?")); + foreach (const QString &filterAtt, filterAttributes) { + d->query->prepare(QLatin1String("SELECT Id FROM FilterAttributeTable " + "WHERE Name=?")); d->query->bindValue(0, filterAtt); d->query->exec(); if (d->query->next()) @@ -482,76 +483,76 @@ bool QHelpGenerator::insertFiles(const QStringList &files, const QString &rootPa if (filterSetId < 0) return false; ++filterSetId; - foreach (int attId, filterAtts) { - d->query->prepare(QLatin1String("INSERT INTO FileAttributeSetTable VALUES(?, ?)")); + foreach (const int &attId, filterAtts) { + d->query->prepare(QLatin1String("INSERT INTO FileAttributeSetTable " + "VALUES(?, ?)")); d->query->bindValue(0, filterSetId); d->query->bindValue(1, attId); d->query->exec(); } - QString title; - QString charSet; - QMap<int, QSet<int> > tmpFileFilterMap; - QList<FileNameTableData> fileNameDataList; - QList<QByteArray> fileDataList; - int tableFileId = 1; d->query->exec(QLatin1String("SELECT MAX(Id) FROM FileDataTable")); if (d->query->next()) tableFileId = d->query->value(0).toInt() + 1; + QString title; + QString charSet; FileNameTableData fileNameData; + QList<QByteArray> fileDataList; + QMap<int, QSet<int> > tmpFileFilterMap; + QList<FileNameTableData> fileNameDataList; int i = 0; - foreach (QString file, files) { - QFileInfo fi(rootPath + QDir::separator() + file); + foreach (const QString &file, files) { + const QString fileName = QDir::cleanPath(file); + if (fileName.startsWith(QLatin1String("../"))) { + emit warning(tr("The referenced file %1 must be inside or within a " + "subdirectory of (%2). Skipping it.").arg(fileName).arg(rootPath)); + continue; + } + + QFile fi(rootPath + QDir::separator() + fileName); if (!fi.exists()) { emit warning(tr("The file %1 does not exist! Skipping it.") - .arg(fi.absoluteFilePath())); + .arg(QDir::cleanPath(rootPath + QDir::separator() + fileName))); continue; } - QFile f(fi.absoluteFilePath()); - if (!f.open(QIODevice::ReadOnly)) { + if (!fi.open(QIODevice::ReadOnly)) { emit warning(tr("Cannot open file %1! Skipping it.") - .arg(fi.absoluteFilePath())); + .arg(QDir::cleanPath(rootPath + QDir::separator() + fileName))); continue; } - title.clear(); - QByteArray data; - data = f.readAll(); - - if (fi.suffix() == QLatin1String("html") || fi.suffix() == QLatin1String("htm")) { - charSet = QHelpGlobal::charsetFromData(data); - QTextStream stream(&data); - stream.setCodec(QTextCodec::codecForName(charSet.toLatin1().constData())); - title = QHelpGlobal::documentTitle(stream.readAll()); + QByteArray data = fi.readAll(); + if (fileName.endsWith(QLatin1String(".html")) + || fileName.endsWith(QLatin1String(".htm"))) { + charSet = QHelpGlobal::charsetFromData(data); + QTextStream stream(&data); + stream.setCodec(QTextCodec::codecForName(charSet.toLatin1().constData())); + title = QHelpGlobal::documentTitle(stream.readAll()); } else { title = fi.fileName(); } - QString fName = QDir::cleanPath(file); - if (fName.startsWith(QLatin1String("./"))) - fName = fName.mid(2); - int fileId = -1; - if (!d->fileMap.contains(fName)) { + if (!d->fileMap.contains(fileName)) { fileDataList.append(qCompress(data)); - fileNameData.name = fName; + fileNameData.name = fileName; fileNameData.fileId = tableFileId; fileNameData.title = title; fileNameDataList.append(fileNameData); - d->fileMap.insert(fName, tableFileId); + d->fileMap.insert(fileName, tableFileId); d->fileFilterMap.insert(tableFileId, filterAtts.toSet()); tmpFileFilterMap.insert(tableFileId, filterAtts.toSet()); ++tableFileId; } else { - fileId = d->fileMap.value(fName); - foreach (int filter, filterAtts) { + fileId = d->fileMap.value(fileName); + foreach (const int &filter, filterAtts) { if (!d->fileFilterMap.value(fileId).contains(filter) && !tmpFileFilterMap.value(fileId).contains(filter)) { d->fileFilterMap[fileId].insert(filter); @@ -565,20 +566,22 @@ bool QHelpGenerator::insertFiles(const QStringList &files, const QString &rootPa d->query->exec(QLatin1String("BEGIN")); QMap<int, QSet<int> >::const_iterator it = tmpFileFilterMap.constBegin(); while (it != tmpFileFilterMap.constEnd()) { - QSet<int>::const_iterator i = it.value().constBegin(); - while (i != it.value().constEnd()) { - d->query->prepare(QLatin1String("INSERT INTO FileFilterTable VALUES(?, ?)")); - d->query->bindValue(0, *i); + QSet<int>::const_iterator si = it.value().constBegin(); + while (si != it.value().constEnd()) { + d->query->prepare(QLatin1String("INSERT INTO FileFilterTable " + "VALUES(?, ?)")); + d->query->bindValue(0, *si); d->query->bindValue(1, it.key()); d->query->exec(); - ++i; + ++si; } ++it; } QList<QByteArray>::const_iterator fileIt = fileDataList.constBegin(); while (fileIt != fileDataList.constEnd()) { - d->query->prepare(QLatin1String("INSERT INTO FileDataTable VALUES (Null, ?)")); + d->query->prepare(QLatin1String("INSERT INTO FileDataTable VALUES " + "(Null, ?)")); d->query->bindValue(0, *fileIt); d->query->exec(); ++fileIt; @@ -586,10 +589,11 @@ bool QHelpGenerator::insertFiles(const QStringList &files, const QString &rootPa addProgress(d->fileStep*20.0); } - QList<FileNameTableData>::const_iterator fileNameIt = fileNameDataList.constBegin(); + QList<FileNameTableData>::const_iterator fileNameIt = + fileNameDataList.constBegin(); while (fileNameIt != fileNameDataList.constEnd()) { - d->query->prepare(QLatin1String("INSERT INTO FileNameTable (FolderId, Name, FileId, Title) " - " VALUES (?, ?, ?, ?)")); + d->query->prepare(QLatin1String("INSERT INTO FileNameTable " + "(FolderId, Name, FileId, Title) VALUES (?, ?, ?, ?)")); d->query->bindValue(0, 1); d->query->bindValue(1, (*fileNameIt).name); d->query->bindValue(2, (*fileNameIt).fileId); @@ -609,8 +613,8 @@ bool QHelpGenerator::insertFiles(const QStringList &files, const QString &rootPa return false; } -bool QHelpGenerator::registerCustomFilter(const QString &filterName, const QStringList &filterAttribs, - bool forceUpdate) +bool QHelpGenerator::registerCustomFilter(const QString &filterName, + const QStringList &filterAttribs, bool forceUpdate) { if (!d->query) return false; |