Форматирование текста

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

\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.