Création de liens

Ces commandes permettent de créer des liens hypertextes vers des classes, des fonctions, des exemples et d'autres cibles.

\l (lien)

La commande « \l » permet de créer un lien hypertexte vers de nombreux types de cibles. La syntaxe générale de la commande est la suivante :

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

... où l'link criteria e entre crochets est facultative, mais peut s'avérer nécessaire lorsque l'link target est ambiguë. Voir la section « Correction des liens ambigus » ci-dessous.

Vous pouvez utiliser la commande « \l » pour créer un lien vers :

• une page externe :

  An URL with a custom link text:
  \l {https://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {https://doc.qt.io/qt-6/}.

  S'affiche comme suit :

  Une URL avec un texte de lien personnalisé : Documentation Qt 6.

  Une URL sans texte de lien personnalisé : https://doc.qt.io/qt-6/.

  Voir aussi \externalpage.

• une page de documentation. La cible du lien peut être :
  • le titre de la page spécifié avec la \title commande :

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

    S'affiche comme suit :

    Voici un lien avec un texte de lien personnalisé : QDoc - Pour commencer.

    Voici un lien dont le texte correspond à la destination du lien : Premiers pas avec QDoc.

  • le nom du fichier de la page spécifié avec la \page commande :

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

    S'affiche comme suit :

    L'article de la page « Création de liens » explique comment créer des liens avec QDoc.

  • la page à l'aide d'une \keyword commande.
• une section d'ancrage particulière au sein d'un document. La cible du lien peut être :
  • un titre de section spécifié à l'aide de l'une des commandes Section:

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

    S'affiche comme suit :

    Voici un lien vers la section « Commandes QDoc » de la rubrique « Rédaction de la documentation » : Commandes QDoc.

    Si les titres de section de votre projet de documentation sont uniques, vous pouvez utiliser le titre de la section comme cible sans avoir à ajouter le titre de la rubrique : Commandes QDoc.

    Étant donné que le caractère « # » est utilisé pour créer des liens au sein des documents, il ne peut pas être utilisé tel quel lors de la création de liens vers des titres qui le contiennent. Il doit donc être échappé à l'aide d'une barre oblique inversée :

    \l {Using Qt with C\\#}

    Deux barres obliques inversées sont utilisées car QDoc traite le texte avant de le transmettre à la commande de lien.

  • une ancre définie avec une \target commande :

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

• un élément de l'API. Les liens cibles peuvent être :
  • \l QWidget - Le nom d’une classe documentée avec le \class ou \qmltype .
  • \l QWidget::sizeHint() - La signature d'une fonction sans paramètres. Si aucune fonction sans paramètres correspondant à la signature ne peut être trouvée, le lien est établi avec la première fonction correspondante trouvée.
  • \l QWidget::removeAction(QAction* action) - La signature d’une fonction avec des paramètres. Si aucune correspondance exacte n’est trouvée, le lien n’est pas établi et QDoc signale une erreur « Impossible de créer un lien vers… ».
  • \l <QtGlobal> - Le sujet d'une \headerfile commande.

  Si vous souhaitez que seul le nom de la fonction apparaisse dans le lien, vous pouvez utiliser la syntaxe suivante : \l{QWidget::}{sizeHint()}.

• Un exemple. La cible du lien est le titre de l'exemple ou un chemin relatif utilisé dans une \example commande :

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

Si la cible du lien est identique au texte du lien, vous pouvez omettre le deuxième argument.

Par exemple, si vous disposez d'une documentation telle que :

/*!
    \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}.
*/

Vous pouvez simplifier cela comme suit :

/*!
    \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.
*/

Pour la version à un paramètre, les accolades peuvent souvent être omises.

Liaison automatique

QDoc tente également de créer un lien à partir de tout mot qui ne ressemble pas à un mot anglais courant, par exemple les noms de classes ou de fonctions Qt, tels que QWidget ou QWidget::sizeHint(). Dans ces cas-là, la commande \l peut en réalité être omise, mais en l'utilisant, vous vous assurez que QDoc émettra un avertissement s'il ne parvient pas à trouver la cible du lien.

Si la création automatique de liens génère un lien indésirable pour un mot qui correspond par hasard à une cible de lien, vous pouvez le supprimer à l’aide de la variable de configuration `ignorewords`.

Correction des liens ambigus

Un lien ambigu est un lien dont la cible correspond à plusieurs modules Qt ou ensembles de documentation. Par exemple, le même titre de section peut apparaître dans plusieurs modules Qt, ou le nom d’une classe C++ dans un module peut également être celui d’un type QML dans un autre module. Un exemple concret dans Qt est le nom « Qt » lui-même : il s’agit à la fois du nom d’un espace de noms C++ dans QtCore et d’un type QML dans QtQml.

Supposons que nous souhaitions créer un lien vers Qt C++ namespace. Au moment où QDoc a généré cette page HTML, ce lien était correct. Renvoie-t-il toujours vers l’espace de noms C++ ? QDoc a généré ce lien à partir de la commande de lien suivante :

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

Supposons maintenant que nous souhaitions créer un lien vers Qt QML type. Au moment où QDoc a généré cette page HTML, ce lien était également correct, mais nous avons dû utiliser cette commande de lien :

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

Le code QML entre crochets indique à QDoc de n'accepter une cible correspondante que si celle-ci se trouve sur une page QML. En réalité, QDoc trouve d'abord la cible de l'espace de noms C++, mais comme celle-ci se trouve sur une page C++, QDoc l'ignore et continue à chercher jusqu'à ce qu'il trouve la même cible sur une page QML.

Sans l’indication fournie par la commande `\l ` dans l’argument facultatif entre crochets, QDoc crée un lien vers la première cible correspondante qu’il trouve. QDoc ne peut pas signaler que le lien est ambigu dans de tels cas, car il ignore qu’une autre cible correspondante existe.

Quels arguments peuvent figurer entre crochets ?

Une commande de lien comportant un argument entre crochets a la syntaxe suivante :

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

L'argument entre crochets n'est autorisé que dans la commande « \l (link) ». L'exemple ci-dessus montre comment « QML » est utilisé comme argument entre crochets pour forcer QDoc à faire correspondre une cible QML. Le plus souvent, il s’agira d’un type QML, mais il peut également s’agir d’une fonction membre ou d’une propriété QML. De plus, certains types QML contiennent des propriétés et des propriétés associées portant le même nom. Les propriétés associées peuvent être sélectionnées à l’aide de l’argument « attached ». Si l’argument « attached » est omis, les propriétés standard seront liées en priorité par rapport aux propriétés associées portant le même nom.

Dans l’exemple, QDoc n’avait pas besoin d’un argument entre crochets pour trouver la page de l’espace de noms Qt C++, car celle-ci était de toute façon la première cible correspondante trouvée par QDoc. Cependant, pour forcer QDoc à trouver une cible C++ lorsqu’une cible QML correspondante fait obstacle, on peut utiliser CPP comme argument entre crochets. Par exemple, le lien suivant forcera QDoc à ignorer le type Qt Qml et à poursuivre la recherche jusqu’à ce qu’il trouve une correspondance avec l’espace de noms Qt C++.

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

Si la cible du lien n’est ni une entité C++ ni une entité QML, DOC peut être utilisé comme argument entre crochets pour empêcher QDoc de faire correspondre l’une ou l’autre de ces entités. À l’heure où nous écrivons ces lignes, aucun cas de lien ambigu n’a nécessité l’utilisation de DOC.

Souvent, l’auteur de la documentation sait dans quel module Qt se trouve la cible du lien. Lorsque le nom du module est connu, utilisez-le comme argument entre crochets. Dans l’exemple ci-dessus, si l’on sait que le type QML nommé Qt se trouve dans le module QtQml, on peut écrire la commande de lien comme suit :

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

Lorsqu’un nom de module est utilisé comme argument entre crochets, QDoc recherchera la cible du lien uniquement dans ce module. Cela rend la recherche des cibles de lien plus efficace.

Enfin, les arguments « nom du module » et « type d’entité » peuvent être combinés, séparés par un espace, ce qui permet également d’écrire quelque chose comme ceci :

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

À l'heure où nous écrivons ces lignes, aucun cas ne justifiait la combinaison des deux.

Voir aussi \sa, \target, et \keyword.

\sa (voir aussi)

La commande « \sa » définit une liste de liens qui seront affichés dans une section distincte intitulée « Voir aussi » au bas de l'unité de documentation.

Cette commande prend comme argument une liste de liens séparés par des virgules. Si la ligne se termine par une virgule, vous pouvez poursuivre la liste sur la ligne suivante. La syntaxe générale est la suivante :

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

QDoc tentera automatiquement de générer des liens « Voir aussi » reliant les différentes fonctions d'une propriété. Par exemple, une fonction setVisible() sera automatiquement associée à un lien vers visible() et inversement.

En général, QDoc génère des liens « Voir aussi » qui relient entre elles les fonctions accédant à la même propriété. Il reconnaît quatre variantes syntaxiques différentes :

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

La commande « \sa » prend en charge le même type de liens que la \l commande.

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

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

Voir aussi \l, \target et \keyword.

\target

La commande « \target » désigne un emplacement dans la documentation vers lequel vous pouvez créer un lien à l’aide des commandes «\l » (lien) et «\sa » (voir aussi).

Le texte jusqu’au saut de ligne devient le nom de la cible. Veillez à faire suivre le nom de la cible d’un saut de ligne. Les accolades ne sont pas obligatoires autour du nom de la cible, mais elles peuvent l’être lorsque celui-ci est utilisé dans une commande de lien. Voir ci-dessous.

/*!
    \target capturing parentheses
    \section1 Capturing Text

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

    ...
*/

Les parenthèses de capture du nom de cible peuvent être liées de la manière suivante :

• \l {capturing parentheses}

Ci-dessus, le nom de la cible est placé entre crochets car il contient des espaces.

\target dans un \table

Lorsque vous utilisez la commande « \target » dans un tableau, assurez-vous que la commande « \target » suit une \licommande (cellule de tableau), car certains générateurs ne prennent en charge que les cibles vers une cellule individuelle, et non vers une ligne entière. De plus, assurez-vous qu’elle se trouve soit sur une ligne distincte, soit qu’elle soit le dernier élément de la ligne dans laquelle elle figure. Cela s’explique par le fonctionnement de la commande « \target » : elle utilise tout ce qui se trouve jusqu’au prochain saut de ligne comme paramètre. En d’autres termes, si vous avez un tableau et que vous souhaitez y insérer une commande « \target », assurez-vous qu’elle respecte la structure suivante :

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

Voir aussi \l, \sa et \keyword.

\keyword

La commande « \keyword » désigne un emplacement dans la documentation vers lequel vous pouvez créer un lien à l’aide des commandes «\l » (lien) et «\sa » (voir aussi). Elle ajoute également le mot-clé et l’emplacement aux index générés.

La commande ` \keyword ` est similaire à la \target , sauf que lorsque vous créez un lien vers un mot-clé, celui-ci pointe par défaut vers le début du commentaire QDoc (rubrique) dans lequel « \keyword » apparaît.

Si vous souhaitez créer un mot-clé pour une unité « section » au sein d’une rubrique, ajoutez la balise ` \keyword ` directement au-dessus du titre de la section :

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

Contrairement à \target, les mots-clés sont enregistrés dans les index des fichiers de documentation hors ligne générés (.qch). Cela permet aux utilisateurs de rechercher l'emplacement par mot-clé, par exemple dans la fonction « Index Search » deQt Assistant, et rend le mot-clé accessible dans l'aide contextuelle de Qt Creator.

Les mots-clés doivent être uniques dans l’ensemble des documents traités lors de l’exécution de QDoc. La commande utilise le reste de la ligne comme argument. Veillez à faire suivre le mot-clé d’un saut de ligne.

/*!
    \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.

    ...
*/

Il est possible de créer un lien vers l'emplacement marqué par le mot-clé à l'aide de :

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

Si le texte du mot-clé contient des espaces, les crochets sont obligatoires.

Voir aussi \l (lien), \sa (voir aussi) et \target.