summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/minorrevision/minorrevision.tex
blob: 8bc690fef74f7b3079139eb1f06eec460b297050 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
\documentclass{ltxdoc}
\usepackage{minorrevision}
\usepackage{url}
\usepackage{framed}

\begin{document}

\title{The \textsf{minorrevision} package\thanks{This document corresponds to \textsf{minorrevision}~v1.1, dated~2013/11/15.}}
\author{Matthieu Guillaumin\\ \texttt{guillaumin@vision.ee.ethz.ch}}

\maketitle

\tableofcontents

\section{Description and usage}

\verb|minorrevision| is intended for researchers who publish articles in peer-reviewed
journals. In the final stages of the review process, the authors typically have
to provide an additional document (such as a letter to the editors) where they
want to provide a list of modifications that they made to the manuscript.  It
is convenient for the editors to have line numbers and quotations from the
manuscript in this letter. This package helps automatizing this task for the
authors.

This is a two-step process.

\subsection{Step 1: Editing the reference document}
In the manuscript (say \verb|manuscript.tex|), you need to declare the use
of the package, by putting the following line in the preamble of your LaTeX
source:
\begin{verbatim}
\usepackage{minorrevision}
\end{verbatim}

You should also add line numbers to your manuscript, also in the preamble:
\begin{verbatim}
\linenumbers
\end{verbatim}

Then, in the body of you manuscript, when you make a minor
modification, you need to use the \verb|\revision| macro. For instance, if the
following sentence was in your manuscript:
\begin{verbatim}
In this paper, we show that $1+1=2$.
\end{verbatim}

And, following reviews, you want to modify it to:
\begin{verbatim}
In this paper, we hypothetize that $1+1=2$.
\end{verbatim}

Then, instead of replacing the text directly, you should use the \verb|\revision| macro:
\begin{quote}
\verb|\revision| \marg{label} \marg{new text} \marg{old text}
\end{quote}

In your document, this looks like:
\begin{verbatim}
In this paper, we \revision{mymod}{hypothetize}{show} that $1+1=2$.
\end{verbatim}

Here, we have used the label \verb|mymod| for later reference. When compiling
\verb|manuscript.tex| with LaTeX, only the new version of the text will appear.

For text that is simply removed, you can use:
\begin{quote}
\verb|\revisionrm| \marg{label} \marg{old text}
\end{quote}

For text that is simply added:
\begin{quote}
\verb|\revisionadd| \marg{label} \marg{new text}
\end{quote}

A call to \verb|\revision{label}{text1}{text2}| is similar to
\begin{verbatim}
\revisionrm{label}{text2}\revisionadd{label}{text1}
\end{verbatim}
but the latter wouldn't work because the label would be defined twice.

\subsection{Step 2: Editing the referring document}

In the document where you want make reference to the manuscript, also add the \verb|minorrevision| package, and specify that \verb|manuscript.tex| is the reference:

\begin{verbatim}
\usepackage{minorrevision}
\mrvdocument{manuscript}
\end{verbatim}

Note how \verb|.tex| should \textbf{not} be included in the \verb|\mrvdocument| macro.
As of v1.1, you can have multiple references:

\begin{verbatim}
\mrvdocument{manuscript}
\mrvdocument{manuscript2}
\end{verbatim}

You can now refer to the line numbers of modifications in the reference documents via their label names, by using:
\begin{quote}
\verb|\mrvref| \marg{reference} \marg{label} \\
\verb|\mrvold| \marg{reference} \marg{label} \\
\verb|\mrvnew| \marg{reference} \marg{label} 
\end{quote}

\verb|reference| should correspond to the argument of \verb|\mrvdocument|.

\begin{verbatim}
On line~\mrvref{manuscript}{mymod}, we have replaced
``\mrvold{manuscript}{mymod}'' with ``\mrvnew{manuscript}{mymod}''.
\end{verbatim}

It's up to you to format that as you prefer.
The \verb|quote| or \verb|quotation| environments are probably better for larger modifications.

For the latest declared reference document, the following simpler macros are available:
\begin{quote}
\verb|\revref| \marg{label}\\
\verb|\revold| \marg{label}\\
\verb|\revnew| \marg{label}
\end{quote}

This is particularly useful when there is no possible ambiguity, i.e when there is only one reference.

\begin{verbatim}
On line~\revref{mymod}, we have replaced ``\revold{mymod}''
with ``\revnew{mymod}''.
\end{verbatim}

\section{Implementation details}

This package automatically adds the following packages:
\begin{itemize}
\item \textsf{xkeyval}: for passing options to the packages below
\item \textsf{lineno}: to get line numbers of labels
\item \textsf{xr}: to perform cross-reference between documents
\end{itemize}

When using the package, a new auxiliary file is created, with extention \verb|.mrv|.
In the case of \verb|manuscript.tex|, the file will be \verb|manuscript.mrv|.
The \verb|\revision| macro not only declares the label for \verb|lineno| and prints the new text to the document, but also writes two macro definitions in \verb|manuscript.mrv| with both the new and old text contents.
The macro name depends on the name of the reference (here, \verb|manuscript|), and the label name (here, \verb|mymod|).

When making the call to \verb|\mrvdocument|, those macro definitions are read (simply by inputting the file), and calls to \verb|\revref{mymod}|, \verb|\revold{mymod}| and \verb|\revnew{mymod}| (and \verb|\mrvref|, \verb|\mrvold| and \verb|\mrvnew|) become available.

See \verb|minorrevision.sty| for the actual implementation with comments.

\section{Bug reports}

Please use the official bitbucket repository for bug reports, patch proposals and other questions:

\begin{quote}
\url{https://bitbucket.org/mguillau/latex-minorrevision}
\end{quote}

\end{document}