\documentclass[10pt,a4paper,final,makeidx,twosides]{article}


\usepackage{tabularx}
\usepackage{ulem}
\usepackage{boxedminipage}

\usepackage{listings}

\usepackage{caption}
%\captionsetup{figurename=Figure, tablename=Table}

\renewcommand{\captionfont}{\small}
\renewcommand{\captionlabelfont}{\bfseries}

\usepackage[protrusion=true,draft=false,final,verbose=true,babel=true]{microtype}


\def\dashuline{\bgroup
\ifdim\ULdepth=\maxdimen % Set depth based on font, if not set already
\settodepth\ULdepth{(j}\advance\ULdepth.4pt\fi
\markoverwith{\kern.15em
\vtop{\kern\ULdepth \hrule width .3em}%
\kern.15em}\ULon}

\def\dotuline{\bgroup
\ifdim\ULdepth=\maxdimen % Set depth based on font, if not set already
\settodepth\ULdepth{(j}\advance\ULdepth.4pt\fi
\markoverwith{\begingroup
\advance\ULdepth0.08ex
\lower\ULdepth\hbox{\kern.15em .\kern.1em}%
\endgroup}\ULon}

\makeatletter
\newcommand{\ack}[1]{\let\save@makefntext\@makefntext%
\def\@makefntext##1{\parindent0em##1}\footnotetext{#1}%
\let\@makefntext\save@makefntext}
\makeatother

\title{The \textbf{dashundergaps} package}
\author{Merciadri Luca}
\date{\today}

\usepackage{makeidx}

%% - HYPERREF PACKAGE - ** MUST be LAST ONE **
\usepackage[a4paper,bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,bookmarksopenlevel=1,breaklinks=true,colorlinks=true,final,menucolor=red,pdfauthor={Merciadri Luca},pdfcreator={Merciadri Luca},pdfkeywords={math},pdftitle={The dashundergaps package},pdfsubject={(La)TeX},pdftoolbar=true]{hyperref}
\hypersetup{urlcolor=red,linkcolor=blue,citecolor=blue,colorlinks=true}

\usepackage{breakurl}


%% -- INDEX GENERATION ACTIVATION --

\makeindex

%% -- INDEX GENERATION ACTIVATION --

\begin{document}


\maketitle

\tableofcontents

\newpage
\section{Introduction}
This package (\verb v1.2 ) \textit{helps you to} use (a) pattern(s) from this list:
\begin{enumerate}
\item \dashuline{dashing};
\item \dotuline{dotting};
\item \underline{underlining}
\end{enumerate}
for a word which can be either
\begin{enumerate}
\item hidden;
\item or not.
\end{enumerate}

This can be \textit{useful in} these situations:
\begin{enumerate}
\item You are writing a document for which you need to dash or (and) to dot text,
\item You want to write a test for which students have to ``fill in the gaps,'' and you want to chose when to print the answers.
\end{enumerate}

\section{Use}
\subsection{Loading the Package}
To \textit{load the package}, please use
\begin{center}
\begin{verbatim}
\usepackage[options]{dashundergaps}
\end{verbatim}
\end{center}
\subsection{Available Options}
Without any option, the package will not be really useful, as it will not perform anything that will be nice for you. Consequently, the \textit{following options are available}:
\begin{itemize}
\item \verb dash : will dash \dashuline{text} if used with the command\index{\texttt{dash}}
\begin{verbatim}
\dashuline{text}
\end{verbatim}
where you want ``text'' to be dashed (\textit{i.e.} somewhere in the \verb document ~environment)
\item \verb dot : will dot \dotuline{text} if used with the command\index{\texttt{dot}}
\begin{verbatim}
\dotuline{text}
\end{verbatim}
where you want ``text'' to be dotted (\textit{i.e.} somewhere in the \verb document ~environment),
\item \verb phantomtext : will help you to write a pattern at the place of the text. This pattern can be\index{\texttt{phantomtext}}
\begin{itemize}
\item dashing, if used with \verb dash ~option;
\item dotting, if used with \verb dot ~option;
\item underlining, if used with (\verb dash ~\textit{and} \verb dot ) options \textit{or} with neither \verb dash ~nor \verb dot ;
\item the text in itself, if used with \verb teachernotes ~option.
\end{itemize}
\item \verb teachernotes : see the last point of \verb phantomtext ,\index{\texttt{teachernotes}}
\item \verb displaynbgaps : will produce, at the end of your document (and in the center of the page), a summary of the number of gaps like\index{\texttt{displaynbgaps}}
\begin{center}
\textbf{GAPS: $x$.}
\end{center}
\end{itemize}

\newpage
\section{Possible Combinations}
All the possible sensed commands (the launching order has no importance) of \verb dashundergap.sty ~are given at Table \ref{tab:exuse} \textit{except} the use of \verb displaynbgaps , which can trivially be used iff \verb phantomtext ~is used. Here, ``$\times$'' is equivalent to the well-known ``N.A.'' and thus means ``Not Applicable here,'' or, equivalently, ``Not Available.''

\begin{table}[!h]
\begin{center}
\begin{tabular}{cccc}
\hline
\hline
\hline
\textbf{Option(s)} & \multicolumn{3}{c}{\textbf{Consequence}}\\
\hline
 & \texttt{\textbackslash gap\{text\}} & \texttt{\textbackslash dashuline\{text\}} & \texttt{\textbackslash dotuline\{text\}}\\
\hline
\hline
\texttt{dash} (only) & $\times$ & \dashuline{text} & $\times$\\
\hline
\texttt{dot} (only) & $\times$ & $\times$ & \dotuline{text}\\
\hline
\texttt{dash}, \texttt{dot} & $\times$ & \dashuline{text} & \dotuline{text}\\
\hline
\hline
\texttt{phantomtext} (only) & \underline{\phantom{text}} (1) & $\times$ & $\times$\\
\hline
\texttt{phantomtext}, \texttt{dash} & \dashuline{\phantom{text}} (1) & \dashuline{text} & $\times$\\
\hline
\texttt{phantomtext}, \texttt{dot} & \dotuline{\phantom{text}} (1) & $\times$ & \dotuline{text}\\
\hline
\texttt{phantomtext}, \texttt{dash}, \texttt{dot} & \underline{\phantom{text}} (1) & \dashuline{text} & \dotuline{text}\\
\hline
\texttt{phantomtext}, \texttt{teachernotes} & \textbf{text} & $\times$ & $\times$\\
\hline
\texttt{phantomtext}, \texttt{dash}, \texttt{teachernotes} & \textbf{text} & \dashuline{text} & $\times$\\
\hline
\texttt{phantomtext}, \texttt{dot}, \texttt{teachernotes} & \textbf{text} & $\times$ & \dotuline{text}\\
\hline
\texttt{phantomtext}, \texttt{dash}, \texttt{dot}, \texttt{teachernotes} & \textbf{text} & \dashuline{text} & \dotuline{text}\\
\hline
\hline
\hline
\end{tabular}
\caption{Possible sensed commands of this package except \texttt{displaynbgaps}.}
\label{tab:exuse}
\end{center}
\index{\texttt{dot}}
\index{\texttt{teachernotes}}
\index{\texttt{dash}}
\index{\texttt{displaynbgaps}}
\index{\texttt{phantomtext}}
\end{table}

\section{Examples}
From now on, the output of the listed codes will be put in rectangular boxes.

\subsection{Dashing}
Here is an \textit{example} of \textit{sentence dashing}.
\begin{verbatim}
\documentclass[10pt]{article}

\usepackage[dash]{dashundergaps}

\begin{document}
\dashuline{This is a dashed sentence}
\end{document}
\end{verbatim}
gives
\begin{center}
\begin{boxedminipage}{\textwidth}
\dashuline{This is a dashed sentence}
\end{boxedminipage}
\end{center}
Dotting is done in the same way.

\newpage
\subsection{Gaps with Dots -- Student Version}
Here is an \textit{example} of \textit{dotted gaps} for the student version.
\begin{verbatim}
\documentclass[10pt]{article}

\usepackage[dot, phantomtext]{dashundergaps}

\begin{document}
In Computer Science, ``PC'' means ``Personal \gap{Computer}.''

We can still \dotuline{dot this}.
\end{document}
\end{verbatim}
results in
\begin{center}
\begin{boxedminipage}{\textwidth}
In Computer Science, ``PC'' means ``Personal \dotuline{\phantom{Computer}}.''

We can still \dotuline{dot this}.
\end{boxedminipage}
\end{center}

\subsection{With Tabular}
To produce
\begin{center}
\begin{boxedminipage}{\textwidth}
\begin{tabular}{lll}
\hline
Head A & Head B & Head C\\
\multicolumn{2}{l}{\dotuline{\hfill}}\\
Col 1 & Col 2 & Col 3\\
Col 1 & Col 2 & Col 3\\
\hline
\end{tabular}
\end{boxedminipage}
\end{center}
just use
\noindent
\begin{verbatim}
 \begin{tabular}{lll}
\hline
Head A & Head B & Head C\\
\multicolumn{2}{l}{\dotuline{\hfill}}\\
Col 1 & Col 2 & Col 3\\
Col 1 & Col 2 & Col 3\\
\hline
\end{tabular}
\end{verbatim}
where you want it to appear.


\newpage
\section{Implementation}
Here is the code of \verb dashundergaps.sty :
\lstset{language=TEX, basicstyle=\tiny, keywordstyle=\bfseries, commentstyle=\itshape, keywords={}, emph={}, emphstyle=\bfseries, numbers=left, stringstyle=\ttseries, showstringspaces=false, stepnumber=2, numbersep=5pt, showspaces=false, showtabs=false, backgroundcolor=\color{white}}

%\begin{lstlisting}[frame=single]
\lstinputlisting[lastline=80]{dashundergaps.forlisting}
%\end{lstlisting}


\section{Limitations}
This package is currently not able to cope with strange users such as the ones which would
\begin{itemize}
\item Like to use both \verb \dashuline{text} ~\textit{and} \verb \dotuline{text} ~\textit{and} would like \verb \gap{text} ~to appear either as \verb \dotuline{\phantom{text}} ~or as \verb \dashuline{\phantom{text}} . This is not implemented as this would be a really unuseful feature: there are not many folks who want their \verb \gap{text} ~to be filled with something else than \begin{center}\begin{verbatim}\underline{\phantom{text}}\end{verbatim}\end{center} when already using \verb \dashuline ~or \verb \dotuline ~in the text!
\end{itemize}

\section{Remarks}
\subsection{Dashing and Dotting Hierarchy}
\subsubsection{Numbering}
Some users would like to use a code like this:
\scriptsize
\begin{verbatim}
...
\usepackage[dash,dot]{dashundergaps}
...
\usepackage[calcwidth,pagestyles,raggedright,bf,sf,...]{titlesec}
\titleformat{\section}{\normalfont\Huge\bfseries}{\dashuline{\thesection}}{1em}{}
\titleformat{\subsection}{\normalfont\LARGE\bfseries}{\dotuline{\thesubsection}}{1em}{}
\titleformat{\subsubsection}{\normalfont\Large\bfseries}{\thesubsubsection}{1em}{}
\titleformat{\paragraph}[runin]{\normalfont\large\bfseries\itshape}{\theparagraph}{1em}{}
\titleformat{\subparagraph}[runin]{\normalfont\normalsize\bfseries\itshape}{\thesubparagraph}{1em}{}
...
\end{verbatim}
\normalsize
It is possible, and will work. For example, here, sections and subsections will have their numbering respectively dashed and dotted.

\subsubsection{Titles}
You cannot modify
\scriptsize
\begin{verbatim}
...
\usepackage[dash,dot]{dashundergaps}
...
\usepackage[calcwidth,pagestyles,raggedright,bf,sf,...]{titlesec}
\titleformat{\section}{\normalfont\Huge\bfseries}{\thesection}{1em}{}
\titleformat{\subsection}{\normalfont\LARGE\bfseries}{\thesubsection}{1em}{}
\titleformat{\subsubsection}{\normalfont\Large\bfseries}{\thesubsubsection}{1em}{}
\titleformat{\paragraph}[runin]{\normalfont\large\bfseries\itshape}{\theparagraph}{1em}{}
\titleformat{\subparagraph}[runin]{\normalfont\normalsize\bfseries\itshape}{\thesubparagraph}{1em}{}
...
\end{verbatim}
\normalsize
to output the names of your sections, subsections, \ldots in a dashed or dotted fashion. For this, the temporary solution is to use, at each of the points of the hierarchy, a code like this (this is for \verb \section ):
\begin{verbatim}
\section{\protect\dashuline{This is the First Section}}
\end{verbatim}
Do not forget the \verb \protect ~please. It must be written because \verb \dashuline ~and \verb \dotuline ~were not declared as robust commands.

\subsection{Ulem and the Emphasize Command}
\label{subsec:v11}
Donald Arseneau informed me in an e-mail that adding
\begin{verbatim}
\PassOptionsToPackage{normalem}{ulem}
\end{verbatim}
before
\begin{verbatim}
\RequirePackage{ulem}
\end{verbatim}
would be a good idea, since \verb \emph ~is equivalent to \verb \underline ~for \verb ulem ~when the \verb normalem ~option is not given to it. This has been modified, and is in \verb v1.1 .

\section{Bugs}
[Chronologically ordered.]
\begin{enumerate}
\item (20/01/2010): Thanks to \cite{mathematex}, the first bug has been discovered: if the argument of \verb \gap ~was too long, and that \verb teachernotes ~was activated, the underlining was not done according to margins. It has now be solved. Many thanks to Donald Arseneau for this. \label{bug:20012010}
\end{enumerate}

\section{Version History}
\begin{enumerate}
 \item \verb v1.0 : package is introduced to the \LaTeX{} world,
 \item \verb v1.1 : see \ref{subsec:v11},
 \item \verb v1.2 : fixed bug \ref{bug:20012010}, and the commands are now defined using \verb \providecommand .
\end{enumerate}


\section{Contact}
If you have any question concerning this package (limitations, bugs, \ldots), please contact me at \href{mailto:Luca.Merciadri@student.ulg.ac.be}{Luca.Merciadri@student.ulg.ac.be}.




\newpage

\phantomsection
\printindex

\newpage
\pagenumbering{Roman}
\setcounter{page}{1}
\section{References}
\nocite{*}
\bibliographystyle{siam}
%\bibliographystyle{frplain}
%\bibliographystyle{alpha}
\label{biblio}
%\begin{multicols}{2}
\bibliography{dashundergaps-bib}

\end{document}