1LATEXDIFF(1) LATEXDIFF(1)
2
6 latexdiff - determine and markup differences between two latex files
7
9 latexdiff [ OPTIONS ] old.tex new.tex > diff.tex
10
12 Briefly, latexdiff is a utility program to aid in the management of
13 revisions of latex documents. It compares two valid latex files, here
14 called "old.tex" and "new.tex", finds significant differences between
15 them (i.e., ignoring the number of white spaces and position of line
16 breaks), and adds special commands to highlight the differences. Where
17 visual highlighting is not possible, e.g. for changes in the format‐
18 ting, the differences are nevertheless marked up in the source.
19 The program treats the preamble differently from the main document.
21 Differences between the preambles are found using line-based differenc‐
22 ing (similarly to the Unix diff command, but ignoring white spaces). A
23 comment, ""%DIF >"" is appended to each added line, i.e. a line present
24 in "new.tex" but not in "old.tex". Discarded lines
25 are deactivated by prepending ""%DIF <"". Changed blocks are preceded
26 by comment lines giving information about line numbers in the original
27 files. Where there are insignificant differences, the resulting file
28 "diff.tex" will be similar to "new.tex". At the end of the preamble,
29 the definitions for latexdiff markup commands are inserted. In differ‐
30 encing the main body of the text, latexdiff attempts to satisfy the
31 following guidelines (in order of priority):
32 1 If both "old.tex" and "new.tex" are valid LaTeX, then the resulting
34 "diff.tex" should also be valid LateX. (NB If a few plain TeX com‐
35 mands are used within "old.tex" or "new.tex" then "diff.tex" is not
36 guaranteed to work but usually will).
37 2 Significant differences are determined on the level of individual
39 words. All significant differences, including differences between
40 comments should be clearly marked in the resulting source code
41 "diff.tex".
42 3 If a changed passage contains text or text-producing commands, then
44 running "diff.tex" through LateX should produce output where added
45 and discarded passages are highlighted.
46 4 Where there are insignificant differences, e.g. in the positioning
48 of line breaks, "diff.tex" should follow the formatting of "new.tex"
49 For differencing the same algorithm as diff is used but words instead
51 of lines are compared. An attempt is made to recognize blocks which
52 are completely changed such that they can be marked up as a unit. Com‐
53 ments are differenced line by line but the number of spaces within com‐
54 ments is ignored. Commands including all their arguments are generally
55 compared as one unit, i.e., no mark-up is inserted into the arguments
56 of commands. However, for a selected number of commands (for example,
57 "\caption" and all sectioning commands) the last argument is known to
58 be text. This text is split into words and differenced just as ordinary
59 text (use options to show and change the list of text commands, see
60 below). As the algorithm has no detailed knowledge of LaTeX, it assumes
61 all pairs of curly braces immediately following a command (i.e. a
62 sequence of letters beginning with a backslash) are arguments for that
63 command. As a restriction to condition 1 above it is thus necessary to
64 surround all arguments with curly braces, and to not insert extraneous
65 spaces. For example, write
66 \section{\textem{This is an emphasized section title}}
68 and not
70 \section {\textem{This is an emphasized section title}}
72 or
74 \section\textem{This is an emphasized section title}
76 even though all varieties are the same to LaTeX (but see --allow-spaces
78 option which allows the second variety).
79 For environments whose content does not conform to standard LaTeX or
81 where graphical markup does not make sense all markup commands can be
82 removed by setting the PICTUREENV configuration variable, set by
83 default to "picture" and "DIFnomarkup" environments; see --config
84 option). The latter environment ("DIFnomarkup") can be used to protect
85 parts of the latex file where the markup results in illegal markup. You
86 have to surround the offending passage in both the old and new file by
87 "\begin{DIFnomarkup}" and "\end{DIFnomarkup}". You must define the
88 environment in the preambles of both old and new documents. I prefer to
89 define it as a null-environment,
90 "\newenvironment{DIFnomarkup}{}{}"
92 but the choice is yours. Any markup within the environment will be
94 removed, and generally everything within the environment will just be
95 taken from the new file.
96 It is also possible to difference files which do not have a preamble.
98 In this case, the file is processed in the main document mode, but the
99 definitions of the markup commands are not inserted.
100 All markup commands inserted by latexdiff begin with ""\DIF"". Added
102 blocks containing words, commands or comments which are in "new.tex"
103 but not in "old.tex" are marked by "\DIFaddbegin" and "\DIFaddend".
104 Discarded blocks are marked by "\DIFdelbegin" and "\DIFdelend". Within
105 added blocks all text is highlighted with "\DIFadd" like this:
106 "\DIFadd{Added text block}" Selected `safe' commands can be contained
107 in these text blocks as well (use options to show and change the list
108 of safe commands, see below). All other commands as well as braces "{"
109 and "}" are never put within the scope of "\DIFadd". Added comments
110 are marked by prepending ""%DIF > "".
111 Within deleted blocks text is highlighted with "\DIFdel". Deleted com‐
113 ments are marked by prepending ""%DIF < "". Non-safe command and curly
114 braces within deleted blocks are commented out with ""%DIFDELCMD < "".
115
117 Preamble
118 The following options determine the visual markup style by adding the
120 appropriate command definitions to the preamble. See the end of this
121 section for a description of available styles.
122 --type=markupstyle or -t markupstyle
124 Add code to preamble for selected markup style. This option defines
125 "\DIFadd" and "\DIFdel" commands. Available styles:
126 "UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
128 CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCBHBAR"
129 [ Default: "UNDERLINE" ]
131 --subtype=markstyle or -s markstyle
133 Add code to preamble for selected style for bracketing commands
134 (e.g. to mark changes in margin). This option defines "\DIFaddbe‐
135 gin", "\DIFaddend", "\DIFdelbegin" and "\DIFdelend" commands.
136 Available styles: "SAFE MARGINAL DVIPSCOL"
137 [ Default: "SAFE" ]
139 --floattype=markstyle or -f markstyle
141 Add code to preamble for selected style which replace standard
142 marking and markup commands within floats (e.g., marginal remarks
143 cause an error within floats so marginal marking can be disabled
144 thus). This option defines all "\DIF...FL" commands. Available
145 styles: "FLOATSAFE TRADITIONALSAFE IDENTICAL"
146 [ Default: "FLOATSAFE" ]
148 --encoding=enc or -e enc
150 Specify encoding of old.tex and new.tex. Typical encodings are
151 "ascii", "utf8", "latin1", "latin9". A list of available encodings
152 can be obtained by executing
153 "perl -MEncode -e 'print join ("\n",Encode-"encodings( ":all" )) ;'
155 >
156 [Default encoding is utf8 unless the first few lines of the pream‐
158 ble contain an invocation "\usepackage[..]{inputenc}" in which case
159 the encoding chosen by this command is asssumed. Note that ASCII
160 (standard latex) is a subset of utf8]
161 --preamble=file or -p file
163 Insert file at end of preamble instead of generating preamble. The
164 preamble must define the following commands "\DIFaddbegin, \DIFad‐
165 dend, \DIFadd{..}, \DIFdelbegin,\DIFdelend,\DIFdel{..}," and vari‐
166 eties for use within floats "\DIFaddbeginFL, \DIFaddendFL,
167 \DIFaddFL{..}, \DIFdelbeginFL, \DIFdelendFL, \DIFdelFL{..}" (If
168 this option is set -t, -s, and -f options are ignored.)
169 --show-preamble
171 Print generated or included preamble commands to stdout.
172 Configuration
174 --exclude-safecmd=exclude-file or -A exclude-file or
176 --exclude-safecmd="cmd1,cmd2,..."
177 --replace-safecmd=replace-file
178 --append-safecmd=append-file or -a append-file or
179 --append-safecmd="cmd1,cmd2,..."
180 Exclude from, replace or append to the list of regular expressions
181 (RegEx) matching commands which are safe to use within the scope of
182 a "\DIFadd" or "\DIFdel" command. The file must contain one Perl-
183 RegEx per line (Comment lines beginning with # or % are ignored).
184 Note that the RegEx needs to match the whole of the token, i.e.,
185 /^regex$/ is implied and that the initial "\" of the command is not
186 included. The --exclude-safecmd and --append-safecmd options can
187 be combined with the ---replace-safecmd option and can be used
188 repeatedly to add cumulatively to the lists.
189 --exclude-safecmd and --append-safecmd can also take a comma sepa‐
190 rated list as input. If a comma for one of the regex is required,
191 escape it thus "\,". In most cases it will be necessary to protect
192 the comma-separated list from the shell by putting it in quotation
193 marks.
194 --exclude-textcmd=exclude-file or -X exclude-file or
196 --exclude-textcmd="cmd1,cmd2,..."
197 --replace-textcmd=replace-file
198 --append-textcmd=append-file or -x append-file or
199 --append-textcmd="cmd1,cmd2,..."
200 Exclude from, replace or append to the list of regular expressions
201 matching commands whose last argument is text. See entry for
202 --exclude-safecmd directly above for further details.
203 --config var1=val1,var2=val2,... or -c var1=val1,..
205 -c configfile
206 Set configuration variables. The option can be repeated to set
207 different variables (as an alternative to the comma-separated
208 list). Available variables (see below for further explanations):
209 "MINWORDSBLOCK" (integer)
211 "FLOATENV" (RegEx)
213 "PICTUREENV" (RegEx)
215 "MATHENV" (RegEx)
217 "MATHREPL" (String)
219 "MATHARRENV" (RegEx)
221 "MATHARRREPL" (String)
223 "COUNTERCMD" (RegEx)
225 --show-safecmd
227 Print list of RegEx matching and excluding safe commands.
228 --show-textcmd
230 Print list of RegEx matching and excluding commands with text argu‐
231 ment.
232 --show-config
234 Show values of configuration variables.
235 --show-all
237 Combine all --show commands.
238 NB For all --show commands, no "old.tex" or "new.tex" file needs to
240 be specified, and no differencing takes place.
241 Miscellaneous
243 --verbose or -V
245 Output various status information to stderr during processing.
246 Default is to work silently.
247 --ignore-warnings
249 Suppress warnings about inconsistencies in length between input and
250 parsed strings and missing characters. These warning messages are
251 often related to non-standard latex or latex constructions with a
252 syntax unknown to "latexdiff" but the resulting difference argument
253 is often fully functional anyway, particularly if the non-standard
254 latex only occurs in parts of the text which have not changed.
255 --allow-spaces
257 Allow spaces between bracketed or braced arguments to commands.
258 Note that this option might have undesirable side effects (unre‐
259 lated scope might get lumpeded with preceding commands) so should
260 only be used if the default produces erroneous results. (Default
261 requires arguments to directly follow each other without interven‐
262 ing spaces).
263 --help or -h
265 Show help text
266 --version
268 Show version number
269 Predefined styles
271 Major types
273 The major type determine the markup of plain text and some selected
275 latex commands outside floats by defining the markup commands
276 "\DIFadd{...}" and "\DIFdel{...}" .
277 "UNDERLINE"
279 Added text is wavy-underlined and blue, discarded text is
280 struck out and red (Requires color and ulem packages). Over‐
281 striking does not work in displayed math equations such that
282 deleted parts of equation are underlined, not struck out
283 (this is a shortcoming inherent to the ulem package).
284 "CTRADITIONAL"
286 Added text is blue and set in sans-serif, and a red footnote
287 is created for each discarded piece of text. (Requires color
288 package)
289 "TRADITIONAL"
291 Like "CTRADITIONAL" but without the use of color.
292 "CFONT" Added text is blue and set in sans-serif, and discarded text
294 is red and very small size.
295 "FONTSTRIKE"
297 Added tex is set in sans-serif, discarded text small and
298 struck out
299 "CCHANGEBAR"
301 Added text is blue, and discarded text is red. Additionally,
302 the changed text is marked with a bar in the margin (Requires
303 color and changebar packages).
304 "CFONTCHBAR"
306 Like "CFONT" but with additional changebars (Requires color
307 and changebar packages).
308 "CULINECHBAR"
310 Like "UNDERLINE" but with additional changebars (Requires
311 color, ulem and changebar packages).
312 "CHANGEBAR"
314 No mark up of text, but mark margins with changebars
315 (Requires changebar package).
316 "INVISIBLE"
318 No visible markup (but generic markup commands will still be
319 inserted.
320 Subtypes
322 The subtype defines the commands that are inserted at the begin and end
324 of added or discarded blocks, irrespectively of whether these blocks
325 contain text or commands (Defined commands: "\DIFaddbegin, \DIFaddend,
326 \DIFdelbegin, \DIFdelend")
327 "SAFE" No additional markup (Recommended choice)
329 "MARGIN" Mark beginning and end of changed blocks with symbols in the
331 margin nearby (using the standard "\marginpar" command - note
332 that this sometimes moves somewhat from the intended posi‐
333 tion.
334 "DVIPSCOL"
336 An alternative way of marking added passages in blue, and
337 deleted ones in red. Note that "DVIPSCOL" only works with the
338 dvips converter, e.g. not pdflatex. (it is recommeneded to
339 use instead the main types to effect colored markup, although
340 in some cases coloring with dvipscol can be more complete).
341 Float Types
343 Some of the markup used in the main text might cause problems when used
345 within floats (e.g. figures or tables). For this reason alternative
346 versions of all markup commands are used within floats. The float type
347 defines these alternative commands.
348 "FLOATSAFE"
350 Use identical markup for text as in the main body, but set
351 all commands marking the begin and end of changed blocks to
352 null-commands. You have to choose this float type if your
353 subtype is "MARGIN" as "\marginpar" does not work properly
354 within floats.
355 "TRADITIONALSAFE"
357 Mark additions the same way as in the main text. Deleted
358 environments are marked by angular brackets \[ and \] and the
359 deleted text is set in scriptscript size. This float type
360 should always be used with the "TRADITIONAL" and "CTRADI‐
361 TIONAL" markup types as the \footnote command does not work
362 properly in floating environments.
363 "IDENTICAL"
365 Make no difference between the main text and floats.
366 Configuration Variables
368 "MINWORDSBLOCK"
370 Minimum number of tokens required to form an independent
371 block. This value is used in the algorithm to detect changes
372 of complete blocks by merging identical text parts of less
373 than "MINWORDSBLOCK" to the preceding added and discarded
374 parts.
375 [ Default: 3 ]
377 "FLOATENV"
379 Environments whose name matches the regular expression in
380 "FLOATENV" are considered floats. Within these environments,
381 the latexdiff markup commands are replaced by their FL vari‐
382 aties.
383 [ Default: "(?:figure⎪table⎪plate)[\w\d*@]*" ]
385 "PICTUREENV"
387 Within environments whose name matches the regular expression
388 in "PICTUREENV" all latexdiff markup is removed (in patho‐
389 logic cases this might lead to
390 inconsistent markup but this situation should be rare).
391 [ Default: "(?:picture⎪DIFnomarkup)[\w\d*@]*" ]
393 "MATHENV","MATHREPL"
395 If both \begin and \end for a math environment (environment
396 name matching "MATHENV" or \[ and \]) are within the same
397 deleted block, they are replaced by a \begin and \end com‐
398 mands for "MATHREPL" rather than being commented out.
399 [ Default: "MATHENV"="(?:displaymath⎪equation)" , "MATH‐
401 REPL"="displaymath" ]
402 "MATHARRENV","MATHARRREPL"
404 as "MATHENV","MATHREPL" but for equation arrays
405 [ Default: "MATHARRENV"="eqnarray\*?" , "MATHREPL"="eqnar‐
407 ray" ]
408 "COUNTERCMD"
410 If a command in a deleted block which is also in the textcmd
411 list matches "COUNTERCMD" then an additional command "\addto‐
412 counter{"cntcmd"}{-1}", where cntcmd is the matching command,
413 is appended in the diff file such that the numbering in the
414 diff file remains synchronized with the numbering in the new
415 file.
416 [ Default: "COUNTERCMD"="(?:footnote⎪part⎪section⎪subsection"
418 ...
419 "⎪subsubsection⎪paragraph⎪subparagraph)" ]
421
423 UTF-8 support requires a relatively new version of perl (5.8.0 is suf‐
424 ficient but 5.6.2 up would work OK, too).
425 Option allow-spaces not implemented entirely consistently. It breaks
427 the rules that number and type of white space does not matter, as dif‐
428 ferent numbers of inter-argument spaces are treated as significant.
429 Please send bug reports to tilmann@esc.cam.ac.uk. Include the serial
431 number of latexdiff (from comments at the top of the source or use
432 --version). If you come across latex files that are error-free and
433 conform to the specifications set out above, and whose differencing
434 still does not result in error-free latex, please send me those files,
435 ideally edited to only contain the offending passage as long as that
436 still reproduces the problem.
437
439 latexrevise
440
442 latexdiff does not make use of external commands and thus should run on
443 any platform supporting Perl 5.6 or higher. If files with encodings
444 other than ASCII or UTF-8 are processed, Perl 5.8 or higher is
445 required.
446 The standard version of latexdiff requires installation of the Perl
448 package "Algorithm::Diff" (available from www.cpan.org -
449 http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone
450 version, latexdiff-so, which has this package inlined, is available,
451 too. latexdiff-fast requires the diff command to be present.
452
454 Copyright (C) 2004-2006 Frederik Tilmann
455 This program is free software; you can redistribute it and/or modify it
457 under the terms of the GNU General Public License Version 2
458 Contributors of bug reports and fixes: V. Kuhlmann, R. Sloan, J. Pais‐
460 ley
461perl v5.8.5 2006-11-27 LATEXDIFF(1)