%% %% This is file `annee-scolaire-eng.tex', %% generated with the docstrip utility. %% %% The original source files were: %% %% annee-scolaire.dtx (with options: `doc,ENG') %% %% 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.6 2020-07-29 TdS $ {} \documentclass[full]{l3doc} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage[french,main=english]{babel} \usepackage{xparse} \usepackage[decalage=0]{annee-scolaire} \newcommand\BOP{\discretionary{}{}{}} \usepackage{xspace} \usepackage{csquotes} \usepackage{fancyvrb,fancyvrb-ex} \begin{document} \title{\pkg{annee-scolaire} user guide\thanks{This file describes version~\ExplFileVersion, last revised~\ExplFileDate. Special \emph{quarantine} edition.}} \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} A macro \cs{anneescolaire} to automatically write academic year (French way) according to the date of compilation day. \end{abstract} \noindent\hrulefill \begin{otherlanguage}{french} \begin{abstract} Une macro \cs{anneescolaire} pour écrire automatiquement l'année scolaire en fonction de la date du jour de compilation. La documentation française pour l'utilisateur de l'extension \pkg{annee-scolaire} est disponible sous le nom de \texttt{annee-scolaire-fra}. \end{abstract} \end{otherlanguage} \noindent\hrulefill \vspace{\baselineskip} \section{The Macros} \label{sec:macros} \pkg{annee-scolaire} offers three main document macros which produce text in the final document and one macro which is used to determine the presentation of the said text. \subsection{Main Macros} \label{sec:main} This package has three main document macros viz. \begin{function}{\anneescolaire} \begin{syntax} \cs{anneescolaire}\oarg{shift} \end{syntax} where \meta{shift} is an integer the default value of which is~\(0\). It is the number of years the academic year is shifted. The same optional argument with the same aim is available for the next two macros. \end{function} In French \foreignquote{french}{année scolaire} means \enquote{school year}. \begin{function}{\debutanneescolaire} \begin{syntax} \cs{debutanneescolaire}\oarg{shift} \end{syntax} \end{function} In French \foreignquote{french}{début d'année scolaire} means \enquote{beginning of school year}. \begin{function}{\finanneescolaire} \begin{syntax} \cs{finanneescolaire}\oarg{shift} \end{syntax} \end{function} In French \foreignquote{french}{fin d'année scolaire} means \enquote{end of school year}. See examples on page~\pageref{sec:writingyear}. \subsection{Presentation Macro} \label{sec:look} The presentation of the years as written by the three preceding commands may be changed redefining the following macro: \begin{function}{\AnneeScolairePresentation} \begin{syntax} \cs{AnneeScolairePresentation}\oarg{number}\marg{year} \end{syntax} where \meta{year} is a integer (a \LaTeX3 \texttt{\textit{int}}) which is the number of the year to be written in the document. The optional argument \meta{number} can be used to tailor the presentation according to the following scheme \begin{description} \item[\textbf{1}] presentation of the beginning year in the text created by the macro \cs{anneescolaire}; \item[\textbf{2}] presentation of the ending year in the text created by the macro \cs{anneescolaire}; \item[\textbf{3}] presentation of the year in the text created by the macro \cs{debutanneescolaire}; \item[\textbf{4}] presentation of the year in the text created by the macro \cs{finanneescolaire}. \end{description} By default, the macro is an alias of \cs{int_to_arabic:n}. % If you want to change the presentation, you have to redefine the command with \cs{RenewDocumentCommand}. \end{function} See examples on page \pageref{sec:changelook}. \section{The Package Options} \label{sec:keys} The package uses the key-value options. There are four keys: \texttt{premiermois} (\emph{first month}), \texttt{premierjour} (\emph{first day}), \texttt{decalage} (\emph{shift}) and \texttt{separateur} (\emph{separator}). \begin{description} \item[\texttt{premiermois} (\textit{\texttt{int}})] is the number of the first month of the school year. It defaults to~\(8\). \item[\texttt{premierjour} (\textit{\texttt{int}})] is the number of the first day of the first month of the school year. Its default value is~\(1\) so the school year begins, by default, on the first of August. \emph{Beware: no attempt is made in order to ensure the consistency of the chosen date --- you can chose the 32nd February if you dare. You have to take care of that by yourself.} \item[\texttt{decalage} (\textit{\texttt{int}})] is an integer which defaults to~\(0\). It is used to shift the school year: passing the option \verb|decalage=1| to the package forces \cs{anneescolaire} to give the next school year. \item[\texttt{separateur} (\textit{\texttt{token list}})] is the text used between the numbers of the two calendar years which the school year spans. Its default value is~\enquote{\texttt{-}}. \end{description} \section{Examples} \label{sec:examples} \subsection{Writing the School Year} \label{sec:writingyear} The text\\[0.5\baselineskip] \enquote{Today is \today, academic year \anneescolaire, beginning in~\debutanneescolaire{} and ending in~\finanneescolaire.}\\[0.5\baselineskip] is obtained with the code\\[0.5\baselineskip] \texttt{Today is \cs{today}, academic year \cs{anneescolaire}, beginning in}\verb|~|\cs{debutannee}\BOP \texttt{sco}\BOP \texttt{laire}\verb|{}| \texttt{and ending in\verb|~|\cs{finanneescolaire}.} \medskip{} What follows illustrates the use of the optional argument of the three document commands. \vspace{\baselineskip} \framebox[0.85\textwidth]{\begin{minipage}{.65\linewidth} \vspace*{.5\baselineskip} On \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{Changing the Look} \label{sec:changelook} With the following code: \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} We obtain: \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{} It should be obvious to everyone that the preceding code is given as a mere example of what we can do and certainly not as an example of what we \emph{have to}! \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-eng.tex'.