%%
%% This is file `simples-matrices-fra.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% simples-matrices.dtx  (with options: `doc,FRA')
%% 
%% Do not distribute this file without also distributing the
%% source files specified above.
%% 
%% Do not distribute a modified version of this file.
%% 
%% File: simples-matrices.dtx
%% Copyright (C) 2022 Yvon Henel aka Le TeXnicien de surface
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
\RequirePackage{expl3}[2020/01/12]
\GetIdInfo$Id: simples-matrices.dtx 1.0 2022-06-19 TdS $
  {}
\documentclass[full]{l3doc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english,main=french]{babel}
\usepackage{xparse}
\usepackage{simples-matrices}
\newcommand\BOP{\discretionary{}{}{}}
\usepackage{xspace}
\usepackage{csquotes}
\usepackage{fancyvrb,fancyvrb-ex}
\usepackage{mathtools}
\usepackage{delarray}
\usepackage{nicematrix}

\providecommand\darg[3]{ \texttt{#1} \meta{#2} \texttt{#3} }

\newcommand{\UnExemple}{%
  \par \medskip \par \noindent
  \begin{minipage}[c]{0.58\linewidth}
    \VerbatimInput[gobble=0, frame=single]{code00.tex}
  \end{minipage}
  \hspace{\stretch{1}}
  \begin{minipage}[c]{0.38\linewidth}
    \input{code00}
  \end{minipage}
  \par \medskip}

\begin{document}
\title{Guide de l'utilisateur de \pkg{simples-matrices}\thanks{Ce fichier décrit
    la version~\ExplFileVersion, dernière révision~\ExplFileDate.\\
    \emph{En souvenir de ma grand-mère maternelle}, Adrienne \textsc{Binaut}
    (1908-03-23 -- 1997-06-08).}  }
\author{Yvon Henel\thanks{E-mail:
    \href{mailto:le.texnicien.de.surface@yvon-henel.fr}
    {le.texnicien.de.surface@yvon-henel.fr}}}
\maketitle
\noindent\hrulefill

\begin{abstract}
Une extension pour écrire des matrices en donnant les coefficients par ligne
sous la forme d'une liste de valeurs séparées par des virgules.

Une macro permet de définir des matrices nommées et une autre permet d'écrire
les matrices nommées. L'extension fournit également quelques raccourcis pour les
matrices identité et les matrices nulles.
\end{abstract}

\noindent\hrulefill

 \begin{otherlanguage}{english}
\begin{abstract}
A package to write matrices which are defined with a list of comma separated
coefficients read by row.

A macro enables the definition of a named matrix, another enables the writing of
a named matrix. This package provides also some shortcuts for identity matrices
and null matrices.

The name of this package and of its macros are French based for there are
already too many macros using the word ``matrix'' itself. The French
``\foreignlanguage{french}{simples matrices}'' means ``simple
matrices''. \emph{Just a letter apart!}

The English documentation for the final user of the package
\pkg{simples-matrices} is available in the file \texttt{simples-matrices-eng}.
\end{abstract}
\end{otherlanguage}

\noindent\hrulefill

\tableofcontents{}

\vspace{3\baselineskip}

L'extension \pkg{simples-matrices} utilise \pkg{xparse} et \pkg{l3keys2e} pour
définir ses macros et gérer les clés d'option. Elle charge également
\pkg{amsmath} pour obtenir une présentation convenable des matrices.

\textbf{Attention}: vous devez fournir l'environnement mathématique adéquat pour
utiliser les macros qui écrivent les matrices. Seule la version non-étoilée de
\cs{declarermatrice} peut être utilisée en dehors du mode mathématique.

\section{Les macros}
\label{sec:macros}

L'extension \pkg{simples-matrices} offre six macros de document.


\subsection{Macros principales}
\label{sec:principales}

Les cinq macros principales de document sont les suivantes:

\begin{function}{\matrice}
  \begin{syntax}
    \cs{matrice}\parg{prefixe}\darg{\string<}{vliste de paires de clé-valeur}{\string>}\oarg{type}\marg{vliste des coefficients}
  \end{syntax}
  où \meta{prefixe} a la même fonction que la clé \texttt{prefix}; \meta{vliste
    de paires de clé-valeur}, optionnel et vide par défaut, peut être utiliser
  pour redéfinit l'environnement de type \texttt{matrix};
  \meta{type} est une chaine de caractère dont l'utilisation sera expliquée
  ci-dessous --- voir~\ref{sec:matrix-type} --- et \meta{vliste des
    coefficients} est la vliste des coefficients de la matrice donnés ligne par
  ligne.

  Avec \verb+\(\matrice{1, 2, 3, 4}\)+ on obtient \(\matrice{1, 2, 3, 4}\).

  Avec \verb+\(\matrice(b)[3]{1, 2, 3, 4, 5, 6}\)+
  on obtient \(\matrice(b)[3]{1, 2, 3, 4, 5, 6}\).

\end{function}

\begin{function}{\declarermatrice}
  \begin{syntax}
    \cs{declarermatrice*}\parg{prefix}\darg{\string<}{vliste de paires de clé-valeur}{\string>}\marg{nom}\oarg{type}\marg{vliste des coefficients}
  \end{syntax}
  où \meta{nom} est le nom de la matrice pour utilisation future. Les autres
  arguments, optionnels ou obligatoires, ont la même signification que
  ci-dessus. La version étoilée définit et écrit la matrice. La version
  non-étoilée ne fait que la définir.

  La définition est global mais on peut redéfinir une matrice nommée existante
  avec la même fonction. \textbf{Aucun contrôle} n'est exercé pour s'assurer que
  l'on n'est pas en train de redéfinir une matrice nommée précédemment définie.
\end{function}

\begin{function}{\lamatrice}
  \begin{syntax}
    \cs{lamatrice}\parg{prefix}\darg{\string<}{vliste de paires de clé-valeur}{\string>}\marg{matrix name}
  \end{syntax}
  écrit la matrice nommée de nom \meta{nom}.
  Les deux arguments optionnels ont la même signification que ci-dessus.
\end{function}

\begin{function}{\MatriceInterieur}
  \begin{syntax}
    \cs{MatriceInterieur}
  \end{syntax}
  donne l'intérieur de la dernière matrice écrite --- via \cs{matrice} --- ou
  définie --- via \cs{declarermatrice}. On peut l'utiliser dans un environnement
  du genre \env{array}.
\end{function}

\begin{function}{\LaMatriceInterieur}
  \begin{syntax}
    \cs{LaMatriceInterieur}\marg{nom}
  \end{syntax}
  donne l'intérieur de la matrice de nom \meta{nom}. On peut l'utiliser dans un
  environnement du genre \env{array}.
\end{function}

Voir les exemples en page~\pageref{sec:exemples}.

\subsection{Valuer les clés}
\label{sec:setting-keys}

On peut changer les valeurs des clés de \pkg{simples-matrices} avec
\begin{function}{\simplesmatricessetup}
  \begin{syntax}
    \cs{simplesmatricessetup}\marg{vliste de paires de clé-valeur}
  \end{syntax}
  où \meta{vliste de paires de clé-valeur} est l'habituelle vliste de paires de
  clé-valeur valuant une ou plusieurs des trois clés de cette extension
  telles que présentées ci-dessous en page~\pageref{sec:clefs}.

  Pour suivre une convention désormais bien établie le nom de cette macro
  consiste en le nom de l'extension --- réduite à ces lettres \TeX{}iennes ---
  suivi de l'anglais \emph{setup}. Je demande pardon pour cette étrange mixture
  linguistique.

\end{function}
\subsection{Raccourcis}
\label{sec:shortcuts}

L'extension propose deux macros \emph{raccourcis}:

\begin{function}{\matid}
  \begin{syntax}
    \cs{matid}\parg{prefix}\darg{\string<}{vliste de paires de clé-valeur}{\string>}\oarg{coefficient}\marg{nombre de colonnes}
  \end{syntax}
  qui imprime la matrice identité --- par défaut --- avec
  \meta{nombre de colonnes} colonnes.
  Si \meta{coefficient} est fourni, on obtient une matrice diagonale
  dont tous les coefficients non-nuls sont égaux à \meta{coefficient}.

  Les deux premiers arguments optionnels ont la même fonction que dans les
  macros précédentes.
\end{function}

\begin{function}{\matnulle}
  \begin{syntax}
    \cs{matnulle}\parg{prefix}\darg{\string<}{vliste de paires de clé-valeur}{\string>}\oarg{coefficient}\marg{nombre de colonnes}
  \end{syntax}
  imprime la matrice nulle \meta{nombre de colonnes} colonnes --- par défaut ---
  ou une matrice de \meta{nombre de colonnes} colonnes dont tous les
  coefficients sont égaux à \meta{coefficient}.

  Les deux premiers arguments optionnels ont la même fonction que dans les
  macros précédentes.
\end{function}

\begin{VerbatimOut}[gobble=0]{code00.tex}
\(\matid{3}\)\qquad \(\matid[9]{3}\)
\par \medskip
\(\matnulle{3}\)\qquad \(\matnulle[2]{3}\)
\end{VerbatimOut}
\UnExemple{}


\section{Les options de l'extension}
\label{sec:clefs}

L'extension utilise le système de clefs-valeurs pour ses options. Elle possède
quatre clés: \texttt{envir}, \texttt{prefix}, \texttt{typeord} et \texttt{argopt}.

\begin{description}
\item[\texttt{envir} (\textit{\texttt{chaine de caractères}})] la partie finale
  du nom de l'environnement utilisé pour imprimer la matrice. Sa valeur initiale
  est \texttt{matrix}.

\item[\texttt{prefix} (\textit{\texttt{chaine de caractères}})], caractères
  placés devant \texttt{envir} pour fournir le nom complet de l'environnement
  utilisé pour imprimer la matrice. Sa valeur initiale est \texttt{p}. Cela fait
  que l'environnement par défaut est \texttt{pmatrix} fourni par \pkg{amsmath}.

\item[\texttt{typeord} (\textit{\texttt{chaine de caractères}})] définit la
  valeur ordinaire --- c.-à-d. par défaut --- de l'argument optionnel
  \meta{type}. La valeur initiale de la clé est \texttt{C}.

\item[\texttt{argopt} (\textit{\texttt{liste de lexèmes}}, anglais:
  \foreignlanguage{english}{token list})]. Cette clé est vide par défaut. Voir
  page~\pageref{sec:delarray} pour son utilisation.
\end{description}

De plus, une clé supplémentaire existe qui est une métaclé:
\texttt{out-of-box}.

Avec |\simplesmatricessetup{out-of-box}| on obtient le même effet qu'avec
|\simplesmatricessetup{prefix=p,|\BOP| envir=matrix,|%
  \BOP| argopt=,|\BOP| typeord=C}|.

\section{Exemples}
\label{sec:exemples}
\subsection{Sans extension particulière}
\label{sec:amsmath}

C'est-à-dire en chargeant uniquement \pkg{amsmath} comme le fait cette extension.

\subsubsection{Déclaration et utilisation}
\label{sec:declar}

\begin{VerbatimOut}[gobble=0]{code00.tex}
\declarermatrice{A}{1, 2, 300, 400}
\(\declarermatrice*{B}{a, b, c, d}\)
\qquad \(\lamatrice{A}\) \par \bigskip
\(\lamatrice(V){A}\)
\qquad \(\lamatrice(b){B}\)
\end{VerbatimOut}
\UnExemple{}


\subsubsection{L'argument \og \texttt{type}\fg}
\label{sec:matrix-type}

L'avant dernier argument --- optionnel --- des macros \cs{matrice} et
\cs{declarermatrice} vaut par défaut \texttt{O}. Dans ce cas, c'est la valeur de
la clé \texttt{typeord} qui est utilisée pour déterminer le \emph{type} des
données de la matrice, voir~\pageref{sec:matrix-type-key}.

Sinon, il peut prendre une valeur numérique qui est le nombre de colonnes de la
matrice ou encore une chaine de caractères --- à ce jour, une seule lettre ---
parmi: \texttt{C}, \texttt{D}, \texttt{I}, \texttt{J}, \texttt{S}, \texttt{T} et
\texttt{x}.

\medskip{}

 \texttt{C} signifie matrice \textbf{carrée}.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
\matrice{1, 2, 3, 4, 5, 6, 7, 8, 9}
\qquad
\matrice[C]{1, 2, 3, 4, 5, 6, 7, 8, 9}
\]
\end{VerbatimOut}
\UnExemple{}

 \texttt{D} signifie matrice \textbf{diagonale}.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
  \matrice{1, 2, 3, 4}\qquad
  \matrice[D]{1, 2, 3, 4}
\]
\end{VerbatimOut}
\UnExemple{}

\texttt{I} signifie matrice triangulaire \textbf{inférieure}; \texttt{J}
signifie matrice triangulaire inférieure avec des zéros sur la diagonale.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
  \matrice[I]{1, 2, 3}\qquad
  \matrice[J]{1, 2, 3}
\]
\end{VerbatimOut}
\UnExemple{}

\texttt{S} signifie matrice triangulaire \textbf{supérieure}; \texttt{T}
signifie matrice triangulaire supérieure avec des zéros sur la diagonale.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
  \matrice[S]{1, 2, 3}\qquad
  \matrice[T]{1, 2, 3}
\]
\end{VerbatimOut}
\UnExemple{}

\texttt{x} signifie \texttt{xcas}. Avec cette valeur, on peut copier-coller de
\texttt{xcas} dans le document \LaTeX{}.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
  \matrice[x]{[[7,1,3],[1,0,3],[5,1,2]]}
\]
\end{VerbatimOut}
\UnExemple{}

Un nombre donne le nombre de colonnes de la matrice.
\begin{VerbatimOut}[gobble=0]{code00.tex}
\[
  \matrice[2]{1, 2, 3, 4, 5, 6}
  \quad
  \matrice[3]{1, 2, 3, 4, 5, 6}
\]
\end{VerbatimOut}
\UnExemple{}


\subsubsection{Utilisation de la clé \og \texttt{typeord}\fg}
\label{sec:matrix-type-key}

Dans ce document, la clé \texttt{typeord} a comme valeur initiale~\texttt{C}.

\medskip{}

\begin{VerbatimOut}[gobble=0]{code00.tex}
\simplesmatricessetup{typeord=3}
\(\matrice{1, 2, 3, 4, 5, 6}\)
\simplesmatricessetup{typeord=2}
\(\matrice{1, 2, 3, 4, 5, 6}\)
\simplesmatricessetup{typeord=C}
\(\matrice{1, 2, 3, 4}\)
\end{VerbatimOut}
\UnExemple{}

Le code précédent n'est, bien entendu, donné qu'à titre d'illustration. Pour une
déclaration de type ne concernant qu'une seule matrice, on aura intérêt à
utiliser l'argument optionnel. Cependant si on veut rédiger un cours sur les
matrices triangulaires supérieures\dots{}

\subsubsection{Utilisation des macros \cs{(La)MatriceInterieur}}
\label{sec:matint}

\begin{VerbatimOut}[gobble=0]{code00.tex}
\declarermatrice{B}[4]{
\hline ein, zwei, drei, vier,
\hline unos, dos, tres, cuatro,
\hline unu, du, tri, kvar}
\declarermatrice{A}[3]{one, two, three,
un, deux, trois, uno, due, tre}
\begin{tabular}{*{3}{l}}
\MatriceInterieur
\end{tabular}
\par \medskip
\begin{tabular}{|*{4}{l|}}
\LaMatriceInterieur{B}\hline
\end{tabular}
\end{VerbatimOut}
\UnExemple{}


\subsection{Changer l'aspect}
\label{sec:aspect}

On peut charger d'autres extensions qui permettent de présenter des matrices
comme \pkg{mathtools}, \pkg{delarray} ou \pkg{nicematrix}. Dans ce cas on peut
changer l'aspect de nos matrices grace aux clés d'option \texttt{envir},
\texttt{prefix} et \texttt{argopt}.

Ce document charge les trois extensions \pkg{mathtools}, \pkg{delarray} et
\pkg{nicematrix} pour présenter les exemples suivants.


\subsubsection{Avec \pkg{mathtools}}
\label{sec:mathtools}

Comme déjà signalé, il y a deux façons d'utiliser les clés d'option: à l'aide de
\cs{simplesmatricesetup} ou en utilisant l'argument optionnel
\darg{\string<}{vliste de paires de clé-valeur}{\string>}.  Je montre les deux.


\begin{VerbatimOut}[gobble=0]{code00.tex}
\simplesmatricessetup{
  envir=matrix*, prefix=p, argopt=[r]}
\(\matrice{1, 2, 30, 40}\) \qquad
\simplesmatricessetup{out-of-box}
\(\matrice{1, 2, 30, 40}\)
\par \medskip
\(\matrice(b)<envir=matrix*, argopt=[l]>
    {1, 2, 30, 40}\)
\end{VerbatimOut}
\UnExemple{}

\subsubsection{Avec \pkg{delarray}}
\label{sec:delarray}


\begin{VerbatimOut}[gobble=0]{code00.tex}
\simplesmatricessetup{
  envir=array, prefix=,
  argopt=[c][{l c r}\}}
\(\matrice{1, 2, 30, 40}\) \qquad
\(\matid()<envir=array,
  argopt={[c][{@{}l c r@{}}\}}>{3}\)
\end{VerbatimOut}
\UnExemple{}
\simplesmatricessetup{out-of-box}

\subsubsection{Avec \pkg{nicematrix}}
\label{sec:nicematrix}

\begin{VerbatimOut}[gobble=0]{code00.tex}
\(\matrice<prefix=b, envir=NiceArray,
argopt={{*{2}{c}|cc}}>{1, 2, 3, 4, 5, 6,
7, 8, 9, 10, 11, 12, 13, 14, 15, 16}\)
\end{VerbatimOut}
 %| emacs
\UnExemple{}

Dans ce cas il faut doubler les accolades entourant les descripteurs de colonnes
de l'environnement \texttt{array} car \LaTeX{} retire un niveau d'accolades en
valuant la clé.

Dans l'exemple suivant, pour la deuxième matrice, il n'est pas nécessaire
d'entourer la valeur de \texttt{argopt} d'une paire d'accolades --- même si ça
n'est pas dangereux --- car la présence de \texttt{[margin]} empêche \LaTeX{} de
supprimer une paire d'accolades.

\begin{VerbatimOut}[gobble=0]{code00.tex}
\(\matrice<prefix=b, envir=NiceArray,
argopt={{l c r}}>{1, 2, 3, 40, 50, 60,
  700, 800, 900}\)
\par \medskip
\(\matrice<prefix=b, envir=NiceArray,
argopt={l c r}[margin]>{1, 2, 3,
  40, 50, 60, 700, 800, 900}\)
\par \medskip
\(\matrice<prefix=b, envir=NiceArray,
argopt={{l c r}[margin]}>{1, 2, 3,
  40, 50, 60, 700, 800, 900}\)
\end{VerbatimOut}
\UnExemple{}

\vspace{\stretch{2}}

\noindent\hspace*{0.2\textwidth}\hrulefill\hspace*{0.2\textwidth}
\begin{center}
  \textsl{Le TeXnicien de Surface scripsit.}
\end{center}
\noindent\hspace*{0.2\textwidth}\hrulefill\hspace*{0.2\textwidth}

\vspace*{\stretch{2}}

\end{document}
\endinput
%%
%% End of file `simples-matrices-fra.tex'.