From 131f429e43a5c382ae208af39bc5f889c39dee8b Mon Sep 17 00:00:00 2001
From: Martin Smith <martin.smith@nokia.com>
Date: Fri, 1 Apr 2011 13:03:52 +0200
Subject: qdoc: modified \include to take a 2nd arg, snippet id.

---
 tools/qdoc3/doc.cpp              | 67 ++++++++++++++++++++++++++++----
 tools/qdoc3/doc/qdoc-manual.qdoc | 84 ++++++++++++++++++++++++++++------------
 tools/qdoc3/quoter.cpp           |  3 +-
 tools/qdoc3/quoter.h             |  2 +
 4 files changed, 123 insertions(+), 33 deletions(-)

diff --git a/tools/qdoc3/doc.cpp b/tools/qdoc3/doc.cpp
index 945b765..66acacf 100644
--- a/tools/qdoc3/doc.cpp
+++ b/tools/qdoc3/doc.cpp
@@ -360,7 +360,7 @@ class DocParser
     void checkExpiry(const QString& date);
     void insertBaseName(const QString &baseName);
     void insertTarget(const QString& target, bool keyword);
-    void include(const QString& fileName);
+    void include(const QString& fileName, const QString& identifier);
     void startFormat(const QString& format, int cmd);
     bool openCommand(int cmd);
     bool closeCommand(int endCmd);
@@ -804,7 +804,11 @@ void DocParser::parse(const QString& source,
                         append(Atom::ImageText, getRestOfLine());
                         break;
                     case CMD_INCLUDE:
-                        include(getArgument());
+                        {
+                            QString fileName = getArgument();
+                            QString identifier = getRestOfLine();
+                            include(fileName, identifier);
+                        }
                         break;
                     case CMD_INLINEIMAGE:
                         enterPara();
@@ -1578,7 +1582,7 @@ void DocParser::insertTarget(const QString &target, bool keyword)
     }
 }
 
-void DocParser::include(const QString& fileName)
+void DocParser::include(const QString& fileName, const QString& identifier)
 {
     if (location().depth() > 16)
         location().fatal(tr("Too many nested '\\%1's")
@@ -1592,12 +1596,12 @@ void DocParser::include(const QString& fileName)
                                         fileName,
                                         userFriendlyFilePath);
     if (filePath.isEmpty()) {
-        location().warning(tr("Cannot find leaf file '%1'").arg(fileName));
+        location().warning(tr("Cannot find qdoc include file '%1'").arg(fileName));
     }
     else {
         QFile inFile(filePath);
         if (!inFile.open(QFile::ReadOnly)) {
-            location().warning(tr("Cannot open leaf file '%1'")
+            location().warning(tr("Cannot open qdoc include file '%1'")
                                 .arg(userFriendlyFilePath));
         }
         else {
@@ -1607,9 +1611,56 @@ void DocParser::include(const QString& fileName)
             QString includedStuff = inStream.readAll();
             inFile.close();
 
-            in.insert(pos, includedStuff);
-            len = in.length();
-            openedInputs.push(pos + includedStuff.length());
+            if (identifier.isEmpty()) {
+                in.insert(pos, includedStuff);
+                len = in.length();
+                openedInputs.push(pos + includedStuff.length());
+            }
+            else {
+                QStringList lineBuffer = includedStuff.split(QLatin1Char('\n'));
+                int i = 0;
+                int startLine = -1;
+                while (i < lineBuffer.size()) {
+                    if (lineBuffer[i].startsWith("//!")) {
+                        if (lineBuffer[i].contains(identifier)) {
+                            startLine = i+1;
+                            break;
+                        }
+                    }
+                    ++i;
+                }
+                if (startLine < 0) {
+                    location().warning(tr("Cannot find '%1' in '%2'")
+                                       .arg(identifier)
+                                       .arg(userFriendlyFilePath));
+                    return;
+                    
+                }
+                QString result;
+                i = startLine;
+                do {
+                    if (lineBuffer[i].startsWith("//!")) {
+                        if (i<lineBuffer.size()) {
+                            if (lineBuffer[i].contains(identifier)) {
+                                break;
+                            }
+                        }
+                    }
+                    else
+                        result += lineBuffer[i] + "\n";
+                    ++i;
+                } while (i < lineBuffer.size());
+                if (result.isEmpty()) {
+                    location().warning(tr("Empty qdoc snippet '%1' in '%2'")
+                                       .arg(identifier)
+                                       .arg(userFriendlyFilePath));
+                }
+                else {
+                    in.insert(pos, result);
+                    len = in.length();
+                    openedInputs.push(pos + result.length());
+                }
+            }
         }
     }
 }
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
index 49dd819..0e4055b 100644
--- a/tools/qdoc3/doc/qdoc-manual.qdoc
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -259,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}
@@ -1437,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}.
 
@@ -3965,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
             / *!
@@ -3995,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
@@ -4007,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 
diff --git a/tools/qdoc3/quoter.cpp b/tools/qdoc3/quoter.cpp
index dadf67c..d9210e3 100644
--- a/tools/qdoc3/quoter.cpp
+++ b/tools/qdoc3/quoter.cpp
@@ -41,6 +41,7 @@
 
 #include <qfileinfo.h>
 #include <qregexp.h>
+#include <qdebug.h>
 
 #include "quoter.h"
 
@@ -65,7 +66,7 @@ static void replaceMultipleNewlines(QString &s)
 }
 
 // This is equivalent to  line.split( QRegExp("\n(?!\n|$)") ) but much faster
-static QStringList splitLines(const QString &line)
+QStringList Quoter::splitLines(const QString &line)
 {
     QStringList result;
     int i = line.size();
diff --git a/tools/qdoc3/quoter.h b/tools/qdoc3/quoter.h
index 6a59ab4..ee515b2 100644
--- a/tools/qdoc3/quoter.h
+++ b/tools/qdoc3/quoter.h
@@ -69,6 +69,8 @@ public:
 			const QString& pattern );
     QString quoteSnippet(const Location &docLocation, const QString &identifier);
 
+    static QStringList splitLines(const QString &line);
+
 private:
     QString getLine(int unindent = 0);
     void failedAtEnd( const Location& docLocation, const QString& command );
-- 
cgit v0.12