外部コードのインクルード

以下のコマンドを使うと、外部ファイルのコード・スニペットをインクルードできます。QDocにファイルの全内容をインクルードさせることもできますし、ファイルの特定の部分を引用して他をスキップすることもできます。後者の典型的な使い方は、ファイルをチャンクごとに引用することです。

\quotefile

\quotefile コマンドは、引数として与えられたファイルの完全な内容に展開します。

コマンドは行の残りを引数の一部とみなしますので、ファイル名の後に改行を入れるようにしてください。

ファイルの内容は、等幅フォントと標準的なインデントを使用して、独立した段落で表示される。コードはそのまま表示される。

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

バージョン6.11からは、\quotefile コマンドと同じ行に、大文字小文字を区別しないオプションの引数として言語を指定できるようになりました。これは \codeコマンドと同じように引用テキストに影響します。

例えば

\quotefile [text] examples/main.cpp

これはQDocにマークアップする機能がないソースコードを含むファイルから引用するときに便利です。

また \quotefromfileおよび \code.

\quotefromfile

\quotefromfile コマンドは、引数として与えられたファイルを引用のために開く。

コマンドは行の残りの部分を引数の一部と見なすので、ファイル名の後に改行を入れるようにしてください。

このコマンドは、ウォークスルーコマンドでファイルの一部を引用するときに使用することを意図しています： \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil.これにより、ファイルの特定の部分を引用することができる。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDocはどのファイルから引用しているかと、そのファイルの現在の位置を記憶しています（詳しくは \printlineを参照)。ファイルを「閉じる」必要はありません。

バージョン6.11から、\quotefromfile コマンドと同じ行で、大文字小文字を区別しないオプションの引数として言語を指定できるようになりました。これは \codeコマンドと同じように引用テキストに影響を与えます。

例えば

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDocはまた、どのコード言語から引用しているかを記憶しているので、次のようなコマンドが使えます。 \printline, \printtoや \printuntilなどのコマンドは現在のファイルから引用し、新しいファイルが読み込まれるまで一貫したスタイルのマークアップを適用します。

参照 \quotefile, \codeおよび \dots.

\printline

\printline コマンドは現在の位置からその行に展開する。

ドキュメントがソース・ファイルと同期していることを保証するために、行の部分文字列をコマンドの引数として指定する必要があります。コマンドは行の残りの部分を引数の一部と見なすので、部分文字列の後には必ず改行を入れてください。

ソース・ファイルからの行は、等幅フォントと標準的なインデントを使用して、独立した段落として表示されます。コードはそのまま表示される。

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDocはファイルを順次読み込みます。現在の位置を前に移動するには、\skip... コマンドのどちらかを使うことができます。現在の位置を後方に移動するには、もう一度 \quotefromfileコマンドを使ってください。

引数の部分文字列がスラッシュで囲まれている場合は、regular expression として解釈されます。

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(完全な例ファイル...)

/^\}/という正規表現は、QDocに行頭の最初の'}'文字までインデントなしで印刷させます。/.../は正規表現を囲み、'^'は行頭を意味します。'}'文字は正規表現の特殊文字なのでエスケープする必要があります。

QDocは指定された部分文字列や正規表現が見つからない場合、つまりソースコードが変更された場合に警告を発します。

また \printtoおよび \printuntil.

\printto

\printto コマンドは、現在の位置から、指定した部分文字列を含む次の行を除くすべての行に展開する。

コマンドはその行の残りの部分を引数の一部とみなすので、部分文字列の後には必ず改行を入れること。このコマンドは、位置と 引数についても\printlineコマンドと同じ規則に従います。

ソース・ファイルの行は、等幅フォントと標準的なインデントを使用して、独立した段落で表示されます。コードはそのまま表示される。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

また \printlineおよび \printuntil.

\printuntil

\printuntil コマンドは、現在の位置から、指定した部分文字列を含む次の行までのすべての行に展開する。

コマンドはその行の残りの部分を引数の一部とみなすので、部分文字列の後には必ず改行を入れること。このコマンドは、位置と 引数についても\printlineコマンドと同じ規則に従います。

引数なしで\printuntil を使用すると、現在の位置から引用符で囲まれたファイルの終わりまでのすべての行に展開されます。

ソース・ファイルの行は、等幅フォントと標準的なインデントを使用して、独立した段落で表示される。コードはそのまま表示されます。

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

また \printlineおよび \printto.

\skipline

\skipline コマンドは、現在のソース・ファイルの次の空白でない行を無視する。

Doc はファイルを順次読み込み、\skipline コマンドは現在の位置を移動する（ソース・ファイルの行を省略する）ために使用される。上記のファイルの位置に関する記述を参照のこと。

コマンドは行の残りを引数の一部とみなすので、部分文字列の後には必ず改行を入れる。コマンドと同じ引数の規則に従います。 \printlineコマンドと併用されます。 \quotefromfileコマンドと併用されます。

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

以下も参照のこと。 \skipto, \skipuntilおよび \dots.

\skipto

\skipto コマンドは、現在の位置から、指定した部分文字列を含む次の行を除くすべての行を無視する。

QDocはファイルを順次読み込み、\skipto コマンドは現在の位置を移動する（ソース・ファイルの1行または数行を省略する）ために使われる。上記のファイルの位置に関する記述を参照のこと。

このコマンドは残りの行を引数の一部とみなしますので、必ず部分文字列の後に改行を入れてください。

コマンドと同じ引数の規則に従います。 \printlineコマンドと併用されます。 \quotefromfileコマンドと併用される。

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

以下も参照のこと。 \skipline, \skipuntilおよび \dots.

\skipuntil

\skipuntil コマンドは、現在の位置から、指定した部分文字列を含む次の行までのすべての行を無視する。

QDocはファイルを順次読み込み、\skipuntil コマンドは現在の位置を移動する（ソース・ファイルの1行または数行を省略する）ために使われる。上記のファイルの位置に関する記述を参照のこと。

このコマンドは残りの行を引数の一部とみなしますので、必ず部分文字列の後に改行を入れてください。

コマンドと同じ引数の規則に従います。 \printlineコマンドと併用されます。 \quotefromfileコマンドと併用される。

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

以下も参照のこと。 \skipline, \skiptoおよび \dots.

\dots

\dots コマンドは、ファイルを引用する際にソース・ファイルの一部が省略されていることを示す。

このコマンドは \quotefromfileコマンドと併用される。ドットは改行され、等幅フォントが使用される。

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

デフォルトのインデントは4スペースだが、コマンドのオプション引数で調整できる。

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

以下も参照のこと。 \skipline, \skiptoおよび \skipuntil.

\snippet

\snippet コマンドは、コード・スニペットを整形済みテキストとして逐語的にインクルードし、シンタックス・ハイライトすることができる。

各コード・スニペットは、それを保持するファイルと、そのファイルの一意な識別子によって参照されます。スニペット・ファイルは通常、ドキュメント・ディレクトリ内のsnippets ディレクトリに保存されます（例えば、$QTDIR/doc/src/snippets ）。

例えば、以下のドキュメントでは、ドキュメント・ディレクトリのサブディレクトリにあるファイルのスニペットを参照しています：

\snippet snippets/textdocument-resources/main.cpp Adding a resource

ファイル名に続くテキストは、スニペットの一意識別子です。これは、上記の\snippet コマンドに対応する以下の例で示されるように、関連するスニペット・ファイルの引用コードを区切るために使用されます：

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

デフォルトでは、QDocは//! をコード・スニペット・マーカーとして探します。.pro 、.py 、.cmake 、CMakeLists.txt のファイルでは、#! が検出されます。最後に、.html 、.qrc 、.ui 、.xml 、.xq ファイルでは、<!-- が検出されます。

QDocは、スニペット・マーカーのスペース・ベースのインデントとスニペットの最小コンテンツ・インデントを比較することで、スニペットのインデントを正規化します（Qtマクロ、空白行、全行コメントは無視します）。その後、自動的にスニペットボディのインデントが小さい方に解除され、マーカーがどこに置かれているかに関係なく、生成されるコードが常に自然な構造を保つようにします。インデント不足のマーカーはそのまま残されます。

バージョン6.11から、\snippet コマンドと同じ行で、大文字と小文字を区別しないオプションの引数として言語を指定できるようになりました。これは \codeコマンドと同じように影響します。

このコマンドの使用例では、デフォルトのC++マークアップ・スタイルを上書きし、代わりにプレーン・テキストを出力します：

\snippet [text] code.cpp

これはQDocがマークアップする機能を持っていない言語を引用するときや、型にはまったファイル名のファイルから引用する必要があるときに便利です。

\codeline

\codeline コマンドは整形済みテキストの空白行を挿入します。これは現在の整形済みテキストエリアを閉じて新しいテキストエリアを開かずに、スニペット間にギャップを挿入するために使われます。