summaryrefslogtreecommitdiff
path: root/support/latexdiff/doc/latexdiff-man.tex
blob: 1059eb25a3f4b49fad5648e17afa5f0ad515a979 (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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
\documentclass[a4]{article}
\usepackage{graphicx}
%\def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}}
%\def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}}
\setlength{\parindent}{0pt}                                                                              
%\setlength{\textwidth}{6.5in}
%\setlength{\oddsidemargin}{0.0in}                                                                                  
\title{Marking up differences between latex files with {\em latexdiff}}
\author{F.J. Tilmann\thanks{tilmann@gfz-potsdam.de}}
\date{\today}

\begin{document}
\maketitle

\section*{Preamble}

{\em latexdiff} is a Perl script, which compares two
latex files and marks up significant differences between them.  Various options are available for visual markup using standard
latex packages such as {\em color.sty}. Changes not directly affecting visible
text, for example in formatting  commands, are still marked in the
latex source.

A rudimentary revision facilility is provided by another Perl script,
{\em latexrevise}, which  accepts or rejects all changes.  Manual editing
of the difference file can be used to override this default behaviour
and accept or reject selected changes only.  

There is no explicit support for annotations as these are trivial to implement.
For example, I include the following command definition in the preamble
\begin{verbatim}
\newcommand{\remark}[1]{{ \bf [ \footnotesize #1 ]}}
\end{verbatim}
and mark up annotations as follows 
\begin{verbatim}
... The roadrunner is the fastest running bird  \remark{Check this 
again with a zoologist!}. The most famous roadrunner ...
\end{verbatim}
Alternatively, instead of a command like \verb#\remark# in the example just given, an
equivalent annotation environment could be defined.
{\em latexrevise} can  remove such comments or
environments from the text body.

%It is planned that the revision capabilities of this system will be
%further expanded, dependent on the amount of feedback received.

On the following pages you find  the {\em man} pages for {\em
  latexdiff} and {\em latexrevise} and a simple example.

\include{latexdiff}
\setcounter{section}{0}

\include{latexrevise}
\setcounter{section}{0}

\include{latexdiff-vc}
\setcounter{section}{0}

\section*{A simple example}

We start with a draft text, \verb|example-draft.tex|, listed here in
full but also included in the distribution (except that the ``verbatim'' environment had
to be renamed to ``Verbatim'' for the listing).

{\scriptsize
\begin{verbatim}
\documentclass[12pt,a4paper]{article}

\setlength{\topmargin}{-0.2in}
\setlength{\textheight}{9.5in}
\setlength{\oddsidemargin}{0.0in}

\setlength{\textwidth}{6.5in}

\title{latexdiff Example - Draft version}
\author{F Tilmann}

\begin{document}
\maketitle

\section*{Introduction}

This is an extremely simple document that showcases some of latexdiff features.
Type
\begin{Verbatim}
latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
\end{Verbatim}
to create the difference file.  You can inspect this file directly. Then run either 
\begin{Verbatim}
pdflatex example-diff.tex
xpdf example-diff.pdf
\end{Verbatim}
or
\begin{Verbatim}
latex example-diff.tex
dvips -o example-diff.ps example-diff.dvi
gv example-diff.ps
\end{Verbatim}
to display the markup. Of course, instead of \verb|xpdf| you can use 
\verb|okular, evince, acroread| or any other pdf or postscript viewer.

\section*{Another section title}

A paragraph with a line only in the draft document.  More things 
could be said were it not for the constraints of time and space.

More things could be said were it not for the constraints of time and space.

And here is a tipo. 

Here is a table:

\begin{tabular}{ll}
Name & Description \\
\hline
Gandalf & Grey \\
Saruman & White
\end{tabular}

And sometimes a whole paragraph gets completely rewritten. In this
case latexdiff marks up the whole paragraph even if some words in it
are identical.
No change, no markup!
\end{document}
\end{verbatim}
}

We can now edit
this text as we would do with any other latex file to create
a new revision of the text, \verb|example-rev.tex|.  We should run
\begin{verbatim}
latex example-rev.tex
\end{verbatim}
and look at the resulting \verb|.dvi| file to make sure that all
changes are valid.  An example revision is listed here:

{\scriptsize
\begin{verbatim}
\documentclass[12pt,a4paper]{article}

\setlength{\topmargin}{-0.2in}
\setlength{\textheight}{9.5in}
\setlength{\oddsidemargin}{0.0in}

\setlength{\textwidth}{6in}

\title{latexdiff Example - Revised version}
\author{F Tilmann}
% Note how in the preamble visual markup is never used (even
% if some preamble might eventually end up as visible text.)

\begin{document}
\maketitle

\section*{Introduction}

This is an extremely simple document that showcases some of the latexdiff features.
Type
\begin{Verbatim}
latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
\end{Verbatim}
to create the difference file.  You can inspect this file directly. Then run either 
\begin{Verbatim}
pdflatex example-diff.tex
xpdf example-diff.pdf
\end{Verbatim}
or
\begin{Verbatim}
latex example-diff.tex
dvips -o example-diff.ps example-diff.dvi
gv example-diff.ps
\end{Verbatim}
to display the markup.

\section*{Yet another section title}

 More things could be said were it not for the constraints of time and space.

A paragraph with a line only in the revised document.  
More things could be said were it not for the constraints of time and space.

And here is a typo. 

Here is a table:

\begin{tabular}{ll}
Name & Description \\
\hline
Gandalf & White \\
Saruman & Evil
\end{tabular}

And now for something completely different, with not a paragraph in sight.
No change, 
no markup!
\end{document}
\end{verbatim}
}

To compare both revisions, type
\begin{verbatim}
latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
\end{verbatim}
This results in the following difference file (a few newlines have been 
added in this listing for legibility reasosn):
{\scriptsize
\begin{verbatim}
\documentclass[12pt,a4paper]{article}

\setlength{\topmargin}{-0.2in}
\setlength{\textheight}{9.5in}
\setlength{\oddsidemargin}{0.0in}

%DIF 7c7
%DIF < \setlength{\textwidth}{6.5in}
%DIF -------
\setlength{\textwidth}{6in} %DIF > 
%DIF -------

%DIF 9c9
%DIF < \title{latexdiff Example - Draft version}
%DIF -------
\title{latexdiff Example - Revised version} %DIF > 
%DIF -------
\author{F Tilmann}
% Note how in the preamble visual markup is never used (even %DIF > 
% if some preamble might eventually end up as visible text.) %DIF > 
%DIF PREAMBLE EXTENSION ADDED BY LATEXDIFF
%DIF UNDERLINE PREAMBLE %DIF PREAMBLE
\RequirePackage[normalem]{ulem} %DIF PREAMBLE
\RequirePackage{color} %DIF PREAMBLE
\providecommand{\DIFadd}[1]{{\color{blue}\uline{#1}}} %DIF PREAMBLE
\providecommand{\DIFdel}[1]{{\color{red}\sout{#1}}}                      %DIF PREAMBLE
%DIF SAFE PREAMBLE %DIF PREAMBLE
\providecommand{\DIFaddbegin}{} %DIF PREAMBLE
\providecommand{\DIFaddend}{} %DIF PREAMBLE
\providecommand{\DIFdelbegin}{} %DIF PREAMBLE
\providecommand{\DIFdelend}{} %DIF PREAMBLE
%DIF FLOATSAFE PREAMBLE %DIF PREAMBLE
\providecommand{\DIFaddFL}[1]{\DIFadd{#1}} %DIF PREAMBLE
\providecommand{\DIFdelFL}[1]{\DIFdel{#1}} %DIF PREAMBLE
\providecommand{\DIFaddbeginFL}{} %DIF PREAMBLE
\providecommand{\DIFaddendFL}{} %DIF PREAMBLE
\providecommand{\DIFdelbeginFL}{} %DIF PREAMBLE
\providecommand{\DIFdelendFL}{} %DIF PREAMBLE
%DIF END PREAMBLE EXTENSION ADDED BY LATEXDIFF

\begin{document}
\maketitle

\section*{Introduction}

This is an extremely simple document that showcases some of latexdiff features.
Type
\begin{Verbatim}
latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
\end{Verbatim}
to create the difference file.  You can inspect this file directly. Then run either 
\begin{Verbatim}
pdflatex example-diff.tex
xpdf example-diff.pdf
\end{Verbatim}
or
\begin{Verbatim}
latex example-diff.tex
dvips -o example-diff.ps example-diff.dvi
gv example-diff.ps
\end{Verbatim}
to display the markup.

\section*{\DIFaddbegin \DIFadd{Yet another }\DIFaddend \DIFdelbegin 
\DIFdel{Another }\DIFdelend section title}

 \DIFdelbegin \DIFdel{A paragraph with a line only in the draft
   document.  }\DIFdelend More things could
 be said were it not for the constraints of time and space.

\DIFaddbegin \DIFadd{A paragraph with a line only in the revised
  document.  }\DIFaddend More things could be said 
were it not for the constraints of time and space.

And here is a \DIFaddbegin \DIFadd{typo}\DIFaddend \DIFdelbegin 
\DIFdel{tipo}\DIFdelend . 

Here is a table:

\begin{tabular}{ll}
Name & Description \\
\hline
Gandalf & \DIFaddbegin \DIFadd{White }\DIFaddend \DIFdelbegin 
\DIFdel{Grey }\DIFdelend \\
Saruman & \DIFaddbegin \DIFadd{Evil
}\DIFaddend \DIFdelbegin \DIFdel{White
}\DIFdelend \end{tabular}

And \DIFaddbegin \DIFadd{now for something completely different, with not
 a paragraph in sight}\DIFaddend \DIFdelbegin \DIFdel{sometimes a whole
 paragraph gets completely rewritten. In this
case latexdiff marks up the whole paragraph even if some words in it
are identical}\DIFdelend .
No change, 
no markup!
\end{document}
\end{verbatim}
}
Type 
\begin{verbatim}
pdflatex example-diff.tex
xpdf example-diff.pdf
\end{verbatim}
to make the markup visible. This is what it looks like:

\vspace{1cm}
\framebox[\textwidth]{\includegraphics[width=\textwidth]{example-diff}}
\vspace{1cm}

If you approve of all the changes in the revision, just continue with 
\verb|example-rev.tex| for the next revision.  If you like to adopt
most but not all changes you can use \verb|latexrevise| in the
following manner.  Simply edit \verb|example-diff.tex| to remove the \verb|\DIFdelbegin| and
\verb|\DIFdelend| tags around the text you would like to keep and
simply remove the text between  \verb|\DIFaddbegin| and
\verb|\DIFaddend| tags, if you do not wish to keep them.  Say you are happy with all proposed changes for the
example above except in
the last paragraph where you prefer the original draft.  You have
to change

{\scriptsize
\begin{verbatim}
...
And \DIFaddbegin \DIFadd{now for something completely different, with not
 a paragraph in sight}\DIFaddend \DIFdelbegin \DIFdel{sometimes a whole
 paragraph gets completely rewritten. In this
case latexdiff marks up the whole paragraph even if some words in it
are identical}\DIFdelend .
...
\end{verbatim}
}
into 
{\scriptsize
\begin{verbatim}
...
And \DIFdel{sometimes a whole
 paragraph gets completely rewritten. In this
case latexdiff marks up the whole paragraph even if some words in it
are identical}.
...
\end{verbatim}
}
and run 
\begin{verbatim}
latexrevise -a example-diff.tex > example-final.tex
\end{verbatim}
\verb|example-final.tex| is then almost identical to 
\verb|example-rev.tex| except for the last paragraph.

\section*{External tools}
The following is an incomplete list of wrappers written by others providing some added functionality. These are not included with the distribution but need to be downloaded and installed separately.

\begin{description}
 \item[latexdiffcite] (Author: Christer van der Meeren)  is a wrapper around latexdiff to make citations diff properly. It works by expanding \verb|\cite| type commands using the bbl or bib file, such that citations are treated just like normal text rather than as atomic in the plain latexdiff. \\
\verb|https://latexdiffcite.readthedocs.org|
\item[git-latexdiff] (lead author: Matthieu Moy) is a wrapper (bash scipt) around latexdiff that allows using it to diff two revisions of a LaTeX file under git revision control Similar functionality is provided by \verb|latexdiff-vc --git| with \verb|--flatten| option included with this distribution but git-latexdiff allows more fine-grained control on varous aspects. (Not to be confused with latexdiff-git, which is normally installed as a soft link to latexdiff-vc) \\
\verb|https://gitorious.org/git-latexdiff/|

\end{description}

\end{document}