[latexrefman-commits] r545 - in /trunk: ChangeLog latex2e-fr.texi latex2e.texi

[vincent.b.1 at domain.hid]

Author: vincentb1
Date: Tue Sep 13 10:26:19 2016
New Revision: 545

URL: http://svn.gna.org/viewcvs/latexrefman?rev=545&view=rev
Log:
Document \@@ifstar.

* latex2e-fr.texi (\@@ifstar): New node.

* latex2e.texi (\makeatletter and \makeatother): Comment that
documenting \@ifstar is TODO.

Modified:
    trunk/ChangeLog
    trunk/latex2e-fr.texi
    trunk/latex2e.texi

Modified: trunk/ChangeLog
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/ChangeLog?rev=545&r1=544&r2=545&view=diff
==============================================================================
--- trunk/ChangeLog	(original)
+++ trunk/ChangeLog	Tue Sep 13 10:26:19 2016
@@ -1,3 +1,10 @@
+2016-09-13  Vincent Belaïche  <vincentb1 at domain.hid>
+
+	* latex2e-fr.texi (\@@ifstar): New node.
+
+	* latex2e.texi (\makeatletter and \makeatother): Comment that
+	documenting \@ifstar is TODO.
+
 2016-09-13  Vincent Belaïche  <vincentb1 at domain.hid>
 
 	* latex2e-fr.texi (\newcommand & \renewcommand, Spaces)

Modified: trunk/latex2e-fr.texi
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/latex2e-fr.texi?rev=545&r1=544&r2=545&view=diff
==============================================================================
--- trunk/latex2e-fr.texi	(original)
+++ trunk/latex2e-fr.texi	Tue Sep 13 10:26:19 2016
@@ -623,7 +623,7 @@
 
 Cette altération est nécessaire parce que beaucoup des commandes de
 @LaTeX{} utilisent @code{@@} dans leur nom, de sorte à empécher les
-utilisateur de définir accidentellement une commande qui remplacerait
+utilisateurs de définir accidentellement une commande qui remplacerait
 l'une des commandes privées de @LaTeX{}.  Les noms de commandes
 consistent en un caractère de catégorie 0, d'ordinaire une
 contr'oblique, suivi de lettres, c.-à -d.@: des caractères de
@@ -632,7 +632,7 @@
 le régime par défaut de codes de catégorie, les commandes définies par
 l'utilisateur ne peuvent pas contenir de @code{@@}.  Mais
 @code{\makeatletter} et @code{\makeatother} permettent aux utilisateurs
-de définir et re-définir des commandes dont le nom comprend une
+de définir et re-définir des commandes dont le nom comprend un
 @code{@@}.
 
 À utiliser dans un fichier @file{.tex}, dans le préambule. Ne pas
@@ -640,10 +640,11 @@
 commandes @code{\usepackage} et @code{\documentclass} règlent le code de
 catégorie de l'arobe à celui d'une lettre.
 
-Des exemple d'utilisation sont donnés ci-après :
+Des exemples d'utilisation sont donnés ci-après :
 
 @menu
-* \@@startsection:: Redefinir les commandes de rubricage.
+* \@@startsection:: Redéfinir les commandes de rubricage.
+* \@@ifstar:: Définir vos propres commandes étoilées.
 @end menu
 
 
@@ -721,6 +722,86 @@
 titre, par ex.@: @code{\bfseries} pour des caractères gras.
 @end table
 
+ at node \@@ifstar
+
+ at c Inpirée des trucs & astuces de Manuel Pégourié-Gonnard
+ at c (https://elzevir.fr/imj/latex/tips.html#stared)
+
+Vous l'avez sans doute remarqué, beaucoup d'environnements ou commandes
+standards de @LaTeX{} existent sous une variante étoilée. Vous pouvez avoir
+envie de reprendre cette idée quand vous définissez vos commandes et arguments.
+
+Si vous avez lu @ref{\newenvironment & \renewenvironment}, vous aurez compris
+que c'est immédiat pour les environnements car l'étoile est un caractère
+autorisé dans les noms d'environnements. Il vous suffit donc de faire
+ at code{\newenvironment at domain.hid}@}} et
+ at code{\newenvironment at domain.hid}*@}} avec les définitions souhaitées.
+
+Pour les commandes, c'est plus compliqué car l'étoile ne peut pas faire partie
+du nom de la commande. Il y aura donc une première commande, qui devra être
+capable de regarder si elle est ou non suivie d'une étoile et d'adapter son
+comportement en conséquence. Cette première commande ne pourra pas accepter
+d'argument, mais pourra faire appel à des commandes qui en acceptent. Par
+ailleurs, on utilise la commande @code{\@@ifstar} interne du noyau @LaTeX{} et
+vous pouvez vous reportez à « @ref{\makeatletter and \makeatother} » pour
+comprendre pourquoi cela implique l'usage d'un bloc
+ at code{\makeatletter...\makeatother}.
+
+Dans cet exemple, on définit @code{\ciel} comme une commande avec un
+argument obligatoire et admettant une variante étoilée @code{\ciel*}
+également avec un argument obligatoire :
+
+ at example
+\makeatletter
+\newcommand*\ciel at domain.hid #1 étoilé@}
+\newcommand*\ciel at domain.hid #1 non étoilé@}
+\newcommand\ciel at domain.hid@}@}
+\makeatother
+ at end example
+
+ at noindent ainsi, @code{\ciel at domain.hid@}} composera « ciel bleu non étoilé » tandis que
+ at code{\ciel*@{nocturne@}} composera « ciel nocturne étoilé ».
+
+Notez que les commandes intermédiaires @code{\ciel at domain.hid} et
+ at code{\ciel at domain.hid} comportent un @code{@@} dans leur nom ce qui est
+possible puisque elles apparaissent au sein d'un bloc
+ at code{\makeatletter...\makeatother}. Ceci assure qu'elles ne puissent pas être
+utilisées directement dans le document. L'utilisation de @@ dans le nom
+comporte certes un risque de collision avec une commande interne du noyeau
+ at LaTeX{}, mais une telle collision est facile à détecter et corriger car
+ at code{\newcommand*@{\@var{cmd}@}} vérifie que si la commande @code{\@var{cmd}}
+n'est pas déjà définie et génère une erreur si c'est le cas.
+
+Voici un autre exemple où la commande @code{\agentsecret} comporte deux
+arguments et sa variante étoilée @code{\agentsecret*} un seul :
+
+ at example
+\makeatletter
+\newcommand*\agentsecret at domain.hid@}@}
+\newcommand*\agentsecret at domain.hid@} \textsc at domain.hid@}@}
+\newcommand\agentsecret at domain.hid@}@}
+\makeatother
+ at end example
+
+ at noindent Avec cette définition la célèbre réplique de l'agent 007 :
+
+ at example
+Je m'appelle \agentsecret*@{Bond@}, \agentsecret at domain.hid@}.
+ at end example
+
+ at noindent est équivalente à  :
+
+ at example
+Je m'appelle \textsc at domain.hid@}, \textit at domain.hid@} textsc at domain.hid@}.
+ at end example
+
+Un dernier mot : contrairement aux noms d'environnement où l'étoile fait partie
+du nom lui-même, et pourrait donc être à n'importe quelle position, dans le nom
+d'une commande l'étoile est comme une sorte d'argument optionnel. D'un point de
+vue purement @TeX{}nique il est donc possible de mettre un nombre indéfini
+d'espace entre la commande et l'étoile. Ainsi @code{\agentsecret*@{Bond@}} et
+ at code{\agentsecret *@{Bond@}} sont équivalents. Toutefois la pratique commune
+est de ne jamais insérer de tels espaces.
 
 @node Document classes
 @chapter Classes de documents

Modified: trunk/latex2e.texi
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/latex2e.texi?rev=545&r1=544&r2=545&view=diff
==============================================================================
--- trunk/latex2e.texi	(original)
+++ trunk/latex2e.texi	Tue Sep 13 10:26:19 2016
@@ -610,6 +610,7 @@
 \makeatother
 @end example
 
+ at c xx TODO document \@ifstar, see latex2e-fr.texi
 
 @node Document classes
 @chapter Document classes