Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-140096

QDoc: \page command with file extensions other than .html results in double extensions

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Unresolved
    • Icon: P3: Somewhat important P3: Somewhat important
    • None
    • 6.8.4, 6.9.2, 6.10, 6.11
    • Build tools: qdoc

      When using the \page command with file extensions other than .html (e.g., .htm, .xml, .txt, .pdf, .json), QDoc incorrectly generates output files with double extensions by preserving the original extension and appending .html. QDoc's file generation logic fails to recognize and remove the extension, resulting in malformed output filenames with double extensions.

      The issue is in src/qttools/src/qdoc/qdoc/src/qdoc/generator.cpp in the fileBase() function (lines 263-264):

      QString base{node->name()};
      if (base.endsWith(".html"))
          base.truncate(base.size() - 5);

      The code only checks for and removes .html extensions, but not other common extensions. When a page has a different extension, it gets treated as part of the base name, and then .html is appended, creating the double extension.

      Steps to Reproduce

      A test case demonstrating this issue already exists in:
      src/qttools/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/non_ascii_character_input/src/adventures_with_non_ascii_characters.qdoc (line 57).

      Expected Behavior

      QDoc should either:
      1. Respect the specified extension and generate files with the exact extension provided (e.g., `test.htm` generates `test.htm`)
      2. OR consistently replace any extension with `.html` (e.g., `test.htm` generates `test.html`)

      The current behavior of creating double extensions is clearly incorrect.

      Impact

      • Breaks expected file naming conventions
      • Can cause issues with links and references to generated documentation
      • Affects all file extensions except `.html`

      Suggested Fix

      The fileBase() function should be updated to handle all common file extensions, not just .html. A possible approach:

      QString base{node->name()};
      // Remove any known file extension
      static const QStringList extensions = {".html", ".htm", ".xml", ".txt", ".pdf", ".json"};
      for (const QString &ext : extensions) {
          if (base.endsWith(ext))

      Unknown macro: {         base.truncate(base.size() - ext.size());         break;     }

      }

      Or use a more generic approach with QFileInfo::completeBaseName().

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

            docinfrastructure Documentation Infrastructure Team
            paulwicking Paul Wicking
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Created:
              Updated:

                There are no open Gerrit changes