リンクの作成

これらのコマンドは、クラス、関数、サンプル、その他のターゲットへのハイパーリンクを作成するためのものです。

\リンク

リンク・コマンドは、多くの異なる種類のターゲットへのハイパーリンクを作成するために使用されます。このコマンドの一般的な構文は次のとおりです：

\l [ link criteria ] { link target } { link text }

...角括弧内のlink criteria はオプションですが、link target があいまいな場合は必要な場合があります。下記の「あいまいなリンクを修正する」を参照してください。

へのリンクには"˶l "コマンドが使えます：

外部ページ：
```
An URL with a custom link text:
\l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.

An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.
```
としてレンダリングします：

カスタムリンクテキストを含む URL：Qt 6 ドキュメント。

カスタムリンクテキストなしのURL: http://doc.qt.io/qt-6/.

外部ページも参照してください。
ドキュメント・ページ。リンク先は以下のようになります：
- を指定します：
```
Here is a link with a custom link text:
\l {Getting Started with QDoc}{QDoc - Getting Started}.

Here is a link with a link text that is the same as the link
target: \l {Getting Started with QDoc}.
```
  としてレンダリングされます：
  
  カスタム・リンク・テキストを持つリンクです：QDoc - はじめに。
  
  こちらはリンク・テキストがリンク・ターゲットと同じリンクです：QDoc入門。
- QDocで始めるページファイル名：
```
\page 08-qdoc-commands-creatinglinks.html
\title Creating Links

These commands are for creating hyperlinks to classes, functions,
examples, and other targets.

...

The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
explains how to create links with QDoc.
```
  としてレンダリングします：
  
  リンクの作成ページでは、QDocでリンクを作成する方法を説明しています。
- としてレンダリングします。
ドキュメント内の特定のアンカーセクション。リンク・ターゲットは以下のとおりです：
- セクション・コマンドのいずれかで指定されたセクション・タイトル：
```
Here is a link to a QDoc Commands section of the Writing
Documentation topic:
\l {Writing Documentation#QDoc Commands}{QDoc Commands}.

If you have unique section titles across your documentation
project, you can use the section title as a target without
the need to add the topic title:
\l {QDoc Commands}.
```
  としてレンダリングされます：
  
  以下は、「ドキュメントの書き方」トピックのQDocコマンド・セクションへのリンクです：QDocコマンド
  
  ドキュメント・プロジェクト全体に固有のセクション・タイトルがある場合、トピック・タイトルを追加しなくても、セクション・タイトルをターゲットとして使うことができます：QDocコマンド。
- QDocCommands：
```
\target assertions

Assertions make some statement about the text at the
point where they occur in the regexp, but they do not
match any characters.

...

Regexps are built up from expressions, quantifiers, and
\l {assertions} {assertions}.
```
APIアイテム。ターゲットリンクは以下のようになります：
- \l QWidget - を指定することができます。
- \l QWidget::sizeHint() - パラメータのない関数のシグニチャ。パラメータを持たない関数のシグニチャ。パラメータを持つ関数のシグニチャ。
- \l QWidget::removeAction(QAction* action) - パラメータを持つ関数のシグニチャ。完全に一致するものが見つからない場合、リンクは満たされず、QDoc はCan't link to...エラーを報告します。
- \l <QtGlobal> - QDocはCan't link to...エラーを報告します。

例です。ターゲット・リンクは、例のタイトル、または￤exampleコマンドで使用される相対パスです：

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \brief Shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

...

See the example: \l widgets/imageviewer

リンク・ターゲットがリンク・テキストと同じ場合は、第2引数を省略できます。

例えば、以下のようなドキュメントがある場合：

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

次のように簡略化できます：

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

1パラメータ・バージョンでは、中括弧は省略できることが多い。

QDoc はまた、通常の英単語に似ていない単語、例えば Qt のクラス名やQWidget やQWidget::sizeHint() のような関数からリンクを作ろうとします。このような場合、" \l" コマンドは省略することができますが、このコマンドを使うことで、QDocがリンク先を見つけられなかった場合に警告を発するようになります。さらに、関数名だけをリンクに表示させたい場合は、以下の構文を使用できます：

\l {QWidget::} {sizeHint()}

あいまいなリンクの修正

Qt 5.0からQtがモジュール化されたため、QDocが曖昧なリンクを扱わなければならない可能性が増えました。曖昧なリンクとは、複数のQtモジュールで対象が一致するリンクのことです。例えば、同じセクションのタイトルが複数のQtモジュールで表示されたり、あるモジュールのC++クラスの名前が別のモジュールのQML型の名前になったりします。Qt5での実例は、Qtという名前そのものです。Qt は、QtCore の C++ 名前空間の名前であり、QtQml の QML 型の名前でもあります。

Qt C++ namespaceQDocがこのHTMLページを生成した時点では、このリンクは正しいものでした。そのリンクはまだC++名前空間に行っているのでしょうか？Qdocはこのlinkコマンドからリンクを生成しました：

\l {Qt} {Qt C++ namespace}

Qt QML typeQDocがこのHTMLページを生成した時点では、このリンクも正しかったが、このリンク・コマンドを使わなければならなかった：

\l [QML] {Qt} {Qt QML type}

角括弧の中のQMLはQDocにターゲットがQMLページ上にある場合のみ、マッチするターゲットを受け入れるように指示します。QDocは実際にはC++名前空間のターゲットを最初に見つけますが、そのターゲットはC++ページにあるので、QDocはそれを無視してQMLページで同じターゲットを見つけるまで探し続けます。

オプションの角括弧の引数で、「◎」コマンドのガイダンスがなければ、QDocは最初に見つかった一致するターゲットにリンクします。QDocはこのような場合、リンクがあいまいであることを警告できません。

どのような引数を角括弧に入れることができますか？

角括弧の引数を持つリンク・コマンドの構文は以下の通りです：

\l [QML|CPP|DOC|QtModuleName] {link target} {link text}

角括弧の引数は\l (link) コマンドでのみ許されます。上の例ではQML を角括弧の引数として使い、QDocにQMLのターゲットを強制的にマッチさせる方法を示しています。多くの場合、これはQMLの型になりますが、QMLのメンバ関数のプロパティにすることもできます。

この例では、QDocはQt C++の名前空間ページを見つけるために角括弧の引数を必要としませんでした。しかし、マッチするQMLターゲットが邪魔になったときにQDocにC++ターゲットを見つけさせるために、CPP を角括弧の引数として使うことができます。例えば

\l [CPP] {Qt} {Qt C++ namespace}

...はQDocにQt QMLの型を無視させ、Qt C++の名前空間にマッチするまで検索を続けさせます。

リンク先がC++でもQMLでもない場合、DOC を角括弧の引数として使うことで、QDocがどちらにもマッチしないようにすることができます。この原稿を書いている時点では、DOC を使用する必要があるあいまいなリンクのケースはありませんでした。

多くの場合、ドキュメント作成者はリンク先がどの Qt モジュールにあるかを知っています。モジュール名がわかっている場合は、モジュール名を角括弧の引数として使います。上の例では、QtというQMLの型がQtQml モジュールにあることがわかっている場合、リンクコマンドを次のように書くことができます：

\l [QtQml] {Qt} {Qt QML type}

モジュール名を角括弧の引数として使った場合、QDocはそのモジュール内だけでリンク先を検索します。これにより、リンク・ターゲットの検索がより効率的になります。

最後に、モジュール名とエンティティ・タイプの引数は空白で区切って組み合わせることができるので、このようなものも可能です：

\l [CPP QtQml] {Window} {C++ class Window}

この記事を書いている時点では、この2つの組み合わせが必要なケースはありませんでした。

keywordも参照してください。

\sa（参照）

"See also "セクションでレンダリングされるリンクのリストを定義します。

このコマンドは、カンマで区切られたリンクのリストを引数として取ります。行末がカンマの場合は、次の行にリストを続けることができます。一般的な構文は

\sa {the first link}, {the second link},
    {the third link}, ...

QDocは自動的にプロパティの様々な関数を相互接続する "See also "リンクを生成しようとします。例えば、setVisible()関数は自動的にvisible()へのリンクを取得し、その逆も同様です。

一般的に、QDocは同じプロパティにアクセスする関数を相互接続する "See also "リンクを生成します。QDocは4つの異なる構文バージョンを認識します：

property()
setProperty()
isProperty()
hasProperty()

をサポートします。

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

また、"keyword"、"keyl "、"keytarget "も参照してください。

\ターゲット

(リンク)コマンドと(参照)コマンドでリンクできるドキュメント内の場所を指定します。

改行までのテキストがターゲット名になります。ターゲット名の後は必ず改行してください。ターゲット名の周りに波括弧を付ける必要はありませんが、ターゲット名がリンク・コマンドで使用される場合、波括弧が必要になることがあります。以下を参照のこと。

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

括弧で囲まれたターゲット名は、以下のようにリンクすることができる：

\l {capturing parentheses}

注：リンク例の括弧は、ターゲット名にスペースが含まれているため必要です。

\テーブル内のターゲット

テーブルの中で \target コマンドを使うときは、li-command(テーブルセル)の後に ˶´﹀`˵ コマンドが続き、それが別の行にあるか、その行にある最後のコンテンツであることを確認してください。これは、"li-command"（表セル）の後に "li-command"（表セル）が続くと、"li-command"（表セル）が別の行になるか、その行にある最後のコンテンツになります。言い換えれば、テーブルがあり、その中に \target が必要な場合、それが以下の構造に従っていることを確認してください：

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

を参照してください。

\キーワード

keyword "コマンドは、"link "コマンドと "see also "コマンドを使用してリンクできるドキュメンテーションの場所を指定します。また、生成されたインデックスにキーワードと場所を追加します。

キーワードにリンクする場合、デフォルトでリンクはそのキーワードが現れるQDocコメント(トピック)の一番上に行くという点を除けば、keywordコマンドはkeywordコマンドと同じです。

トピック内のsection ユニットに対してキーワードを作成したい場合は、セクション・タイトルの真上に「indiceskeyword」を追加してください：

\keyword debug
\section1 Debug command line option (--debug)
...

keywordは生成されたオフライン・ドキュメント・ファイル(.qch)のインデックスに登録されます。これにより、ユーザーは、例えば、Qt AssistantのIndex Searchでキーワードによって場所を調べることができ、Qt Creatorのコンテキスト・ヘルプでキーワードにアクセスできるようになります。

キーワードはQDoc実行中に処理されるすべてのドキュメントで一意でなければなりません。コマンドは行の残りの部分を引数として使用します。キーワードの後には必ず改行を入れてください。

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

キーワードでマークされた場所は、次のようにリンクすることができる：

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

キーワードテキストにスペースが含まれる場合は、括弧が必要です。

キーワードにスペースが含まれている場合は、括弧が必要です。

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

本書に含まれる文書の著作権は、それぞれの所有者に帰属します。本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の商標です。その他すべての商標は、それぞれの所有者に帰属します。