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

QDoc: Support descriptive lists (<dl>, <dt>, <dd>) in output

    XMLWordPrintable

Details

    • Suggestion
    • Resolution: Unresolved
    • P2: Important
    • None
    • None
    • Build tools: qdoc

    Description

      QDoc currently does not support generating descriptive lists in its output (i.e., HTML <dl>, <dt>, <dd> structures), which are commonly used for term–description pairs such as command keywords and their explanations.

      This limitation has been noted in documentation reviews, where descriptive lists would provide more semantic clarity and improve formatting over simple bullet lists or inline text.

      Suggested Feature
      Introduce support for descriptive lists in QDoc, enabling documentation authors to mark up content that naturally fits the term–description pattern. For example:

      \startdesclist

      \term INCLUDE
      \desc Can be used to include files for import.

      \term DEFINE
      \desc Used to define macros and constants.

      \enddesclist

      Or alternatively, any other syntax that fits QDoc’s style and flexibility.

      Expected Output

      For HTML output, this would ideally generate:
      <dl>
      <dt>INCLUDE</dt>
      <dd>Can be used to include files for import.</dd>
      <dt>DEFINE</dt>
      <dd>Used to define macros and constants.</dd>
      </dl>

      For other supported formats:

      • DocBook: <variablelist>, <varlistentry>, <term>, <listitem>
      • WebXML: I don't know if we need it; if we do, perhaps include an appropriate representation preserving the term–description semantics, potentially using <term> and <description> tags or similar XML structure.

      Motivation

      • Improves semantic structure and accessibility of documentation.
      • Clarifies relationships between terms and their explanations.
      • Aligns with common documentation standards.
      • Reduces the need for ad hoc formatting or workarounds in QDoc comments.

      Attachments

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

        Activity

          People

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

            Dates

              Created:
              Updated:

              Gerrit Reviews

                There are no open Gerrit changes