\chapter{Notations, syntaxe, terminologie et codes couleurs}\label{cha-synt-term-notat} Ce chapitre précise les notations, syntaxe, terminologie et codes couleurs de la présente documentation. \section{Commandes, environnements, clés, valeurs}\label{sec-comm-envir-cles} \index{commande}% \index{environnement}% \index{clé}% \index{valeur}% Les commandes, environnements, clés et valeurs de clés sont systématiquement composés en fonte à chasse fixe. En outre, pour plus facilement les distinguer, ils figurent avec des couleurs propres : \begin{itemize} \item les commandes en bleu : \docAuxCommand*{commande} ; \item les environnements en \enquote{sarcelle} : \docAuxEnvironment*{environnement} ; \item les clés en pourpre : \docAuxKey*{clé} ; \item les valeurs des clés en violet : \docValue*{valeur}. \end{itemize} \section{Arguments génériques} \label{sec-arguments-generiques} \index{argument générique}% Pour expliquer le rôle d'une commande, il est parfois nécessaire d'indiquer à quoi celle-ci s'applique, autrement dit quel en est l'argument générique. Un tel argument est composé : \begin{itemize} \item en fonte à chasse fixe ; \item en italique ; \item entre chevrons simples ; \end{itemize} le tout en marron, ainsi : \meta{argument générique}. \section{Liens hypertextes} \label{sec-liens-hypertextes} \index{lien hypertexte}% Les liens hypertextes figurent en couleur, ainsi : \href{https://gte.univ-littoral.fr/members/dbitouze/pub/latex}{lien hypertexte}. La plupart des références aux commandes, environnements et clés définis dans la présente documentation, sont des liens hypertextes, surmontés du numéro de page où se trouve la cible correspondante (sauf si elle se situe sur la même page) : \begin{itemize} \item \refCom{author} ; \item \refEnv{abstract} ; \item \refKey{professor}. \end{itemize} \section{Éléments \enquote{obligatoires}} \label{sec-comm-oblig} \index{élément obligatoire}% L'icône \mandatory{}, figurant en regard de certains éléments (commandes ou environnements), indique que ceux-ci sont \enquote{obligatoires} et ils peuvent l'être pour différentes raisons : \begin{itemize} \item parce qu'ils sont requis : \begin{itemize} \item de façon évidente dans une thèse, par exemple l'auteur, le titre, l'institut, la table des matières (commandes \refCom{author}, \refCom{title}, \refCom{institute}, \refCom{tableofcontents}) ; \item selon le \textcite{guidoct}, par exemple le champ disciplinaire, l'école doctorale, les mots clés, le résumé (commandes \refCom{academicfield}, \refCom{doctoralschool}, \refCom{keywords}, environnement \refEnv{abstract}) ; \end{itemize} \item parce qu'ils sont nécessaires au fonctionnement \emph{par défaut} de la \yatCl{}, par exemple \refCom{maketitle}, \refCom{mainmatter} ; \item parce qu'ils sont fortement recommandés par l'auteur de la présente classe\footnote{Par exemple \protect\refCom{printbibliography}. Une liste des références bibliographiques est évidemment de toute façon requise dans une thèse mais on peut souhaiter recourir à un autre système de gestion de bibliographie que celui que fournit le \Package{biblatex}.}. \end{itemize} \begin{dbremark}{Éléments \enquote{obligatoires} : modérément pour certains}{} Certains de ces éléments ne sont que modérément \enquote{obligatoires} car, s'ils sont omis : \begin{enumerate} \item cette omission est : \begin{description} \item[passée sous silence] par défaut\footnote{C'est-à-dire en version intermédiaire du document (cf. valeur par défaut \docValue{inprogress} de la clé \refKey{version}). Le signalement est également désactivé en versions intermédiaire alternative et brouillon (cf. valeurs \docValue{inprogress*} et \docValue{draft} de la clé \refKey{version}).} ; \item[signalée] (seulement) en versions \enquote{à soumettre}\footnote{Cf. valeur \docValue{submitted} de la clé \refKey{version}.} et \emph{finale}\footnote{Cf. valeur \docValue{final} de la clé \refKey{version}.} du document, par le biais d'une erreur de compilation\index{erreur de compilation}\index{compilation!erreur} ciblée\footnote{Sauf si la désactivation de cette erreur a été demandée, cf. % \vref{sec-desact-des-erre} \vref{cha-usage-avance}.} ; \end{description} \item un texte générique est en général affiché à sa place\footnote{Si cet élément est conçu pour produire du texte.}. \end{enumerate} \end{dbremark} Naturellement, tout élément non \enquote{obligatoire} est réputé optionnel. \section{Codes sources} \label{sec-codes-sources} \index{code source}% Les exemples qui illustrent la présente documentation sont constitués de codes sources et, le cas échéant, des \enquote{copies d'écran} correspondantes. Ceux-ci proviennent le plus souvent du spécimen de document composé avec la \yatCl{}, fourni avec l'ensemble de la classe (cf. \vref{sec-specimen-arborescence}). Ces codes sources figurent dans des cadres de couleur bleu : \begin{itemize} \item non ombrés s'ils doivent être saisis dans le corps du document ; \item ombrés s'ils doivent être saisis en préambule du fichier (maître) : \begin{itemize} \item soit directement ; \item soit indirectement \emph{via} un fichier lui-même importé en préambule, ce qui peut être fait : \begin{itemize} \item soit automatiquement par la \yatCl{}, par le biais du \File{\configurationfile} (cf. \vref{rq-configurationfile}) ; \item soit manuellement au moyen de la commande \docAuxCommand{input}. \end{itemize} \end{itemize} \end{itemize} Ces cadres pourront en outre comporter d'éventuels titres : \begin{multicols}{2} \begin{bodycode} "\meta{code source}" \end{bodycode} \begin{bodycode}[title=\meta{titre}] "\meta{code source}" \end{bodycode} \begin{preamblecode} "\meta{code source à insérer en préambule}" \end{preamblecode} \begin{preamblecode}[title=\meta{titre}] "\meta{code source à insérer en préambule}" \end{preamblecode} \end{multicols} \section{Espaces dans les codes sources} \label{sec-espaces-dans-les} \index{espace!dans les codes sources}% Pour éviter certaines confusions, les espaces dans les codes sources devant être saisis au clavier sont parfois matérialisés au moyen de la marque \lstinline[showspaces]+ +. \section{Options} \label{sec-options} \index{option!terminologie}% La \yatCl{} ainsi que certaines de ses commandes et certains de ses environnements peuvent être modulés au moyen d'options, ou listes d'options (séparées par des virgules). Ces options se présentent sous la forme \meta{clé}|=|\meta{valeur} et la \meta{valeur} passée à une \meta{clé} peut être : % \begin{description} % \item[ne prennent pas de valeur.] Une telle option, par exemple nommée % \refKey{option}, est alors documentée selon la syntaxe suivante: % \begin{docKey*}{option}{}{\meta{valeurs par défaut et initiale}} % \meta{Description de \refKey{option}} % \end{docKey*} % \item[prennent des valeurs.] Une telle option se présente alors sous la forme % \meta{clé}|=|\meta{valeur}. Les valeurs passées à une clé peuvent être : \begin{description} \item[libre.] Si une telle \meta{clé} est (pour l'exemple) nommée \refKey{freekey}, elle est alors documentée selon la syntaxe suivante : \begin{docKey*}{freekey}{=\meta{valeur}}{\meta{valeurs par défaut et initiale}} \meta{Description de \refKey{freekey}} \end{docKey*} \item[imposée] (parmi une liste de valeurs possibles). Si une telle \meta{clé} est (pour l'exemple) nommée \refKey{choicekey} et de valeurs imposées \docValue*{valeur1}, \docValue*{valeur2}, ..., \docValue*{valeurN}, elle est alors documentée selon la syntaxe suivante\footnote{Comme souvent en informatique, la barre verticale séparant les valeurs possibles signifie \enquote{ou}.} : \begin{docKey*}{choicekey}{=\docValue*{valeur1}\textbar\docValue*{valeur2}\textbar...\textbar\docValue*{valeurN}}{\meta{valeurs par défaut et initiale}} \meta{Description de \refKey{choicekey} et de ses valeurs possibles} \end{docKey*} \end{description} % \end{description} Les \meta{valeurs par défaut et initiale} d'une clé sont souvent précisées (entre parenthèses en fin de ligne). Elles indiquent ce que la clé vaut : \begin{description} \item[par défaut] c'est-à-dire lorsque la clé \emph{est} employée, mais \emph{seule} c'est-à-dire sans qu'une valeur explicite lui soit passée ; \item[initialement] c'est-à-dire lorsque la clé \emph{n'est pas} employée. \end{description} % Ainsi certaines clés, appelées booléennes parce qu'elles ne peuvent prendre que deux valeurs (\docValue*{true} et \docValue*{false}), portent la précision par exemple \enquote{par défaut \lstinline+true+, initialement \lstinline+false+} car elles valent : \begin{enumerate} \item \docValue*{true} si elles sont employées mais sans qu'une valeur leur soit passée ; \item \docValue*{false} si elles ne sont pas employées ; \item la valeur \docValue*{true} ou \docValue*{false} qui leur est passée le cas échéant. \end{enumerate} Une telle clé, par exemple nommée \refKey{booleankey}, est alors documentée selon la syntaxe suivante : \begin{docKey*}{booleankey}{=\docValue*{true}\textbar\docValue*{false}}{par défaut \lstinline+true+, initialement \lstinline+false+} \meta{Description de \refKey{booleankey}} \end{docKey*} Illustrons ceci au moyen de la clé \refKey{nofrontcover} qui peut être passée en option de la \yatCl{}. C'est une clé booléenne valant par défaut \docValue*{true} et initialement \docValue*{false}, c'est-à-dire : \begin{enumerate} \item \docValue*{true} si l'utilisateur l'emploie en option de la \yatCl{} mais sans lui passer de valeur : \begin{preamblecode} \documentclass[nofrontcover,"\meta{autres options}"]{yathesis} \end{preamblecode} \item \docValue*{false} si l'utilisateur ne l'emploie pas en option de la \yatCl{} : \begin{preamblecode} \documentclass["\meta{toutes options sauf \refKey*{nofrontcover}}"]{yathesis} \end{preamblecode} \item la valeur \docValue*{true} ou \docValue*{false} que l'utilisateur lui passe le cas échéant en option de la \yatCl{} : \begin{preamblecode} \documentclass[nofrontcover=true,"\meta{autres options}"]{yathesis} \end{preamblecode} ou \begin{preamblecode} \documentclass[nofrontcover=false,"\meta{autres options}"]{yathesis} \end{preamblecode} \end{enumerate} \section{Faux-texte} \label{sec-faux-texte} Certains exemples comportent des paragraphes de \gls{fauxtexte}, obtenus au moyen de la commande |\lipsum| du \Package{lipsum}. %%% Local Variables: %%% mode: latex %%% TeX-master: "../yathesis-fr" %%% End: