qdoc: Introduce codeprefix & codesuffix, re-introduce codeindent

In order to provide acceptable results for styling the documentation
for rendering using QTextBrowser (instead of a full browser engine),
QDoc needs flexibility in adjusting the generated HTML.

This commit introduces and documents codeprefix and codesuffix
variables for qdocconf, and re-introduces the once-removed
support for codeindent.

The default codeindent value is reset to 0. These changes have no
effect to the generated output unless the above variables are
defined.

Change-Id: I6eb40dc0700725622e5a525ef19b5626b3b2b6a5
Reviewed-by: Martin Smith <martin.smith@digia.com>

src/tools/qdoc/config.cpp

@@ -53,6 +53,8 @@ QString ConfigStrings::BASE = QStringLiteral("base");
 QString ConfigStrings::BASEDIR = QStringLiteral("basedir");
 QString ConfigStrings::BUILDVERSION = QStringLiteral("buildversion");
 QString ConfigStrings::CODEINDENT = QStringLiteral("codeindent");
+QString ConfigStrings::CODEPREFIX = QStringLiteral("codeprefix");
+QString ConfigStrings::CODESUFFIX = QStringLiteral("codesuffix");
 QString ConfigStrings::CPPCLASSESPAGE = QStringLiteral("cppclassespage");
 QString ConfigStrings::DEFINES = QStringLiteral("defines");
 QString ConfigStrings::DEPENDS = QStringLiteral("depends");

src/tools/qdoc/config.h

@@ -165,6 +165,8 @@ struct ConfigStrings
     static QString BASEDIR;
     static QString BUILDVERSION;
     static QString CODEINDENT;
+    static QString CODEPREFIX;
+    static QString CODESUFFIX;
     static QString CPPCLASSESPAGE;
     static QString DEFINES;
     static QString DEPENDS;
@@ -241,6 +243,8 @@ struct ConfigStrings
 #define CONFIG_BASEDIR ConfigStrings::BASEDIR
 #define CONFIG_BUILDVERSION ConfigStrings::BUILDVERSION
 #define CONFIG_CODEINDENT ConfigStrings::CODEINDENT
+#define CONFIG_CODEPREFIX ConfigStrings::CODEPREFIX
+#define CONFIG_CODESUFFIX ConfigStrings::CODESUFFIX
 #define CONFIG_CPPCLASSESPAGE ConfigStrings::CPPCLASSESPAGE
 #define CONFIG_DEFINES ConfigStrings::DEFINES
 #define CONFIG_DEPENDS ConfigStrings::DEPENDS

src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc

@@ -185,6 +185,13 @@
     to adjust the appearance of certain types of HTML elements, this
     level of indentation is not always required.
 
+    \target codeprefix-variable
+    \target codesuffix-variable
+    \section1 codeprefix, codesuffix
+
+    The \c codeprefix and \c codesuffix variables specify a pair of
+    strings that each code snippet is enclosed in.
+
     \target defines-variable
     \section1 defines
 

src/tools/qdoc/generator.cpp

@@ -2115,11 +2115,14 @@ void Generator::terminateGenerator()
   Trims trailing whitespace off the \a string and returns
   the trimmed string.
  */
-QString Generator::trimmedTrailing(const QString& string)
+QString Generator::trimmedTrailing(const QString& string, const QString &prefix, const QString &suffix)
 {
     QString trimmed = string;
     while (trimmed.length() > 0 && trimmed[trimmed.length() - 1].isSpace())
         trimmed.truncate(trimmed.length() - 1);
+
+    trimmed.append(suffix);
+    trimmed.prepend(prefix);
     return trimmed;
 }
 

src/tools/qdoc/generator.h

@@ -139,7 +139,9 @@ protected:
     static QString outputSuffix(const Node* node);
     static void singularPlural(Text& text, const NodeList& nodes);
     static void supplementAlsoList(const Node *node, QList<Text> &alsoList);
-    static QString trimmedTrailing(const QString &string);
+    static QString trimmedTrailing(const QString &string,
+                                   const QString &prefix,
+                                   const QString &suffix);
     static QString sinceTitles[];
 
     void initializeTextOutput();

src/tools/qdoc/htmlgenerator.cpp

@@ -220,8 +220,9 @@ void HtmlGenerator::initializeGenerator(const Config &config)
         ++edition;
     }
 
-    // The following line was changed to fix QTBUG-27798
-    //codeIndent = config.getInt(CONFIG_CODEINDENT);
+    codeIndent = config.getInt(CONFIG_CODEINDENT); // QTBUG-27798
+    codePrefix = config.getString(CONFIG_CODEPREFIX);
+    codeSuffix = config.getString(CONFIG_CODESUFFIX);
 
     /*
       The help file write should be allocated once and only once
@@ -584,23 +585,23 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
         break;
     case Atom::Code:
         out() << "<pre class=\"cpp\">"
-              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative))
+              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative), codePrefix, codeSuffix)
               << "</pre>\n";
         break;
     case Atom::Qml:
         out() << "<pre class=\"qml\">"
-              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative))
+              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative), codePrefix, codeSuffix)
               << "</pre>\n";
         break;
     case Atom::JavaScript:
         out() << "<pre class=\"js\">"
-              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative))
+              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative), codePrefix, codeSuffix)
               << "</pre>\n";
         break;
     case Atom::CodeNew:
         out() << "<p>you can rewrite it as</p>\n"
               << "<pre class=\"cpp\">"
-              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative))
+              << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()),relative), codePrefix, codeSuffix)
               << "</pre>\n";
         break;
     case Atom::CodeOld:
@@ -608,7 +609,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
         // fallthrough
     case Atom::CodeBad:
         out() << "<pre class=\"cpp\">"
-              << trimmedTrailing(protectEnc(plainCode(indent(codeIndent,atom->string()))))
+              << trimmedTrailing(protectEnc(plainCode(indent(codeIndent,atom->string()))), codePrefix, codeSuffix)
               << "</pre>\n";
         break;
     case Atom::DivLeft:
@@ -2370,7 +2371,7 @@ void HtmlGenerator::generateIncludes(const Aggregate *inner, CodeMarker *marker)
         out() << "<pre class=\"cpp\">"
               << trimmedTrailing(highlightedCode(indent(codeIndent,
                                                         marker->markedUpIncludes(inner->includes())),
-                                                 inner))
+                                                 inner), codePrefix, codeSuffix)
               << "</pre>";
     }
 }

src/tools/qdoc/htmlgenerator.h

@@ -233,6 +233,8 @@ private:
 
     QHash<QString, QString> refMap;
     int codeIndent;
+    QString codePrefix;
+    QString codeSuffix;
     HelpProjectWriter *helpProjectWriter;
     bool inObsoleteLink;
     QRegExp funcLeftParen;

src/tools/qdoc/main.cpp

@@ -729,7 +729,7 @@ int main(int argc, char **argv)
         Location::startLoggingProgress();
 
     /*
-      The default indent for code is 4.
+      The default indent for code is 0.
       The default value for false is 0.
       The default supported file extensions are cpp, h, qdoc and qml.
       The default language is c++.
@@ -738,7 +738,7 @@ int main(int argc, char **argv)
       And those are all the default values for configuration variables.
      */
     if (defaults.isEmpty()) {
-        defaults.insert(CONFIG_CODEINDENT, QLatin1String("4"));
+        defaults.insert(CONFIG_CODEINDENT, QLatin1String("0"));
         defaults.insert(CONFIG_FALSEHOODS, QLatin1String("0"));
         defaults.insert(CONFIG_FILEEXTENSIONS, QLatin1String("*.cpp *.h *.qdoc *.qml"));
         defaults.insert(CONFIG_LANGUAGE, QLatin1String("Cpp"));