diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/yathesis/documentation/sections/notations.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/yathesis/documentation/sections/notations.tex | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/yathesis/documentation/sections/notations.tex b/Master/texmf-dist/doc/latex/yathesis/documentation/sections/notations.tex new file mode 100644 index 00000000000..99c52aecbdc --- /dev/null +++ b/Master/texmf-dist/doc/latex/yathesis/documentation/sections/notations.tex @@ -0,0 +1,245 @@ +\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} + +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} + +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} + +Les liens hypertextes figurent en couleur, ainsi : +\href{http://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} + +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, par exemple\footnote{Une liste des références bibliographiques est de + toute façon requise de façon évidente dans une thèse mais on peut souhaiter + recourir à un autre système de gestion de bibliographie que celui que + fournit le \Package{biblatex}.} \refCom{printbibliography}. +\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 ciblée\footnote{Sauf si la désactivation de + cette erreur a été demandée, cf. \vref{sec-desact-des-erre}.} ; + \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} + +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} + +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} + +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 : +%^^A \begin{description} +%^^A \item[ne prennent pas de valeur.] Une telle option, par exemple nommée +%^^A \refKey{option}, est alors documentée selon la syntaxe suivante: +%^^A \begin{docKey*}{option}{}{\meta{valeurs par défaut et initiale}} +%^^A \meta{Description de \refKey{option}} +%^^A \end{docKey*} +%^^A \item[prennent des valeurs.] Une telle option se présente alors sous la forme +%^^A \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} +%^^A \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} +%^^A +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}. + +% +\iffalse +%%% Local Variables: +%%% mode: latex +%%% eval: (latex-mode) +%%% ispell-local-dictionary: "fr_FR" +%%% TeX-engine: xetex +%%% TeX-master: "../yathesis.dtx" +%%% End: +\fi |