%%
%% This is file `annee-scolaire-fra.tex',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% annee-scolaire.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: annee-scolaire.dtx
%% Copyright (C) 2020 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}[2013/03/12]
\GetIdInfo$Id: annee-scolaire.dtx 1.5 2020-04-05 TdS $
  {}
\documentclass[full]{l3doc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english,main=french]{babel}
\usepackage{xparse}
\usepackage[decalage=0]{annee-scolaire}
\newcommand\BOP{\discretionary{}{}{}}
\usepackage{xspace}
\usepackage{csquotes}
\usepackage{fancyvrb,fancyvrb-ex}
\begin{document}
\title{Guide de l'utilisateur de \pkg{annee-scolaire}\thanks{Ce fichier
    décrit la version~\ExplFileVersion, dernière révision~\ExplFileDate. Édition
  spéciale \emph{confinement}.}}
\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 macro \cs{anneescolaire} pour écrire automatiquement l'année scolaire en
fonction de la date du jour de compilation.
\end{abstract}

\noindent\hrulefill

 \begin{otherlanguage}{english}
\begin{abstract}
A macro \cs{anneescolaire} to automatically write academic year (French way)
according to the date of compilation day.

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

\noindent\hrulefill
\vspace{\baselineskip}


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

L'extension \pkg{annee-scolaire} offrent quatre macros de document: trois macros
principales produisant du texte et une macro, qui ne devrait être utilisée que
rarement et peut-être même jamais, qui permet de changer la présentation du
texte écrit.

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

Les trois macros principales de document sont les suivantes:

\begin{function}{\anneescolaire}
  \begin{syntax}
    \cs{anneescolaire}\oarg{décalage}
  \end{syntax}
  où \meta{décalage} est un entier relatif qui vaut~\(0\) par défaut.  C'est le
  nombre d'années dont l'année scolaire est décalée. Les deux autres macros ont
  le même argument optionnel.
\end{function}

\begin{function}{\debutanneescolaire}
  \begin{syntax}
    \cs{debutanneescolaire}\oarg{décalage}
  \end{syntax}
\end{function}

Comme son nom l'indique, cette macro donne l'année de début de l'année scolaire.

\begin{function}{\finanneescolaire}
  \begin{syntax}
    \cs{finanneescolaire}\oarg{shift}
  \end{syntax}
\end{function}

Celle-ci donne l'année de fin.

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

\subsection{Changement de la présentation}
\label{sec:presentation}

La présentation des années obtenues à l'aide des trois macros précédentes peut
être modifiée en redéfinissant la macro \cs{AnneeScolairePresentation}:
\begin{function}{\AnneeScolairePresentation}
  \begin{syntax}
    \cs{AnneeScolairePresentation}\oarg{numéro}\marg{année}
  \end{syntax}
  où \meta{année} est un entier relatif (\texttt{\textit{int}} au sens de
  \LaTeX3), c'est le numéro de l'année à écrire dans le document. L'argument
  optionnel \meta{numéro} peut être utilisé pour traiter différemment la
  présentation suivant ce schéma
  \begin{description}
  \item[\textbf{1}] présentation de l'année de début dans le texte créé par la
    macro \cs{anneescolaire};
  \item[\textbf{2}] présentation de l'année de fin dans le texte créé par la
    macro \cs{anneescolaire};
  \item[\textbf{3}] présentation de l'année dans le texte créé par la
    macro \cs{debutanneescolaire};
  \item[\textbf{4}]  présentation de l'année dans le texte créé par la
    macro \cs{finanneescolaire}.
  \end{description}

  Par défaut, cette macro est définie comme un alias de \cs{int_to_arabic:n}.
  %
  Si l'on veut changer la présentation, il faut redéfinir cette commande à
  l'aide de \cs{RenewDocumentCommand}.
\end{function}

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


\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{premiermois}, \texttt{premierjour}, \texttt{decalage} et
\texttt{separateur}.

\begin{description}
\item[\texttt{premiermois} (\textit{\texttt{int}})] contient le numéro du 1\ier
  mois de l'année scolaire. Par défaut sa valeur est~\(8\);

\item[\texttt{premierjour} (\textit{\texttt{int}})] contient le numéro du 1\ier
  jour du 1\ier mois de l'année scolaire. Par défaut sa valeur est~\(1\). La
  date de début de l'année scolaire est donc le 1\ier aout;

  \emph{Attention: l'extension ne vérifie pas la validité de la date ainsi
    choisie --- choisir le 32 février ne provoquera pas d'erreur. L'utilisateur
    s'en assurera lui-même.}

\item[\texttt{decalage} (\textit{\texttt{int}})] est un entier relatif qui vaut
  \(0\) par défaut. Il permet de décaler l'année scolaire. En donnant l'option
  \verb|decalage=1| à l'extension on force \cs{anneescolaire} à donner l'année
  scolaire prochaine;

\item[\texttt{separateur} (\textit{\texttt{token list}})] est le texte utilisé
  entre les numéros des deux années civiles composant l'année scolaire. Par
  défaut sa valeur est \enquote{\texttt{-}}.
\end{description}


\section{Exemples}
\label{sec:exemples}

\subsection{Écrire l'année scolaire}
\label{sec:ecrireannee}

Le texte\\[0.5\baselineskip]
\enquote{Aujourd'hui est le \today, année scolaire \anneescolaire, débutant
  en~\debutanneescolaire{} et finissant en~\finanneescolaire.}\\[0.5\baselineskip]
est obtenu avec le code\\[0.5\baselineskip]
\texttt{Aujourd'hui} \texttt{est} \texttt{le} \cs{today}\texttt{,}
\texttt{année} \texttt{scolaire} \cs{anneescolaire}\texttt{,} \texttt{débutant}
\texttt{en}\verb|~|\cs{de}\BOP{}\texttt{but}\BOP \texttt{an}\BOP
\texttt{nee}\BOP \texttt{sco}\BOP \texttt{laire}\verb|{}| \texttt{et}
\texttt{finissant} \texttt{en}\verb|~|\cs{finanneescolaire}.

\medskip{}

La suite illustre l'utilisation de l'argument optionnel des trois commandes.

\vspace{\baselineskip}

\framebox[0.85\textwidth]{\begin{minipage}{.65\linewidth}
\vspace*{.5\baselineskip}

 Le
\today{}:

\vspace{.5\baselineskip}

\noindent{}
{\cs{anneescolaire[-1]}}: \anneescolaire[-1] \par\noindent{}
{\cs{debutanneescolaire[-1]}}: \debutanneescolaire[-1] \par\noindent{}
{\cs{finanneescolaire[-1]}}: \finanneescolaire[-1]

\vspace{.5\baselineskip}

\noindent{}
{\cs{anneescolaire}}: \anneescolaire \par\noindent{}
{\cs{debutanneescolaire}}: \debutanneescolaire \par\noindent{}
{\cs{finanneescolaire}}: \finanneescolaire

\vspace{.5\baselineskip}

\noindent{}
{\cs{anneescolaire[1]}}: \anneescolaire[1] \par\noindent{}
{\cs{debutanneescolaire[1]}}: \debutanneescolaire[1] \par\noindent{}
{\cs{finanneescolaire[1]}}: \finanneescolaire[1]

\vspace*{.5\baselineskip}
\end{minipage}}


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

Avec le code suivant:


\begin{Verbatim}[gobble=0, frame=lines, label={code}, labelposition=topline]
\ExplSyntaxOn
\RenewDocumentCommand{\AnneeScolairePresentation}{ o m }
{
  \int_case:nn { #1 }
  {
    {1} { \textbf{ \int_to_arabic:n { #2 } } }
    {2} { \int_to_roman:n { #2 } }
    {3} { \textit{ \int_to_arabic:n { #2 } } }
    {4} { \int_to_Roman:n { #2 } }
  }
}
\ExplSyntaxOff

\anneescolaire \quad \debutanneescolaire \quad \finanneescolaire
\end{Verbatim}

 Nous obtenons:

\bgroup{}
\ExplSyntaxOn
\RenewDocumentCommand{\AnneeScolairePresentation}{ o m }
{
  \int_case:nn { #1 }
  {
    {1} { \textbf{ \int_to_arabic:n { #2 } } }
    {2} { \int_to_roman:n { #2 } }
    {3} { \textit{ \int_to_arabic:n { #2 } } }
    {4} { \int_to_Roman:n { #2 } }
  }
}
\ExplSyntaxOff

\anneescolaire \quad \debutanneescolaire \quad \finanneescolaire
\egroup{}

\medskip{}

Je n'ai pas besoin, je pense, d'insister sur le caractère de pur exemple du code
qui précède. Il ne viendra à l'esprit de personne d'y voir un encouragement à la
\emph{créativité typographique}!

\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 `annee-scolaire-fra.tex'.
