% !TeX encoding = ISO-8859-1
% Ceci est la documentation du package "scratch"
%
% Fichier compilé avec pdflatex
\documentclass[frenchb,a4paper,10pt]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[margin=2cm]{geometry}
\usepackage[bottom]{footmisc}
\usepackage{libertine,boites,tikz,enumitem,MnSymbol,babel,xspace,listings,scratch}
\usepackage[scaled=0.8]{luximono}
\frenchbsetup{og=«,fg=»}
\def\SCRATCH{\texttt{scratch}\xspace}
\makeatletter
\def\code{\expandafter\code@i\string}
\def\code@i#1{%
	\begingroup
		\par\nobreak\medskip\parindent0pt
		\leftskip.1\linewidth
		\catcode`\^^I 13 \begingroup\lccode`\~`\^^I \lowercase{\endgroup\def~{\leavevmode\space\space\space\space}}%
		\let\do\@makeother \dospecials
		\ttfamily\small\@noligs
		\make@car@active\<{$\langle$\begingroup\itshape}%
		\make@car@active\>{\endgroup$\rangle$}%
		\obeylines\obeyspaces
		\def\code@ii##1#1{##1\par\medbreak\endgroup}%
		\code@ii
}
\long\def\grab@toks#1\relax{\gdef\right@content{#1}}

\newcommand\disable@lig[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~{\leavevmode\kern\z@\string#1}}%
}

\newcommand\make@car@active[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~}%
}

\newcommand\exemple{%
	\begingroup
	\parskip\z@
	\exemple@}

\newcommand\exemple@{%
	\medbreak\noindent
	\begingroup
		\let\do\@makeother\dospecials
		\make@car@active\ { {}}%
		\make@car@active\^^M{\par\leavevmode}%
		\make@car@active\^^I{\space\space}%
		\make@car@active\,{\leavevmode\kern\z@\string,}%
		\make@car@active\-{\leavevmode\kern\z@\string-}%
		\make@car@active\>{\leavevmode\kern\z@\string>}%
		\make@car@active\<{\leavevmode\kern\z@\string<}%
		\@makeother\;\@makeother\!\@makeother\?\@makeother\:% neutralise frenchb
		\exemple@@
}

\newcommand\exemple@@[1]{%
	\def\@tempa##1#1{\exemple@@@{##1}}%
	\@tempa
}

\newcommand\exemple@@@[1]{%
	\xdef\the@code{#1}%
	\endgroup
		\begingroup
			\fboxrule0.4pt \fboxsep=5pt
			\let\breakboxparindent\z@
			\def\bkvz@top{\hrule\@height\fboxrule}%
			\def\bkvz@bottom{\hrule\@height\fboxrule}%
			\let\bkvz@before@breakbox\relax
			\def\bkvz@set@linewidth{\advance\linewidth\dimexpr-2\fboxrule-2\fboxsep\relax}%
			\def\bkvz@left{\vrule\@width\fboxrule\kern\fboxsep}%
			\def\bkvz@right{\kern\fboxsep\vrule\@width\fboxrule}%
			\breakbox
				\kern.5ex\relax
				\begingroup
					\ttfamily\small\the@code\par
				\endgroup
				\kern3pt
				\hrule height0.1pt width\linewidth depth0.1pt
				\vskip5pt
				\newlinechar`\^^M\everyeof{\noexpand}\scantokens{#1}\par
			\endbreakbox
		\endgroup
	\medbreak
	\endgroup
}
\begingroup
	\catcode`\<13 \catcode`\>13
	\gdef\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
		\bgroup
			\verb@eol@error \let\do\@makeother \dospecials
			\verbatim@font\@noligs
			\catcode`\<13 \catcode`\>13 \def<{\begingroup$\langle$\itshape}\def>{\/$\rangle$\endgroup}%
			\@ifstar\@sverb\@verb}
\endgroup
\def\longfrscrdate@i#1/#2/#3\@nil{\number#3\relax\space \ifcase#2 \or janvier\or février\or mars\or avril\or mai\or juin\or juillet\or aout\or septembre\or octobre\or novembre\or décembre\fi\space#1}
\edef\longfrscrdate{\expandafter\longfrscrdate@i\scrdate\@nil}
\makeatother
\begingroup
	\catcode`\_11 
	\gdef\cleval#1#2{%
		\bigbreak\noindent
		\hbox to .25\linewidth{%
			\color{teal}\bfseries\ttfamily
			\detokenize{#1}=$\langle$\detokenize{#2}$\rangle$\hss}\kern2.5em 
		(\textit{Défaut} : {\color{teal}\ttfamily
		\hlst_eearg\hlst_ifempty{\useKV[scratch]{#1}}
			{\detokenize{{}}}
			{\detokenize\expandafter\expandafter\expandafter{\useKV[scratch]{#1}}}})%
		\par\nobreak
	}
\endgroup
\def\suffixe#1{\begingroup\sffamily\bfseries\color{scr#1}#1\endgroup}
\begin{document}
\parindent=0pt
\thispagestyle{empty}
\begin{titlepage}
	\begingroup
		\centering
		\null\vskip.25\vsize
		{\large\bfseries L'extension pour \LaTeX\par \Huge \scrname\par}
		\bigbreak
		v \scrver
		\smallbreak
		\longfrscrdate
		\vskip1.5cm
		Christian \bsc{Tellechea}\footnote{\texttt{unbonpetit@openmailbox.org}}\par
	\endgroup
	\vskip2cm
	\leftskip=.2\linewidth \rightskip=.2\linewidth \small
	Cette extension permet de dessiner des empilements de blocs similaires à ceux que l'on trouve dans le logiciel de programmation \emph{visuelle} « \SCRATCH\footnote{Le logiciel que l'on peut utiliser en ligne à \texttt{https://scratch.mit.edu/}} ».
\end{titlepage}
\parindent1.5em
\section{L'environnement \SCRATCH}
Pour dessiner un programme comme le fait \SCRATCH, il faut ouvrir un environnement «\SCRATCH» et écrire dans cet environnement les macros correspondant aux \emph{blocs} que l'on veut y mettre :

\code|\begin{scratch}
	macros pour dessiner des blocs
\end{scratch}|

Comme le savent ceux qui enseignent l'algorithmique et la programmation avec le très-à-la-mode logiciel « \SCRATCH », les programmes sont construits avec des briques, appelés «blocs», qui peuvent s'emboiter les uns sur les autres. Ces blocs sont de plusieurs couleurs, chacune correspondant à un type d'instruction que l'on retrouve dans les menus de \SCRATCH.

J'ai pris le parti d'écrire des macros ayant comme argument le texte qui figure dans le bloc. Ce faisant, on a plus de liberté que dans \SCRATCH où les blocs ont des textes prédéfinis, mais cette liberté permet d'utiliser cette extension quelle que soit la langue dans laquelle on écrit.

Enfin, j'ai cherché le bon compromis entre complexité du code et qualité des dessins obtenus avec cette extension: ils \emph{ressemblent} à ceux du logiciel \SCRATCH, mais le but de cette extension n'est \emph{pas} la ressemblance absolue au pixel près!

\section{Les blocs normaux}
Ces blocs sont les plus courants et possèdent une encoche d'emboitement, femelle en haut et mâle en bas. Les macros permettant de dessiner ces blocs ont des noms de la forme \verb|\block<suffixe>| et ont un seul argument obligatoire qui est le texte que l'on souhaite mettre dans le bloc. Par exemple, un bloc bleu (correspondant au menu «mouvement») a un suffixe \suffixe{move}, et est dessiné grâce à la macro \verb|\blocmove{<texte>}|. Ainsi, dans l'environnement \SCRATCH, écrire \verb|\blockmove{Bonjour le monde}| donne
\begin{center}\begin{scratch}\blockmove{Bonjour le monde}\end{scratch}\end{center}

La police d'écriture dans chaque bloc est la police « \textsf{sans serif} » en gras qui est définie dans le document au moment où l'environnement est appelé : pratiquement, cela signifie que les macros \verb|\sffamily| et \verb|\bfseries| sont exécutées avant que le texte des blocs ne soit composé. Dans cette documentation, la police sans serif est «\textsf{biolinum}».

La plupart des dimensions des blocs sont proportionnelles à la taille de la police en cours. On peut donc jouer sur la taille de la police (via les classiques macros \verb|\small|, \verb|\large|, \verb|\footnotesize|, etc) pour modifier la taille des blocs.

Voici un inventaire des tous les blocs disponibles, empilés les uns sous les autres :

\exemple/Voici un algorithme bizarre : \begin{scratch}
	\blockmove{bloc de mouvement}
	\blocklook{bloc d'apparence}
	\blocksound{bloc de son}
	\blockpen{bloc de stylo}
	\blockvariable{bloc de variable}
	\blocklist{bloc de liste}
	\blockevent{bloc d'événement}
	\blockcontrol{bloc de contrôle}
	\blocksensing{bloc de capteur}
\end{scratch}/

Il faut donc retenir cette logique : les suffixes \suffixe{move}, \suffixe{look}, \suffixe{sound}, \suffixe{pen}, \suffixe{variable}, \suffixe{list}, \suffixe{event}, \suffixe{control} et \suffixe{sensing} correspondent aux couleurs des blocs. Il existe aussi le suffixe \suffixe{operator} qui n'a pas été montré précédemment puisqu'aucun bloc n'existe pour la fonction «opérateurs».

\section{Les ovales}
Les « ovales » sont, selon le code graphique de \SCRATCH, censés contenir des nombres. Lorsque ces nombres sont explicitement écrits en chiffres, ces ovales ont un fond blanc : \begin{center}\begin{scratch}\blockmove{ajouter \ovalnum{10} à x}\end{scratch}\end{center}
Les valeurs numériques sont parfois issues de valeurs prédéfinies auquel cas, une flèche de sélection doit apparaitre après le nombre prédéfini choisi : \begin{center}\begin{scratch}\blockmove{s'orienter à \ovalnum{180\selectarrownum}}\end{scratch}\end{center}

Au niveau des macros utilisées dans l'exemple plus bas :
\begin{itemize}
	\item la macro \verb|\ovalnum{<nombre>}| dessine un nombre dans un ovale à fond blanc;
	\item la macro \verb|\selectarrownum| trace la flèche de sélection;
	\item les macros \verb|\turnleft| et \verb|\turnright| dessinent des flèches de rotation dans les blocs \verb|\blockmove|.
\end{itemize}

\exemple/Ovales sur fond blanc : \begin{scratch}
	\blockmove{ajouter \ovalnum{10} à x}
	\blockmove{s'orienter à \ovalnum{180\selectarrownum}}
	\blockmove{tourner de \turnleft{} de \ovalnum{45} degrés}
	\blockcontrol{attendre \ovalnum{1} seconde}
	\blockpen{mettre l'intensité du stylo à \ovalnum{50}}
\end{scratch}/

Lorsque les \verb|<nombres>| sont contenus dans des variables, les ovales prennent alors la couleur de la fonction correspondant à ces variables. Les macros ont des noms de la forme \verb|\oval<suffixe>| et ont pour suffixe \suffixe{move}, \suffixe{look}, \suffixe{sound}, \suffixe{variable}, \suffixe{list}, \suffixe{sensing} et \suffixe{operator}.

Voici quelques exemples :
\exemple/Ovales divers : \begin{scratch}
	\blockmove{s'orienter à \ovalmove{direction}}
	\blocksound{ajouter \ovaloperator{\ovalnum{-0.5} * \ovalsound{volume}} au volume}
	\blockmove{glisser en \ovalsound{tempo} secondes à x: \ovalsensing{souris x}
	           y: \ovaloperator{\ovalnum{4} * \ovalsensing{souris y}}}
\end{scratch}

Toutes les macros ayant pour préfixe \verb|\oval| sont utilisables \emph{en dehors} de l'environnement \texttt{scratch}, la preuve : voici \ovalvariable{une variable} et \ovaloperator{un opérateur}./

\section{Les blocs de début}
Ces blocs sont de la couleur \suffixe{event} pour la plupart (macro \verb|\blockinit|), mais il existe aussi un bloc de début de couleur \suffixe{control} (macro \verb|\blockinitclone|). Le drapeau vert est dessiné avec la macro \verb|\greenflag|.

\exemple/Voici un début :
\begin{scratch}
	\blockinit{quand \greenflag est cliqué}
	\blockmove{suite de l'algorithme...}
\end{scratch}
et un autre :
\begin{scratch}
	\blockinitclone{quand je commence comme un clone}
	\blocklook{enfiler le costume de clown !}
\end{scratch}/

\section{Les rectangles}
Du texte spécifié par l'utilisateur se trouve dans un rectangle sur fond blanc, en graisse normale et en couleur noir. La macro \verb|\txtbox{<du texte>}| permet, dans l'environnement \SCRATCH d'insérer ces rectangles « de texte »:

\exemple/\begin{scratch}
	\blocklook{dire \txtbox{Hello} pendant \ovalnum{2} secondes}
	\blocksensing{demander \txtbox{Quel est votre nom ?} et attendre}
\end{scratch}/

Un menu déroulant ayant des valeurs prédéfinies est également symbolisé par un rectangle dont la couleur reprend la fonction du bloc qui le contient. Pour ce faire, la macro \verb|\selectmenu{<texte>}| doit être exécutée :

\exemple/\begin{scratch}
	\blockinit{Quand je reçois \selectmenu{message 1}}
	\blockcontrol{créer un clone de \selectmenu{moi même}}
	\blockmove{aller à \selectmenu{pointeur de souris}}
	\blocklook{ajouter à l'effet \selectmenu{couleur} \ovalnum{25}}
\end{scratch}/

Un carré rempli de couleur et accessible avec la macro \verb|\squarecolor{<couleur>}| achève cet inventaire sur les rectangles :

\exemple/\begin{scratch}
	\blockpen{stylo en position d'écriture}
	\blockpen{mettre la couleur du style à \squarecolor{red!75!black}}
	\blockmove{avancer de \ovalnum{25}}
\end{scratch}/

\section{Les losanges et les blocs de test}
Dans la symbolique graphique de \SCRATCH, les losanges contiennent des valeurs booléennes ayant vocation à se retrouver dans un bloc de test. Pour dessiner de tels objets booléens, les macros \verb|\bool<suffixe>{<texte>}| sont utilisées où les \verb|<suffixes>| représentent les couleurs correspondant à la fonction du booléen tracé : \suffixe{list}, \suffixe{sensing} ou \suffixe{operator}.

Les blocs de test sont de deux types,selon qu'ils possèdent ou pas une branche « else».
\code|\blocif{<texte du test>}
	{<instructions si test vrai>}|
et
\code|\blocifelse{<texte du test>}
	{<instructions si test vrai>}
	{<instructions si test faux>}|


\exemple/Conditions :\begin{scratch}
	\blockif{si \booloperator{\ovalmove{abscisse x} < \txtbox{7}} alors}
		{\blockmove{aller à \selectmenu{position aléatoire}}
		 \blocklook{basculer sur costume \selectmenu{costume 4}}
		}
	\blockmove{aller à \selectmenu{pointeur souris}}
\end{scratch}
et
\begin{scratch}
	\blockifelse{si \boolsensing{couleur \squarecolor{blue!65} touchée ?} alors}
		{\blockmove{avancer de \ovalnum{2}}
		\blocksound{jouer le son \selectmenu{miaou}}
		}
		{\blockvariable{mettre \ovalvariable{total} à \ovaloperator{\ovalvariable{total} + \ovalnum{1}}}
		\blocksound{arrêter tous les sons}
		}
	\blockmove{aller à \selectmenu{pointeur souris}}
\end{scratch}/

Les macros \verb|\squarecolor| et celles de la forme \verb|\bool<suffixe>| sont utilisables \emph{en dehors} d'un environnement \SCRATCH :

\exemple/Une couleur : \squarecolor{cyan}.\par
Un booléen : \boollist{liste \selectmenu{malist} contient \txtbox{foobar}}.\par
Un autre : \booloperator{\booloperator{\ovalvariable{varx} > \txtbox{1}}
et \booloperator{\ovalvariable{varx} < \txtbox{5}}}./

\section{Les blocs de fin}
Ces blocs sont susceptibles de clore un algorithme et n'ont donc pas d'encoche mâle dans leur partie basse. Ils ne peuvent être que du type \suffixe{control} et sont dessinés avec la macro \verb|\blockstop{<texte>}|

\exemple/\begin{scratch}\blockstop{supprimer ce clone}\end{scratch}
ou
\begin{scratch}\blockstop{stop \selectmenu{ce script}}\end{scratch}/

\section{Les blocs de répétition}
Ces blocs sont de deux types, selon que la répétition est prévue pour s'arrêter ou pas (boucle infinie). Ils seront dessinés par les macros \verb|\blockrepeat| et \verb|\blocinfloop| ayant chacune \emph{deux} arguments : le premier étant le \verb|<texte>| du bloc et le second la suite d'instructions à répéter.

\exemple/\begin{scratch}
	\blockpen{stylo en position d'écriture}
	\blockrepeat{répéter \ovalnum{4} fois}
		{
		\blockmove{avancer de \ovalnum{10}}
		\blockmove{tourner \turnright{} de \ovalnum{90} degrés}
		}
\end{scratch}
et
\begin{scratch}
	\blockpen{stylo en position d'écriture}
	\blockinfloop{répéter indéfiniment}
		{
		\blockmove{s'orienter à \ovaloperator{nombre aléatoire entre \ovalnum{0} et \ovalnum{359}}}
		\blockmove{avancer de \ovaloperator{nombre aléatoire entre \ovalnum{1} et \ovalnum{10}}}
		\blockif{si \boolsensing{\selectmenu{bord} touché?}}
			{
			\blockmove{aller à x: \ovalnum{0} y: \ovalnum{0}}
			}
		}
\end{scratch}/

\section{Les blocs de définition}
Les « procédures », ayant le suffixe \suffixe{moreblocks}, permettent d'étendre les maigres possibilités données au programmeur en \SCRATCH.

\exemple/\begin{scratch}
	\initmoreblocks{définir \namemoreblocks{trace_carré \ovalmoreblocks{coté_carré}}}
	\blockrepeat{répéter \ovalnum4 fois}
		{\blockmove{avancer de \ovalmoreblocks{coté_carré}}
		\blockmove{tourner \turnleft{} de \ovalnum{90} degrés}
		}
\end{scratch}
puis
\begin{scratch}
	\blockinit{Quand \greenflag est cliqué}
	\blockpen{effacer tout}
	\blockpen{relever le stylo}
	\blockmove{aller à x: \ovalnum0 y: \ovalnum0}
	\blockmove{s'orienter à \ovalnum{90\selectarrownum} degrés}
	\blockpen{stylo en position d'écriture}
	\blockrepeat{répéter \ovalnum{10} fois}
		{
		\blockmoreblocks{trace carré \ovalnum{50}}
		\blockmove{avancer de \ovalnum{10}}
		\blockmove{tourner \turnleft{} de \ovalnum{36} degrés}
		}
\end{scratch}/

\section{Bloc invisible}
Bien que ce genre de bloc n'existe pas avec \SCRATCH, cette fonctionnalité peut s'avérer utile. On insère un espace vide avec \verb|\blockspace[<coeff>]|. L'espace verticale insérée est égale à la hauteur normale d'un bloc multipliée par le \verb|<coeff>|, valeur optionnelle qui vaut 1 par défaut.

\exemple/\begin{scratch}
	\blockmove{ci-dessous, une espace d'un bloc}
	\blockspace
	\blockmove{ci dessous, une espace égale à la moitié d'un bloc}
	\blockspace[0.5]
	\blockmove{la suite}
\end{scratch}/

\section{Personnalisation}
Plusieurs \verb|<paramètres>| peuvent être réglés par l'utilisateur selon la syntaxe \verb|<clé>=<valeur>|. Cas paramètres peuvent être spécifiés dans :

\begin{itemize}
	\item l'argument optionnel de l'environnement \verb|\begin{scratch}[<paramètres>]| auquel cas les \verb|<paramètres>| ne s'appliquent qu'à cet environnement;
	\item l'argument de la macro \verb|\setscratch{<paramètres>}| pour spécifier des \verb|<paramètres>| pour les environnements \SCRATCH à venir;
	\item l'argument de \verb|\setdefaultscratch{<paramètres>}| pour spécifier des \verb|<paramètres>| \emph{par défaut}.
\end{itemize}

Il existe la macro \verb|\resetscratch| qui remet à leur valeur par défaut tous les \verb|<paramètres>| de \SCRATCH, pour annuler les effets d'une macro \verb|\setscratch|.\bigbreak

Voici les \verb|<paramètres>| disponibles :

\cleval{else word}{caractères}
Représente est le mot qui est inséré dans la branche « else » d'un bloc de test.

\cleval{x sep}{dimension}
Représente l'espace horizontale insérée entre les bords droit et gauche du texte du bloc et les bords droits et gauche du bloc.

\cleval{y sepsup}{dimension}
Représente l'espace verticale insérée entre le bas de l'encoche femelle et le bord supérieur du texte du bloc.

\cleval{y sepinf}{dimension}
Représente l'espace verticale insérée entre le bas du bloc et le bord inférieur du texte du bloc.

\cleval{line width}{dimension}
Représente l'épaisseur des lignes de relief des blocs et le double des lignes de relief des losanges booléens.

\cleval{loop width}{dimension}
Représente est la largeur de la barre verticale des blocs de répétition ou de test.

\cleval{loop height}{dimension}
Représente est l'épaisseur des barres horizontales « else » et inférieure des blocs de répétition ou de test.

\cleval{corner}{dimension}
Représente la dimension des chanfreins des blocs. Cette dimension est utilisée proportionnellement pour le placement horizontal, l'épaisseur et la largeur des encoches des blocs.

\cleval{init arcangle}{angle}
Représente l'angle avec l'horizontale de l'arc de cercle tracé dans la partie haute des blocs de départ.

\cleval{init arclength}{dimension}
Représente la longueur horizontale de l'arc de cercle tracé dans la partie haute des blocs de départ.*

\cleval{moreblock arcangle}{angle}
Représente l'angle avec l'horizontale de l'arc de cercle tracé dans la partie haute des blocs de de type « moreblock».

\section{Mot de la fin}
Le code de cette extension démontre mon immense ignorance de ti\textit kz/pgf et les méthodes de programmation qui lui sont propres que, décidément, je ne comprendrai jamais! C'est sans doute le trop grand éloignement avec la logique de \TeX{} et la documentation de ti\textit kz/pgf, aussi indigeste qu'illisible, qui explique cette incompatibilité d'humeur et mon désintérêt à l'égard de ti\textit kz. Toujours est-il que cette extension fonctionne, avec une lenteur certaine que j'attribue à ma programmation hasardeuse ainsi qu'à la lenteur intrinsèque de ti\textit kz.

Toute remarque, remontée de bug ---~je n'ose pas dire amélioration du code~---, demande d'implémentation de fonctionnalité est bien évidemment bienvenue; j'invite les utilisateurs à m'en faire part \emph{via} email.
\end{document}