Smartdoc/titre-et-references

Titres internes, numérotation et références

Contexte :

Le SmartDoc correspond à un système de document dynamique qu'il est possible de paramétrer avec des variables (pour intégrer des valeurs de façon dynamique), des conditions de visibilités (afficher ou masquer un élément du document selon telle ou telle condition), et même des conditions de répétitions (répéter un éléments autant de fois que nécéssaire).

Mais qu'en est il des titres internes du document ? Comment paramétrer les titres et leur numérotation dans un modèle de document dynamique puisque n'importe quelle rubrique (chapitre, paragraphe ...) peut apparaitre et disparaitre selon le contexte ? Comment faire référence à une rubrique (càd, à un titre) alors que sa numérotation est dynamique ?

Définir un titre

Comme défini dans la rubrique dédiée, un SmartDoc est constitué d'une suite ordonnée d'élément de contenu. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'élément de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).

Les "options" disponibles sur l'élément de contenu permettent de définir des caractéristiques spéciales de cet élément : notamment indiquer que cet élément doit être considéré comme un titre / sous-titre interne.

Marche à suivre :

- Créer un nouvel élément de contenu (c'est à dire une nouvelle ligne dans la feuille du tableur de paramétrage)

- Saisissez le titre à affiche dans la colonne "Contenu"

- Donner à ce nouvel élément l'option "title-level" pour qu'il soit considéré comme un titre / sous-titre interne. L'option "title-level" doit définir le niveau du titre (de 1 à 6 inclus). Ex: `title-level: 3`

- Vous pouvez éventuellement rajouter une condition de visibilité sur votre élément (comme pour tout autre élément). Notez néanmoins que seul le titre sera affecté par cette condition.

Notez que :

• Ce système de niveau de titre permet de réguler la hiérarchie des titres du document, mais ce n'est en rien un moyen d'écrire un titre plus grand ou plus petit (utilisez les "styles" pour cela) ;
• Il est préférable de respecter la logique hiérarchique : un titre de niveau 2 ne peut être défini qu'au sein d'un titre de niveau 1, et qu'un titre de niveau 3 ne le sera qu'au sein d'un titre de niveau 2 et ainsi de suite. Il ne serait pas logique de définir un titre de niveau 5 directement en dessous d'un titre de niveau 1 (il sera alors considéré par le document comme un titre de niveau 2 même si vous avez indiqué 5) ;
• Si vous rajoutez une conditions de visibilités sur un titre, cela ne fera pas disparaitre le contenu de la rubrique mais seulement le titre lui-même. Si vous souhaiter conditionner l'affichage de toute une rubrique (titre + ses paragraphes etc.) nous vous conseillons d'utiliser le système de "BLOC" : le bloc contiendra l'ensemble de la rubrique et la condition d'affichage portera directement sur le bloc ;

Intégrer une référence dynamique vers un titre

Vous pouvez à tout moment intégrer dans votre contenu une référence dynamique vers un titre du document.

1 - Identifier le titre

En amont, il est nécéssaire d'identifier le titre en lui donnant un identifiant unique. Pour cela, utilisez l'option title-id sur l'élément de contenu correspondant (l'option se trouvera donc au dessous de `title-level`).

2 - Intégrer la référence

Ensuite, vous pouvez faire référence à ce titre dans votre contenu en utilisant l'opérateur spécial @ref suivi du title-id à référencer.

Exemple de contenu utilisant une référence :

    Le décret énonce les différents cas pris en compte par la procédure. Voir : {@ref:article-truc}

3 - Formater la référence

Vous pouvez vouloir afficher la référence au titre de plusieurs façon : juste le numéro du titre, juste le titre lui-même, le numéro du titre ainsi que ces parents (1-5-2) etc.

Par défaut, l'intégration d'une référence affiche sa numérotation ainsi que le contenu du titre mais il existe plusieurs façon de personnaliser l'affichage de cette référence :

— N'afficher que la numérotation :

Utiliser le transformateur :num pour n'afficher que la numérotation.

    Comme indiqué à l'article {@ref:article-truc:num} du contrat, il faut recourir à une procédure de ...

— N'afficher que le titre :

Utiliser le transformateur :title-only pour n'afficher que le titre sans la numérotation.

    Dans notre article "{@ref:article-truc:title-only}" nous expliquons comment le ...

— Affichage totalement personnalisé :

Utiliser le transformateur :format("xxx") pour formater vous même l'affichage de la référence.

Il faudra spécifier (à la place des xxx) une chaîne de caractère décrivant le format souhaité.

Cette chaîne répond à la même syntaxe que celle de l'option de document title-num-display (documentation ici) où $1 (et $2, $3 ... $6) font référence à l'index de numérotation d'un titre et permettent ainsi de personnaliser le système de numérotation (Exemple : pour un titre placé au 9-7-1 d'un document, $1 vaut 9, $2 vaut 7, et $3 vaut 1).

Utilisez aussi ce transformateur :format pour mettre en forme votre référence en la préfixant d'un terme, ou en personnalisant les signes séparateurs.

Exemple de contenu :

    En référence à l'{ @ref:mon-titre:format("Art. $3.$2") } du code de ...

Ce qui affichera "En référence à l'Art 6.4 du code de ..." (pour un titre ayant l'identifiant "mon-titre'" dans le document et qui serait le 2ème titre visible du niveau 4, lui-même enfant du 6ème titre visible de niveau 3).

Autre exemple d'intégration personnalisée :

    En vous référant à la {@ref:section-bidule:format("section $3 (article $1.$2)")}, vous trouverez ... 

Qui affichera quelque chose comme : "En vous référant à la section 12 (article 3.4), vous trouverez ..."