Разметка текста

Команды форматирования текста указывают, как должен быть отображен текст.

\a (маркер параметра)

Команда \a сообщает QDoc, что следующее слово — это имя формального параметра.

Выдается предупреждение, если формальный параметр не документирован или написан неправильно, поэтому при документировании функции вы должны упомянуть каждый формальный параметр по имени в описании функции, предварительно указав команду \a. Имя параметра затем отображается курсивом.

/ *!
   Constructs a line edit containing the text
   \a contents. The \a parent parameter is sent
   to the QWidget constructor.
* /

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
{
   ...
}

QDoc отображает это как:

QLineEdit::QLineEdit ( const QString & contents, QWidget *parent )

Создает поле ввода, содержащее текст contents. Параметр parent передается конструктору QWidget.

Имя формального параметра может быть заключено в фигурные скобки, но это не обязательно.

\c (шрифт кода)

Команда \c используется для отображения имен переменных, имен определённых пользователем классов и ключевых слов C++ (например, int и for) шрифтом кода.

Команда отображает свой аргумент с помощью моноширинного шрифта. Например:

/ *!
  The \c AnalogClock class provides a clock widget with hour
  and minute hands that is automatically updated every
  few seconds.
* /

QDoc отображает это как:

Класс AnalogClock предоставляет виджет часов с часовой и минутной стрелками, которые автоматически обновляются каждые несколько секунд.

Если текст, который должен быть отображен шрифтом кода, содержит пробелы, заключите весь текст в фигурные скобки.

\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

QDoc отображает это как:

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)

Команда \c принимает специальный символ \ в своём аргументе, который отображается как обычный символ. Таким образом, если вы хотите использовать вложенные команды, вам необходимо использовать команду телетипа (\tt) вместо этого.

См. также \tt и \code.

\div

Команды \div и \enddiv разделяют большой или малый блок текста (который может включать другие команды QDoc), к которому должны быть применены специальные атрибуты форматирования.

Аргумент должен быть предоставлен в фигурных скобках, как показано в комментарии qdoc ниже. Аргумент не интерпретируется, а используется в качестве атрибута(ов) тега, который выводит qdoc.

Например, мы можем захотеть отобразить встроенное изображение, чтобы оно плавало справа от текущего блока текста:

/ *!
   \div {class="float-right"}
     \inlineimage qml-column.png
   \enddiv

* /

Если qdoc генерирует HTML, он переведёт эти команды в:

<div class="float-right"><p><img src="images/qml-column.png" /></p></div>

Для HTML, значение атрибута float-right затем будет относиться к фрагменту в файле style.css, который в данном случае может быть:

div.float-right
{
   float: right; margin-left: 2em
}

Если qdoc генерирует DITA XML, он переведёт команды в:

<sectiondiv outputclass="float-right">
    <p>
        <fig>
            <image href="images/qml-column.png" placement="inline"/>
        </fig>
    </p>
</sectiondiv>

Затем ваша программа публикации DITA XML должна распознать значение атрибута outputclass.

Примечание: Обратите внимание, что команда \div может быть вложена.

Ниже приведен пример, взятый из файла index.qdoc, используемого для генерации index.html для Qt 4.7:

\div {class="indexbox guide"}
    \div {class="heading"}
        Qt Developer Guide
\enddiv
    \div {class="indexboxcont indexboxbar"}
        \div {class="section indexIcon"} \emptyspan
        \enddiv
        \div {class="section"}
            Qt is a cross-platform application and UI
            framework. Using Qt, you can write web-enabled
            applications once and deploy them across desktop,
            mobile and embedded operating systems without
            rewriting the source code.
        \enddiv
        \div {class="section sectionlist"}
            \list
               \li \l{Getting Started}
               \li \l{Installation} {Installation}
               \li \l{how-to-learn-qt.html} {How to learn Qt}
               \li \l{tutorials.html} {Tutorials}
               \li \l{Qt Examples} {Examples}
               \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
            \endlist
        \enddiv
    \enddiv
\enddiv

Когда все значения атрибута класса определены так же, как и в файле style.css, используемом для рендеринга документации Qt, указанный выше пример отображается как:

При генерации DITA XML qdoc выводит вложенные команды div как:

<sectiondiv outputclass="indexbox guide">
    <sectiondiv outputclass="heading">
        <p>Qt Developer Guide</p>
    </sectiondiv>
    <sectiondiv outputclass="indexboxcont indexboxbar">
        <sectiondiv outputclass="section indexIcon"/>
        <sectiondiv outputclass="section">
            <p>Qt is a cross-platform application and UI
               framework. Using Qt, you can write
               web-enabled applications once and deploy
               them across desktop, mobile and embedded
               operating systems without rewriting the
               source code.
            </p>
        </sectiondiv>
        <sectiondiv outputclass="section sectionlist">
            <ul>
                <li>
                    <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref>
                </li>
                <li>
                    <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref>
                </li>
                <li>
                    <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref>
                </li>
                <li>
                    <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref>
                </li>
                <li>
                    <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref>
                </li>
                <li>
                    <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref>
                </li>
            </ul>
        </sectiondiv>
    </sectiondiv>
</sectiondiv>

Ваша программа публикации DITA XML должна распознать значения атрибута outputclass.

См. также \span.

\span

Команда \span применяет специальное форматирование к небольшому блоку текста.

Необходимо предоставить два аргумента, каждый в фигурных скобках, как показано в комментарии QDoc ниже. Первый аргумент не интерпретируется, но указывает атрибут(ы) форматирования тега, выводимого QDoc. Второй аргумент — это текст, который будет отображен со специальными атрибутами форматирования.

Например, мы можем захотеть отобразить первое слово каждого элемента в числовом списке синим цветом.

/ *!
    Global variables with complex types:
\list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
* /

Класс variableName относится к фрагменту в вашем файле style.css.

.variableName
{
    font-family: courier;
color: blue
}

Используя классы variableName, показанные выше, пример отображается как:

Глобальные переменные со сложными типами:

1. mutableComplex1 в globals.cpp на строке 14
2. mutableComplex2 в globals.cpp на строке 15
3. constComplex1 в globals.cpp на строке 16
4. constComplex2 в globals.cpp на строке 17

Примечание: Команда span не приводит к началу нового абзаца.

См. также \div.

\tt (шрифт телетипа)

Команда \tt отображает свой аргумент моноширинным шрифтом. Эта команда ведет себя так же, как команда \c, за исключением того, что \tt позволяет вам вкладывать команды QDoc в аргумент (например, \e, \b и \underline).

/ *!
    After having populated the main container with
    child widgets, \c setupUi() scans the main container's list of
    slots for names with the form
    \tt{on_\e{objectName}_\e{signalName}().}
* /

QDoc отображает это как:

После заполнения основного контейнера дочерними виджетами, setupUi() сканирует список слотов основного контейнера на предмет имён с формой on_objectName_signalName().

Если текст, который должен быть отображен шрифтом кода, содержит пробелы, заключите весь текст в фигурные скобки.

\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

QDoc отображает это как:

QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)

См. также \c.

\b

Команда \b отображает свой аргумент жирным шрифтом. Эта команда раньше называлась \bold.

/ *!
    This is regular text; \b {this text is
    rendered using the \\b command}.
* /

QDoc отображает это как:

Это обычный текст; этот текст отображается с помощью команды \b.

\e (выделение, курсив)

Команда \e отображает свой аргумент особым шрифтом, обычно курсивом. Эта команда раньше называлась \i, которая сейчас устарела.

Если аргумент содержит пробелы или другие знаки препинания, заключите аргумент в фигурные скобки.

/ *!
    Here, we render \e {a few words} in italics.
* /

QDoc отображает это как:

Здесь мы отображаем несколько слов курсивом.

Если вы хотите использовать другие команды QDoc внутри аргумента, содержащего пробелы, вам всегда нужно заключить аргумент в скобки. Но QDoc достаточно умён, чтобы подсчитывать скобки [3], поэтому вам не нужны скобки в таких случаях:

/ *!
    An argument can sometimes contain whitespaces,
    for example: \e QPushButton(tr("A Brand New Button"))
* /

QDoc отображает это как:

Аргумент иногда может содержать пробелы, например: QPushButton(tr("Новая кнопка"))

Наконец, знаки препинания в конце не включаются в аргумент [4], также как и "'s" [5]

\sub

Команда \sub отображает свой аргумент ниже базовой линии обычного текста, используя меньший шрифт.

/ *!
    Definition (Range): Consider the sequence
    {x\sub n}\sub {n > 1} . The set

    {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}

    is called the range of the sequence.
* /

QDoc отображает это как:

Определение (Диапазон): Рассмотрим последовательность {x_n}_{n > 1} . Множество

{x₂, x₃, x₄, ...} = {x_n ; n = 2, 3, 4, ...}

называется диапазоном последовательности.

Если аргумент содержит пробелы или другие знаки препинания, заключите аргумент в фигурные скобки.

\sup

Команда \sup отображает свой аргумент выше базовой линии обычного текста, используя меньший шрифт.

/ *!
    The series

    1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...

    is called the \i {geometric series}.
* /

QDoc отображает это как:

Ряд

1 + a + a² + a³ + a⁴ + ...

называется геометрической прогрессией.

Если аргумент содержит пробелы или другие знаки препинания, заключите аргумент в фигурные скобки.

\uicontrol

Команда \uicontrol используется для маркировки контента как используемого для элементов управления UI. При использовании HTML выход отображается жирным шрифтом. При использовании DITA XML содержимое заключается в теге uicontrol.

\underline

Команда \underline отображает свой аргумент подчеркнутым.

/ *!
    The \underline {F}ile menu gives the users the possibility
    to edit an existing file, or save a new or modified
    file, and exit the application.
* /

QDoc отображает это как:

Меню Файл предоставляет пользователям возможность редактировать существующий файл, сохранять новый или изменённый файл и завершать работу приложения.

Если аргумент содержит пробелы или другие знаки препинания, заключите аргумент в фигурные скобки.

\\ (двойной обратный слэш)

Команда \\ расширяется до двойного обратного слэша.

Команды QDoc всегда начинаются с одного обратного слэша. Чтобы отобразить одиночный обратный слэш в тексте, необходимо ввести два обратных слэша. Если вы хотите отобразить два обратных слэша, вам нужно ввести четыре.

/ *!
    The \\\\ command is useful if you want a
    backslash to appear verbatim, for example,
    writing C:\\windows\\home\\.
* /

QDoc отображает это как:

Команда \\ полезна, если вы хотите, чтобы обратный слэш отображался буквально, например, при записи C:\windows\home\.

Однако, если вы хотите, чтобы ваш текст отображался также моноширинным шрифтом, вы можете использовать команду \c вместо этого, которая принимает и отображает обратный слэш как любой другой символ. Например:

/ *!
    The \\c command is useful if you want a
    backslash to appear verbatim, and the word
    that contains it written in a monospace font,
    like this: \c {C:\windows\home\}.
* /

QDoc отображает это как:

Команда \c полезна, если вы хотите, чтобы обратный слэш отображался буквально, а слово, содержащее его, отображалось моноширинным шрифтом, например: C:\windows\home\.

См. также \b.