exercice.dtx

% \iffalse meta-comment
% vim: textwidth=75
%<*internal>
\iffalse
%</internal>
%<*readme>
|--------:| ----------------------------------------------------------------
|exercice:| This package configures and extends the exercise package.
|  Author:| Arnaud Malapert
|  E-mail:| arnaud.malapert@univ-cotedazur.fr
| License:| Released under the LaTeX Project Public License v1.3c or later
|     See:| http://www.latex-project.org/lppl.txt


Short description:
This package configures and extends the exercise package for typesetting examination papers.
It allows to prepare two versions of the examination paper along with its correction.
The user must redefine a few commands for specifying general information about the course and the examination.
The package defines custom formatting (title, headers, margins) for the different versions of the document.
It also provides user commands for examination papers such as answer placeholders.
Last, an export command allows to easily export all versions of the document at once. 
%</readme>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
--------:| ----------------------------------------------------------------
exercice:| This package configures and extends the exercise package.
  Author:| Arnaud Malapert
  E-mail:| arnaud.malapert@univ-cotedazur.fr
 License:| Released under the LaTeX Project Public License v1.3c or later
     See:| http://www.latex-project.org/lppl.txt

\endpreamble
\postamble

Copyright (C) 2019-2020 by Arnaud Malapert <arnaud.malapert@univ-cotedazur.fr>

This work 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

This work is "maintained" (as per LPPL maintenance status) by
Arnaud Malapert.

This work consists of the file exercice.dtx, the file exercice-example.tex, and a Makefile.
Running "make" generates the derived files README, exercice.pdf and exercice.cls.
Running "make inst" installs the files in the user's TeX tree.
Running "make install" installs the files in the local TeX tree.

\endpostamble

\usedir{tex/latex/exercice}
\generate{
  \file{\jobname.cls}{\from{\jobname.dtx}{class}}
}
%</install>
%<install>\endbatchfile
%<*internal>
\usedir{source/latex/exercice}
\generate{
  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\nopreamble\nopostamble
\usedir{doc/latex/exercice}
\generate{
  \file{README.txt}{\from{\jobname.dtx}{readme}}
}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{exercice.dtx}
%</driver>
%<class>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<class>\ProvidesClass{exercice}
%<*class>
    [2020/03/23 v1.00 porting the previous class (cls) to a documented source file (dtx).]
%</class>
%<*driver>
\documentclass{ltxdoc}
\usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry}
\usepackage[numbered]{hypdoc}

\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{\jobname.dtx}
% \DoNotIndex{\newcommand,\newenvironment}
%
%\title{\textsf{exercice} --- configure and extend the exercise package.\thanks{This file
%   describes version \fileversion, last revised \filedate.}
%}
%\author{Arnaud Malapert\thanks{E-mail: arnaud.malapert@univ-cotedazur.fr}}
%\date{Released \filedate}
%
%\maketitle
%
%\changes{v1.00}{2020/03/23}{First public release}
%
% \begin{abstract}
% This package configures and extends the \textsf{exercise} package for typesetting examination papers.
% It allows to prepare two versions of the examination paper along with its correction.
% The user must redefine a few commands for specifying general information about the course and the examination.
% The package defines custom formatting (title, headers, margins) for the different versions of the document.
% It also provides user commands for examination papers such as answer placeholders.
% Last, an export command allows to easily export all versions of the document at once. 
% \end{abstract}
%
% \section{Usage}
%
% In this section, we briefly recall the usage of the most used commands when typesettting an exam.
% Package options are described in Section~\ref{sec:options}.
% Commands that configure the different placeholders are described in Section~\ref{sec:info}.
% The command that configure the default export of the examination and correction papers are described in Section~\ref{sec:export}. \\
% \DescribeMacro{\Versions}
% The macro |\Versions|\marg{textA} \marg{textB} allows to typeset simultaneously two versions of the document.
% Only one argument is written depending of the version of the document (A or B). \\
% \DescribeMacro{\ExamLines}
% The macro |\ExamLines|\marg{nbLines} prints \meta{nbLines} lines for writing the answer to a question on the examination paper. \\
% \DescribeMacro{\ExamGrid}
% The macro |\ExamGrid|\marg{nbLines} prints a fullwidth grid with \meta{nbLines} lines for writing the answer to a question on the examination paper. \\
% Now, let's describre two last commands used less frequently. \\
% \DescribeMacro{\ExamNewpage}
% The macro simply calls |\clearpage| in exam mode. \\
% \DescribeMacro{\ExamOnly}
% The macro simply calls |\ExamOnly|\marg{text} only prints \meta{text} in exam mode.
%
%\StopEventually{
%  \PrintChanges
%  \PrintIndex
%}
%
% \section{Implementation}
%
%    \begin{macrocode}
%<*class>
\LoadClass[a4paper]{article}
%    \end{macrocode}

% \subsection{Class Options}
% \label{sec:options}
% Options are passed to the \textsl{exercise} package.
% The package uses three additional options: |exam|; |versionB|; |nograde|. \\
% The option |exam| indicates that the document is an examination paper, and not a correction.
%    \begin{macrocode}
\newif\ifExamOutput \ExamOutputfalse
\DeclareOption{exam}{\ExamOutputtrue}
%    \end{macrocode}
% The option |versionB| indicates that the version of the document is B (default is A). 
%    \begin{macrocode}
\newif\ifVersionA \VersionAtrue
\DeclareOption{versionB}{\VersionAfalse}
%    \end{macrocode}
% The option |nograding| cancels the display of the grading table in the examination paper.
%    \begin{macrocode}
\newif\ifGradingOutput \GradingOutputtrue
\DeclareOption{nograding}{\GradingOutputfalse}
%    \end{macrocode}
% Pass all options to the article class.
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
%    \end{macrocode}
% Pass relevant options to the \textsl{exercise} package.
%    \begin{macrocode}
\DeclareOption{noanswer}{\PassOptionsToPackage{noanswer}{exercise}}
\DeclareOption{noexercise}{\PassOptionsToPackage{noexercise}{exercise}}
\DeclareOption{answeronly}{\PassOptionsToPackage{answeronly}{exercise}}
\DeclareOption{exerciseonly}{\PassOptionsToPackage{exerciseonly}{exercise}}
\DeclareOption{nothing}{\PassOptionsToPackage{nothing}{exercise}}
%    \end{macrocode}
% Process options.
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}

% \subsection{Requirements}

% The options given to the class |exercice| must include \textsl{babel} and \textsl{exercise} packages options.
%    \begin{macrocode}
\RequirePackage{babel}
\RequirePackage[lastexercise]{exercise}
%    \end{macrocode}
% Here, we apply a workaround to fix the incompatibility between \emph{exercise} and the french option from \textsl{babel} (see \href{http://tex.stackexchange.com/questions/338293/package-exercise-change-exercise-to-french-exercice}{stackexchange}).  
%    \begin{macrocode}
\@ifpackageloaded{babel}{
\addto{\captionsfrench}{ %% replace frenchb (fix exercise package)  
  \def\listexercisename{Liste des exercices}%
  \def\ExerciseName{Exercice}%
  \def\AnswerName{Solution de l'exercice}%
  \def\ExerciseListName{Ex.}%
  \def\AnswerListName{Solution}%
  \def\ExePartName{Partie}%
}
}{}

%    \end{macrocode}
% It loads additional packages used for formatting.
%    \begin{macrocode}
\RequirePackage{geometry,tikz,afterpage}
\RequirePackage{titling,fancyhdr}
%    \end{macrocode}
% It registers the total value of the |Exercise| counter.
%    \begin{macrocode}
\RequirePackage{totcount}
\regtotcounter{Exercise}
%    \end{macrocode}

% \subsection{General Information}
% \label{sec:info}
% The user must redefine these commands that specify information about the course or the examination using |\renewcommand|.
% \subsubsection{Course Information}
% \begin{macro}{\coursename}
% The name of the course.
%    \begin{macrocode}
\newcommand{\coursename}{}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\degreename}
% The name of the degree.  
%    \begin{macrocode}
\newcommand{\degreename}{}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\universityname}
% The name of the university.  
%    \begin{macrocode}
\newcommand{\universityname}{Universit\'e C\^ote d'Azur}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\universitylogo}
% The path to an image with the logo of the university.  
%    \begin{macrocode}
\newcommand{\universitylogo}{logo-uca.png}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Exam Information}
% These informations are only displayed on the first page of the examination paper 
% \begin{macro}{\ExamRemark}
% Short remarks or instructions for the exam.
%    \begin{macrocode}
\newcommand{\ExamRemark}{Aucun document autorisé. Écrire à l'encre.}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ExamDuration}
% The duration of the exam.
%    \begin{macrocode}
\newcommand{\ExamDuration}{}
%    \end{macrocode}
% \end{macro}


% \subsection{Versions A and B}
% \begin{macro}{\Versions}
% Beside changing the titles and formats, the user can specify content that depends on the version (A or B).
%    \begin{macrocode}
\newcommand{\Versions}[2]{%
  \ifVersionA%
  #1%
  \else%
  #2%
  \fi%
}
%    \end{macrocode}
% \end{macro}

% \subsection{Export Helper}
% \label{sec:export}
% \begin{macro}{\ExamExport}
% The command configures internal jobs using |\write18| that generate examination papers and corrections for both versions.
% It is designed to be used only once in the preamble of the document.
% Beware that class options can interfere with the default export option. It is recommended to pass a single option to the class : the babel language. 
%    \begin{macrocode}
\newcommand{\ExamExport}{%
\ifx\ExamExportKey\undefined
  \immediate\write18{%
    pdflatex --jobname="\jobname-examA"
    "\gdef\string\ExamExportKey{1}\string\PassOptionsToClass{exam,noanswer}{exercice}\string\input\space\jobname\string"
  }%
  \immediate\write18{%
    pdflatex --jobname="\jobname-examB"
    "\gdef\string\ExamExportKey{2}\string\PassOptionsToClass{exam,noanswer,versionB}{exercice}\string\input\space\jobname\string"
  }%
  \immediate\write18{%
    pdflatex --jobname="\jobname-corrA"
    "\gdef\string\ExamExportKey{3}\string\input\space\jobname"
  }%
  \immediate\write18{%
    pdflatex --jobname="\jobname-corrB"
    "\gdef\string\ExamExportKey{4}\string\PassOptionsToClass{versionB}{exercice}\string\input\space\jobname\string"
  }%
  \expandafter\stop
 \fi
}
%    \end{macrocode}
% However, there is a security issue. If you download some TeX code from the Internet, can you be sure that there is not some command in it (perhaps in a hidden way) to do stuff that might be harmful to your PC 
% So, requires an additional argument when starting TeX : \\ |(pdf)(la)tex --shell-escape|.
% \end{macro}

% \subsection{Exam Commands and Placeholders}
% This section presents special commands for the examination paper. 
% \begin{macro}{\ExamNewpage}
% Clear the page in |exam| 
%    \begin{macrocode}
\newcommand{\ExamNewpage}{%
  \ifExamOutput
  \clearpage
  \fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ExamOnly}
% Print only in |exam|
%    \begin{macrocode}
\newcommand{\ExamOnly}[1]{%
  \ifExamOutput
  #1
  \fi
}
%    \end{macrocode}
% \end{macro}
% Internal counter for generating lines and grids.
%    \begin{macrocode}
\newcounter{@ExamLines}
%    \end{macrocode}
% \begin{macro}{\ExamLines}
% Print lines for writing an answer on the examination paper.
%    \begin{macrocode}
\newcommand{\ExamLines}[1]{%
  \ifExamOutput
  \ExeText%
  \noindent%
  \begin{center}%
    \setcounter{@ExamLines}{0}%
    \whiledo{\value{@ExamLines}<#1}{%
      \begingroup\color{gray}\hrulefill\endgroup\\[2ex]%
      \stepcounter{@ExamLines}}%
  \end{center}%
  \fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\roundlcm}
% return a length in cm rounded to an integer.
%    \begin{macrocode}
\makeatletter%
\def\l@nunitperpt{0.0351459}\def\l@nunits{cm}%
\def\@round#1.#2\@empty{#1}%
\newcommand{\roundlcm}[1]{%
    \expandafter\@round
    \the\dimexpr\l@nunitperpt\dimexpr#1\relax + 0.5pt\relax\@empty
}%
\makeatother%

\newlength{\ExamGridWidth}
\setlength{\ExamGridWidth}{\roundlcm{\textwidth}cm}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ExamGrid}
% Print a grid for writing an answer.
%    \begin{macrocode}
\newcommand{\ExamGrid}[1]{%
  \ifExamOutput
  \ExeText%
  \noindent%
  \begin{center}%
    \begin{tikzpicture}%
      \draw[step=5mm, thin,color=gray!80] (0, 0) grid (\ExamGridWidth,#1cm);%
    \end{tikzpicture}%
  \end{center}%
  \fi
}
%    \end{macrocode}
% \end{macro}


% \subsection{Titling and Formatting}
% This section enables the custom titles anf formatting for both examination paper and correction.
% Most of the changes concern the examination paper.
%
% First, let reduce margins with the geometry package.
%    \begin{macrocode}
\ifExamOutput
\geometry{top=25mm, bottom=20mm, right=20mm}
\else
\geometry{top=20mm, bottom=20mm, left=20mm, right=20mm}
\fi
%    \end{macrocode}
% Second, let define custom headers with the fancyhdr package.
%    \begin{macrocode}
\pagestyle{fancyplain}
\fancyhf{}
\ifExamOutput
\lhead{\fancyplain{}{\coursename}}
\rhead{\fancyplain{}{\Versions{A}{B}\thepage}}
\else
\lhead{\fancyplain{\parbox[t]{7cm}{\large\universityname\\\coursename}}{\large\coursename}}
\rhead{\fancyplain{\large\degreename}{\large\Versions{A}{B}\thepage}}
\fi
%    \end{macrocode}
% Redefine |\maketitle| with the |titling| package.
%    \begin{macrocode}
\ifExamOutput
\reversemarginpar    
\pretitle{
  \vspace{-3.5cm}%
  \hspace*{-2cm}\includegraphics[height=3cm]{\universitylogo}\hfill \\[10pt]  
  \hspace*{-2cm}\begin{minipage}[b]{11cm}
    \large
    \universityname \hfill \degreename\\
    \hfill \coursename 
\begin{center}\LARGE}
\posttitle{\par\end{center}\vskip 0.1em\end{minipage}}
%    \end{macrocode}
% Note that |\author| is not printed.
%    \begin{macrocode}
\preauthor{\author{}}\postauthor{}
%    \end{macrocode}
% Put placeholders and instructions below the date for examination paper.
%    \begin{macrocode}
\predate{
\newline%
\hspace*{-2cm}\begin{minipage}[b]{11cm}%
\begin{center}\large}
\postdate{%
      \par\end{center}%
\textbf{Durée :} \ExamDuration\\
\ExamRemark\\[3pt]
\fbox{\parbox[t]{2cm}{Note\\ \ \\ \ \\ \ }}%
\quad\parbox[t]{7cm}{\scriptsize Il est de votre responsabilité de rabattre le triangle grisé et de le cacheter au moyen de colle, agrafes ou papier adhésif. Si ne vous le faites pas, vous acceptez implicitement que votre copie ne soit pas anonyme.}%
\end{minipage}
%    \end{macrocode}
% Let print the identification block with the tikz package.
%    \begin{macrocode}
\begin{tikzpicture}[remember picture, overlay]
        \node [shift={(-8cm,-8cm)}] at (current page.north east)
              {\begin{tikzpicture}[remember picture, overlay]
                  \draw (0,0) rectangle (8,8);
                  \draw [fill=gray] (0,8) -- (8,8) -- (8,0) -- cycle;
                  \path [coordinate]
                  \foreach \k in {1,...,4}{%
                    (0pt,8cm-\k*1.2cm) coordinate (d\k)};
                  \path [clip] (0,0) rectangle (8,8);
                  \foreach \k/\t in {1/Nom,2/Prénom,3/Né(e) à,4/Le}{%
                    \node [inner sep=0pt,rotate=-45,%
                      right=0.5cm,minimum height=12pt] (f\k) at (d\k) {\t};
                    \draw (f\k.south east) -- (8cm-\k*1.2cm,-6pt);
                  }
                \end{tikzpicture}};
          \end{tikzpicture}
          %% frame at the verso of the title page
          \afterpage{\vspace*{5cm}}
          \afterpage{%
            \begin{tikzpicture}[remember picture, overlay]
              \node [shift={(0cm,-8cm)}] at (current page.north west)
              {\begin{tikzpicture}[remember picture, overlay]
                  \draw (0,0) [fill=gray] rectangle (8,8);
                \end{tikzpicture}};
            \end{tikzpicture}
          }
%    \end{macrocode}
% Let print the grade tables for teacher if it is enabled.
%    \begin{macrocode}          
          \ifGradingOutput
          \vspace{1.5cm}
          \marginpar{
            \setcounter{@ExamLines}{1}
            \renewcommand{\arraystretch}{1.5}
            \Versions{\color{purple}}{\color{blue}}
            \begin{tabular}{|p{1.5cm}|}
              \hline
              Sujet \Versions{A}{B}\\
              \hline
              \whiledo{\value{@ExamLines} < \totvalue{Exercise}}{%
              \arabic{@ExamLines} : \stepcounter{@ExamLines}\\\hline
              }
              \arabic{@ExamLines} : \stepcounter{@ExamLines}\\\hline
            \end{tabular}%
          }
          \vspace{-1.5cm}
          \fi
        }
%    \end{macrocode}
% Let define the light formatting for corrections.
%    \begin{macrocode}           
\else
\pretitle{\begin{center}\LARGE}
\posttitle{\par\end{center}\vskip 0.1em}
\preauthor{\author{}}
\postauthor{}
\predate{\begin{center}\large}
\postdate{\par\end{center}}
\fi
%    \end{macrocode}

%    \begin{macrocode}
\endinput
%</class>
%    \end{macrocode}


%\Finale
\endinput