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

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

\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 используется для маркировки содержимого как используемого для элементов управления пользовательским интерфейсом. При использовании 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.