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

Consider the unification of the code commands

    XMLWordPrintable

Details

    • Task
    • Resolution: Unresolved
    • P2: Important
    • None
    • None
    • Build tools: qdoc
    • None
    • Da Vinci sprint 45, Da Vinci sprint 46, Da Vinci sprint 47

    Description

      QDoc currently has many ways to insert a block of code in its output.

      For inline code blocks specifically, that is code that is not extracted from a file that is different from the file the block of code is inserted in, we have, for example, code, badcode and qml.

      code and badcode specifically, divide the markup into code blocks that QDoc will treat specially (for example providing some syntax highlighting) and code blocks that will be just taken verbatim.

      This impose an overhead on the user, which must remember which kind of code can be put in each of the two bins.

      Furthermore, it creates friction when QDoc has to evolve.
      For example, if we have many appearances of, lets say, python code and decide to add special formatting for those blocks, as they were previously put in the badcode bin they will now need to be modified to a new command, be it `\code` or a custom command like `\python`.

      To avoid those kind of issues and to simplify the internal representation and external interface of QDoc, it is proposed to unify the inline code blocks command into a single block command that carries information about the kind of code QDoc is asked to present.

      Furthermore, this allows us to have a unified base for the expansion of QDoc code blocks capabilities, such as providing special support or customizable support for the treatment of code blocks.

      As an additional improvements, it removes the inconsistency of the `\badcode`-`\endcode` pair, where the closing commands does not respect the `end` + command-name form that most other block commands have.

      As an initial step, a new block command should be added to inspect the feasibility of transitioning to it without breaking the current QDoc interface.

      The proposed command pair, `\codeblock` and `\endcodeblock` has the following properties:

      • `\codeblock` has one, currently required, parameter: a tag representing the "language" of the content it encloses.
        The tag parameter is a sequence of one or more non-whitespace characters.
      • Anything between `\codeblock` and `\endcodeblock` is read verbatim during the parsing phase. This is equivalent to the treatment of `\code` and `\badcode`.
      • An `\endcodeblock` is required for each `\codeblock`.

      `\code` and `\badcode` currently support the use of optional parameters that can then be inserted into the content of the block. The main use for this seems to be the representation of QDoc closing delimiters inside the code block itself.

      This should be taken into account for the new commands pair, possibly mimicking the exact same behavior and interface that was used until now.

      The parsing of a codeblock commands pair should result in a single atom, `CodeBlock` that contains the tag that the user provided for the language, in string form, and a string representing the content between the two command, taken verbatim.

      This atom will later be processed by the various generator and should respect the current semantic of the `\code` and `\badcode` commands depending on the tag it bears.

      A system for the special processing of languages should be designed, trying to reuse the current infrastructure but not necessarily tying itself to it when it might create friction for future developments.

      When the experimental command reaches feature parity with the current commands, it should be reviewed and, depending on the feasibility of its usage and its current form, either be discarded, replace \code` or deprecate `\code` and `\badcode` in favour of it.

      Attachments

        Issue Links

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

          Activity

            People

              diseraluca Luca Di Sera
              diseraluca Luca Di Sera
              Votes:
              1 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

                Created:
                Updated:

                Gerrit Reviews

                  There are no open Gerrit changes