Voir la source de Smartdoc/titre-et-references

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

<br/>

'''Contexte :''' 

Le [[SmartDoc|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|conditions de visibilités]] (afficher ou masquer un élément du document selon telle ou telle condition), et même des [[Boucles|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, sous-titres et de leur numérotation ? Comment paramétrer cela dans un modèle de document dynamique puisque n'importe quel chapitre peut apparaitre et disparaitre selon le contexte et que cela remet en cause la numérotation ? Comment faire référence à titre alors que sa numérotation est dynamique ? 
C'est tout cela que nous vous expliquons ici. 


== Définir un titre ==

Comme défini dans la [[SmartDoc|rubrique dédiée]], un [[SmartDoc|SmartDoc]] est constitué d'une suite ordonnée ''[[Élément_de_contenu|d'éléments de contenu]]''. 
Dans la feuille du tableur de paramétrage, il faut créer autant de lignes que d'[[Élément_de_contenu|éléments de contenus dynamiques]]. 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 [[SmartDoc#Options|"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, lui assigner un "niveau" (titre de niveau 1, 2, ...) et un "identifiant" pour s'y référer.
 
:: '''Marche à suivre :''' 
:: -  Créer un nouvel ''[[Élément_de_contenu|é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 au document. 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, pas le contenu qui suit (pour conditionner la visibilité d'une rubrique entière, utilisez [[SmartDoc/Blocs|le système de blocs]]).


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 de styliser un titre pour qu'il apparaissent 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 [[SmartDoc#Visible_if|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 [[SmartDoc/Blocs|"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.

Notez qu'il existe deux types de référence dynamiques : 
:: - Celles qui référencent un titre du document courant : nommée "référence interne" ;
:: - Et celles qui font référence à un titre d'un autre document, nommée "référence externe" ou "référence inter-document" ;


=== 1 - Identifier le titre ===

[[Fichier:Id-title.png|vignette|left|Exemples de titres portant des "identifiants" uniques afin qu'ils puissent être référencés .|redresse=1.25]]

Pour pouvoir faire une référence à un titre, il est d'abord nécéssaire de donner un "identifiant unique" au titre vers lequel la référence doit porter.
Pour cela, on utilise l'option <code>title-id</code> sur l'élément de contenu correspondant, en plus de l'option <code>title-level</code> décrite précédemment. Evitez d'intégrer des espaces ou des caractères spéciaux dans vos identifiants de titre car cela peut compliquer l'écriture des références. Ex: <code>title-id: mon-super-titre</code>

''<b>Rappel :</b> dans un SmartDoc, pour qu'un élément soit affichés comme un titre, il doit porter l'option <code>title-level</code> avec une valeur comprise entre 1 et 6 selon le niveau de titre (titre de premier niveau, de 2ème niveau etc.). Ex : <code>title-level: 1</code>''


=== 2 - Intégrer la référence ===

Vous pouvez faire référence à un titre dans votre contenu en utilisant :

— <b>Pour une référence vers un titre interne au document</b>, utilisez l'opérateur spécial <code>@ref</code>. Cet opérateur doit être accompagné d'un paramètre obligatoire : le '''title-id''' du titre à référencer. Chaque paramètre étant séparé par le signe <code>:</code>, la syntaxe d'une référence interne prend la forme de : <code>{ @ref : title-id }</code>. 

— <b>Pour une référence vers un titre présent dans un autre document</b>, utilisez l'opérateur spécial <code>@ref-ext</code>. Cet opérateur doit être accompagné de 2 paramètres obligatoires : le '''doc-id''' du document vers lequel porte la référence, puis le  '''title-id''' du titre à référencer dans ce document externe. Chaque paramètre étant séparé par le signe <code>:</code>, la syntaxe d'une référence externe prend la forme de : <code>{ @ref-ext : doc-id : title-id }</code>. 


:: '''''Exemple de contenu utilisant une référence interne :''''' 
:: <pre>Le décret énonce les différents cas pris en compte par la procédure. Voir : { @ref:article-truc }</pre>

:: '''''Exemple de contenu utilisant une référence externe vers un autre document: ''''' 
:: <pre>Voir annexe : { @ref-ext:annexe1:article-truc }</pre>

=== 3 - Formater la référence ===

Que ce soit une référence interne ou une référence externe, vous pouvez vouloir afficher la référence au titre de plusieurs façon : seulement la numérotation du titre, seulement le titre, la numérotation du titre ainsi que ces parents (1-5-2) etc. 

Par  défaut, l'intégration d'une référence affiche la numérotation suivi du titre mais il est possible de personnaliser l'affichage : 

:: '''— N'afficher que la numérotation :'''

:: Utiliser le transformateur <code>:num</code> comme dernier paramètre pour n'afficher que la numérotation. 
:: <pre>    Comme indiqué à l'article {@ref:article-truc:num} du contrat, il faut recourir à une procédure de ...</pre>
:: De même pour une référence externe : 
:: <pre>    Voir article { @ref-ext:mon-doc:article-truc:num } de l'annexe.</pre>


:: '''— N'afficher que le titre :'''

:: Utiliser le transformateur <code>:title-only</code> comme dernier paramètre pour n'afficher que le titre sans sa numérotation. 
:: <pre>    Dans notre article "{@ref:article-truc:title-only}" nous expliquons comment le ...</pre>


:: '''— Affichage totalement personnalisé :'''

:: Utiliser le transformateur <code>:format("xxx")</code> 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 <code>title-num-display</code> ([[SmartDoc|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, <code>$1</code> vaut 9, <code>$2</code> vaut 7, et <code>$3</code> vaut 1). 

:: Utilisez aussi ce transformateur <code>:format</code> 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 : 
:: <pre>    En référence à l'{ @ref:mon-titre:format("Art. $3.$2") } du code de ...</pre>
:: Ce qui affichera "''En référence à l'<u>Art 6.4</u> 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 :  
:: <pre>    En vous référant à la {@ref:section-bidule:format("section $3 (article $1.$2)")}, vous trouverez ... </pre>
:: Qui affichera quelque chose comme : "''En vous référant à la <u>section 12 (article 3.4)</u>, vous trouverez ...''"