\documentclass{article}

\usepackage[arrows]{ezedits}

\usepackage{xcolor}
\usepackage{hyperref}

\newcommand{\macroexample}[1]{\begin{center}
    \fcolorbox{black}{black!6}{\parbox{.9\linewidth}{\ttfamily #1}}
\end{center}}


\title{\texttt{ezedits.sty} documentation}
\author{Joseph A. Smiga $\langle$\href{mailto:joseph.smiga@rochester.edu?subject=[ezedits]\%20}{joseph.smiga@rochester.edu}$\rangle$}
\date{Package: September 12, 2024 (v1.0)\\
Documentation: September 12, 2024
}

\defineEdit{ABC}{\color{red}}{\color{blue}}
\defineEdit{XYZ}{\color{gray}\textit}{\textbf}


\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

The \texttt{ezedits} package is designed to make it easier to edit \LaTeX{} documents with multiple people, while keeping track of what changed. 

Changes signified with this package with raise warnings. This makes it easier to keep track of changes and keep the document clean. 

Note that, in this document, the package is included as:
\macroexample{\textbackslash{}usepackage[arrows]\{ezedits\}}
with the \texttt{xcolor} package included. 

\section{Dependencies}
The following packages may be required:
\begin{itemize}
    \item \href{https://ctan.org/pkg/ulem}{\texttt{ulem}}: used for strikethrough (\texttt{\textbackslash{sout}}). This is required by default, unless the \hyperlink{opt_nosout}{\texttt{nosout}} option is used. 
    
    \item \href{https://ctan.org/pkg/xcolor}{\texttt{xcolor}}: used for coloring text. If included (i.e., \texttt{\textbackslash{textcolor}} is defined), \hyperlink{cmd_draftnote}{\texttt{\textbackslash{draftnote}}} is colored red by default.

    \item \href{https://ctan.org/pkg/pdfcomment}{\texttt{pdfcomment}}: needed when \hyperlink{opt_pdfcomment}{\texttt{pdfcomment}} option is used.
\end{itemize}


\section{Package options}
The following options can be used with \verb+\usepackage[...]{ezedits}+:
\begin{itemize}
    \item \hypertarget{opt_arrows}{\texttt{arrows}} add arrows ``$\Longleftarrow$'' pointing to edits in margins (in captions, a pair of arrows are added, instead; $\Longrightarrow$Like this$\Longleftarrow$). These arrows are styled based on the edit.

    \item \hypertarget{opt_accept}{\texttt{accept}} accept all edits (arrows still appear if \texttt{arrows} option is used).

    \item \hypertarget{opt_pdfcomment}{\texttt{pdfcomment}} write edits as pdf annotations (arrows still appear if \texttt{arrows} option is used).

    \item \hypertarget{opt_nosout}{\texttt{nosout}} do not strikeout delete text (by default). If this option is set, the \texttt{ulem} package is not required.
\end{itemize}


\section{Commands}

\noindent\hypertarget{cmd_draftnote}{\texttt{\textbackslash{draftnote}\{...\}}}

This will generate a note in the text. Text is placed in square brackets and stylized to make it distinct from the rest of the text.

\draftnote{Here is an example note}

\vspace{5mm}\hrule\vspace{2mm}

\noindent\hypertarget{cmd_defineEdit}{\texttt{\textbackslash{defineEdit}\{ABC\}\{$\langle$styleA$\rangle$\}\{$\langle$styleB$\rangle$\}}}

This will generate a set of commands with the prefix \texttt{ABC} for editing where \texttt{$\langle$styleA$\rangle$} is used for omitted text and \texttt{$\langle$styleB$\rangle$} is used for added text.

The following commands are generated:
\begin{itemize}
    \item \verb+\ABCEdit{del}{ins}+ Used to replace \verb+del+ with \verb+ins+.
    
    For example: \ABCEdit{old}{new}.

    \item \verb+\ABCIns{ins}+ Used to insert \verb+ins+.
    
    For example: \ABCIns{new}.

    \item \verb+\ABCDel{del}+ Used to delete \verb+del+.
    
    For example: \ABCDel{old}.
\end{itemize}


\vspace{5mm}\hrule\vspace{2mm}

\noindent\hypertarget{cmd_setnotestyle}{\texttt{\textbackslash{setnotestyle}}\{$\langle$style$\rangle$\}}

Redefine how \hyperlink{cmd_draftnote}{\texttt{\textbackslash{draftnote}}} appears. Here, $\langle$style$\rangle$ is a macro that takes one argument and returns a styled version of that text.


\vspace{5mm}\hrule\vspace{2mm}

\noindent\hypertarget{cmd_makeeditreport}{\texttt{\textbackslash{makeeditreport}}}

Creates a summary of which page edits appear on (at the point that the command is called). The output is a \texttt{tabular} environment.


\section{Examples}
Here, we use the following command to define the edit commands:

\macroexample{\textbackslash{}defineEdit\{ABC\}\{\textbackslash{}color\{red\}\}\{\textbackslash{}color\{blue\}\}}

Here, the first argument \verb+{ABC}+ is the prefix for the edit commands. The second argument \verb+{\color{red}}+ describes how to style deleted text (the text is always crossed-out). Finally, the third argument \verb+{\color{blue}}+ describes what to do with added text. Note that, if the \hyperlink{opt_arrows}{\texttt{arrows}} option is used, it will be styled according to the latter argument. 

A simple example of editing a sentence:
\macroexample{This \textbackslash{}ABCIns\{sentence\} contains some \textbackslash{}ABCDel\{major\} errors, but that is \textbackslash{}ABCEdit\{ok\}\{not a big deal\}. \textbackslash{}drafNote\{Remember to clean up the document\}}

\begin{center}
    \fbox{\parbox{.9\linewidth}{This \ABCIns{sentence} contains some \ABCDel{major} errors, but that is \ABCEdit{ok}{not a big deal}. \draftnote{Remember to clean up the document}}}
\end{center}


\vspace{5mm}\hrule\vspace{2mm}

The styling options are fairly flexible. For example, one can define their own macro \verb+\style{...}+ that takes one argument and stylizes it. 
For example, an alternative styling:
\macroexample{\textbackslash{}defineEdit\{XYZ\}\{\textbackslash{}color\{gray\}\textbackslash{}textit\}\}\{\textbackslash{}textbf\}}
So deleted text \XYZDel{will look like this} while added text \XYZIns{will look like this}.


\vspace{5mm}\hrule\vspace{2mm}

One can also include edits in (floating) figures. However, if \hyperlink{opt_arrows}{\texttt{arrows}} package option is used, the arrows will appear around the edit, instead of in the margin.
\begin{figure}[h]
    \centering
    {\rule{1cm}{1cm}}
    \caption{This is just a \ABCIns{black} box.}
    \label{fig:blackbox}
\end{figure}


\vspace{5mm}\hrule\vspace{2mm}

After making edits, one can generate a summary of edits using \verb+\makeeditreport+ (only includes edits/notes from before this command is called):

\macroexample{
\textbackslash{}begin\{table\}[h]\par
~~~~\textbackslash{}centering\par
~~~~\textbackslash{}makeeditreport\par
\textbackslash{}end\{table\}
}

\begin{table}[h]
    \centering
    \makeeditreport
\end{table}

Note that warnings will also be raised for each edit/note at their location. 

\section{Possible issues}
There are times where the page number used in \hyperlink{cmd_makeeditreport}{\texttt{\textbackslash{makeeditreport}}} may not be exactly correct. This has to do with how \LaTeX{} updates \verb+\thepage+. Namely, it tends to wait until new paragraphs. Also, floating environments can be pushed to a different page.

There are certain cases in which the ``strikeout'' styling does not play nicely. For example, there may be issues when crossing-out citations (c.f., \href{https://tex.stackexchange.com/q/98222}{this Stack Exchange}). To resolve this, \texttt{ezedits} modifies the \verb+\sout+ command to put \verb+\cite{...}+ within an \verb+\mbox+. This results in the minor inconvenience of not letting citations cross multiple lines. 

Also, issues can arise when command covers many paragraphs --- the simple resolution to this would be to repeat the command per paragraph.


\section{Acknowledgements}
JAS would like to thank Abhay Hegde for suggesting the \hyperlink{cmd_makeeditreport}{\texttt{\textbackslash{makeeditreport}}} macro.


\end{document}