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
18 formatting, the differences are nevertheless marked up in the source.
19 Note that old.tex and new.tex need to be real files (not pipes or
20 similar) as they are opened twice (unless "--encoding" option is used)
21 The program treats the preamble differently from the main document.
23 Differences between the preambles are found using line-based
24 differencing (similarly to the Unix diff command, but ignoring white
25 spaces). A comment, ""%DIF >"" is appended to each added line, i.e. a
26 line present in "new.tex" but not in "old.tex". Discarded lines
27 are deactivated by prepending ""%DIF <"". Changed blocks are preceded
28 by comment lines giving information about line numbers in the original
29 files. Where there are insignificant differences, the resulting file
30 "diff.tex" will be similar to "new.tex". At the end of the preamble,
31 the definitions for latexdiff markup commands are inserted. In
32 differencing the main body of the text, latexdiff attempts to satisfy
33 the following guidelines (in order of priority):
34 1. If both "old.tex" and "new.tex" are valid LaTeX, then the resulting
36 "diff.tex" should also be valid LateX. (NB If a few plain TeX
37 commands are used within "old.tex" or "new.tex" then "diff.tex" is
38 not guaranteed to work but usually will).
39 2. Significant differences are determined on the level of individual
41 words. All significant differences, including differences between
42 comments should be clearly marked in the resulting source code
43 "diff.tex".
44 3. If a changed passage contains text or text-producing commands, then
46 running "diff.tex" through LateX should produce output where added
47 and discarded passages are highlighted.
48 4. Where there are insignificant differences, e.g. in the positioning
50 of line breaks, "diff.tex" should follow the formatting of "new.tex"
51 For differencing the same algorithm as diff is used but words instead
53 of lines are compared. An attempt is made to recognize blocks which
54 are completely changed such that they can be marked up as a unit.
55 Comments are differenced line by line but the number of spaces within
56 comments is ignored. Commands including all their arguments are
57 generally compared as one unit, i.e., no mark-up is inserted into the
58 arguments of commands. However, for a selected number of commands (for
59 example, "\caption" and all sectioning commands) the last argument is
60 known to be text. This text is split into words and differenced just as
61 ordinary text (use options to show and change the list of text
62 commands, see below). As the algorithm has no detailed knowledge of
63 LaTeX, it assumes all pairs of curly braces immediately following a
64 command (i.e. a sequence of letters beginning with a backslash) are
65 arguments for that command. As a restriction to condition 1 above it
66 is thus necessary to surround all arguments with curly braces, and to
67 not insert extraneous spaces. For example, write
68 \section{\textem{This is an emphasized section title}}
70 and not
72 \section {\textem{This is an emphasized section title}}
74 or
76 \section\textem{This is an emphasized section title}
78 even though all varieties are the same to LaTeX (but see --allow-spaces
80 option which allows the second variety).
81 For environments whose content does not conform to standard LaTeX or
83 where graphical markup does not make sense all markup commands can be
84 removed by setting the PICTUREENV configuration variable, set by
85 default to "picture" and "DIFnomarkup" environments; see --config
86 option). The latter environment ("DIFnomarkup") can be used to protect
87 parts of the latex file where the markup results in illegal markup. You
88 have to surround the offending passage in both the old and new file by
89 "\begin{DIFnomarkup}" and "\end{DIFnomarkup}". You must define the
90 environment in the preambles of both old and new documents. I prefer to
91 define it as a null-environment,
92 "\newenvironment{DIFnomarkup}{}{}"
94 but the choice is yours. Any markup within the environment will be
96 removed, and generally everything within the environment will just be
97 taken from the new file.
98 It is also possible to difference files which do not have a preamble.
100 In this case, the file is processed in the main document mode, but the
101 definitions of the markup commands are not inserted.
102 All markup commands inserted by latexdiff begin with ""\DIF"". Added
104 blocks containing words, commands or comments which are in "new.tex"
105 but not in "old.tex" are marked by "\DIFaddbegin" and "\DIFaddend".
106 Discarded blocks are marked by "\DIFdelbegin" and "\DIFdelend". Within
107 added blocks all text is highlighted with "\DIFadd" like this:
108 "\DIFadd{Added text block}" Selected `safe' commands can be contained
109 in these text blocks as well (use options to show and change the list
110 of safe commands, see below). All other commands as well as braces "{"
111 and "}" are never put within the scope of "\DIFadd". Added comments
112 are marked by prepending ""%DIF > "".
113 Within deleted blocks text is highlighted with "\DIFdel". Deleted
115 comments are marked by prepending ""%DIF < "". Non-safe command and
116 curly braces within deleted blocks are commented out with
117 ""%DIFDELCMD < "".
118
120 Preamble
121 The following options determine the visual markup style by adding the
122 appropriate command definitions to the preamble. See the end of this
123 section for a description of available styles.
124 --type=markupstyle or -t markupstyle
126 Add code to preamble for selected markup style. This option defines
127 "\DIFadd" and "\DIFdel" commands. Available styles:
128 "UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE
130 CHANGEBAR CCHANGEBAR CULINECHBAR CFONTCHBAR BOLD PDFCOMMENT"
131 [ Default: "UNDERLINE" ]
133 --subtype=markstyle or -s markstyle
135 Add code to preamble for selected style for bracketing commands
136 (e.g. to mark changes in margin). This option defines
137 "\DIFaddbegin", "\DIFaddend", "\DIFdelbegin" and "\DIFdelend"
138 commands. Available styles: "SAFE MARGIN COLOR DVIPSCOL ZLABEL
139 ONLYCHANGEDPAGE (LABEL)*"
140 [ Default: "SAFE" ] * Subtype "LABEL" is deprecated
142 --floattype=markstyle or -f markstyle
144 Add code to preamble for selected style which replace standard
145 marking and markup commands within floats (e.g., marginal remarks
146 cause an error within floats so marginal marking can be disabled
147 thus). This option defines all "\DIF...FL" commands. Available
148 styles: "FLOATSAFE TRADITIONALSAFE IDENTICAL"
149 [ Default: "FLOATSAFE" ]
151 --encoding=enc or -e enc
153 Specify encoding of old.tex and new.tex. Typical encodings are
154 "ascii", "utf8", "latin1", "latin9". A list of available encodings
155 can be obtained by executing
156 "perl -MEncode -e 'print join ("\n",Encode-"encodings( ":all" )) ;'
158 >
159 If this option is used, then old.tex, new.tex are only opened once.
161 [Default encoding is utf8 unless the first few lines of the
162 preamble contain an invocation "\usepackage[..]{inputenc}" in which
163 case the encoding chosen by this command is asssumed. Note that
164 ASCII (standard latex) is a subset of utf8]
165 --preamble=file or -p file
167 Insert file at end of preamble instead of generating preamble. The
168 preamble must define the following commands "\DIFaddbegin,
169 \DIFaddend, \DIFadd{..}, \DIFdelbegin,\DIFdelend,\DIFdel{..}," and
170 varieties for use within floats "\DIFaddbeginFL, \DIFaddendFL,
171 \DIFaddFL{..}, \DIFdelbeginFL, \DIFdelendFL, \DIFdelFL{..}" (If
172 this option is set -t, -s, and -f options are ignored.)
173 --packages=pkg1,pkg2,..
175 Tell latexdiff that .tex file is processed with the packages in
176 list loaded. This is normally not necessary if the .tex file
177 includes the preamble, as the preamble is automatically scanned for
178 "\usepackage" commands. Use of the --packages option disables
179 automatic scanning, so if for any reason package specific parsing
180 needs to be switched off, use --packages=none. The following
181 packages trigger special behaviour:
182 "amsmath"
184 Configuration variable MATHARRREPL is set to "align*"
185 (Default: "eqnarray*"). (Note that many of the amsmath
186 array environments are already recognised by default as
187 such)
188 "endfloat"
190 Ensure that "\begin{figure}" and "\end{figure}" always
191 appear by themselves on a line.
192 "hyperref"
194 Change name of "\DIFadd" and "\DIFdel" commands to
195 "\DIFaddtex" and "\DIFdeltex" and define new "\DIFadd" and
196 "\DIFdel" commands, which provide a wrapper for these
197 commands, using them for the text but not for the link
198 defining command (where any markup would cause errors).
199 "apacite"
201 Redefine the commands recognised as citation commands.
202 "siunitx"
204 Treat "\SI" as equivalent to citation commands (i.e.
205 protect with "\mbox" if markup style uses ulem package.
206 "cleveref"
208 Treat "\cref,\Cref", etc as equivalent to citation commands
209 (i.e. protect with "\mbox" if markup style uses ulem
210 package.
211 "glossaries"
213 Define most of the glossaries commands as safe, protecting
214 them with \mbox'es where needed
215 "mhchem"
217 Treat "\ce" as a safe command, i.e. it will be highlighted
218 (note that "\cee" will not be highlighted in equations as
219 this leads to processing errors)
220 "chemformula" or "chemmacros"
222 Treat "\ch" as a safe command outside equations, i.e. it
223 will be highlighted (note that "\ch" will not be
224 highlighted in equations as this leads to processing
225 errors)
226 [ Default: scan the preamble for "\usepackage" commands to
228 determine
229 loaded packages. ]
230 --show-preamble
232 Print generated or included preamble commands to stdout.
233 Configuration
235 --exclude-safecmd=exclude-file or -A exclude-file or
236 --exclude-safecmd="cmd1,cmd2,..."
237 --replace-safecmd=replace-file
238 --append-safecmd=append-file or -a append-file or
239 --append-safecmd="cmd1,cmd2,..."
240 Exclude from, replace or append to the list of regular expressions
241 (RegEx) matching commands which are safe to use within the scope of
242 a "\DIFadd" or "\DIFdel" command. The file must contain one Perl-
243 RegEx per line (Comment lines beginning with # or % are ignored).
244 Note that the RegEx needs to match the whole of the token, i.e.,
245 /^regex$/ is implied and that the initial "\" of the command is not
246 included. The --exclude-safecmd and --append-safecmd options can
247 be combined with the ---replace-safecmd option and can be used
248 repeatedly to add cumulatively to the lists.
249 --exclude-safecmd and --append-safecmd can also take a comma
250 separated list as input. If a comma for one of the regex is
251 required, escape it thus "\,". In most cases it will be necessary
252 to protect the comma-separated list from the shell by putting it in
253 quotation marks.
254 --exclude-textcmd=exclude-file or -X exclude-file or
256 --exclude-textcmd="cmd1,cmd2,..."
257 --replace-textcmd=replace-file
258 --append-textcmd=append-file or -x append-file or
259 --append-textcmd="cmd1,cmd2,..."
260 Exclude from, replace or append to the list of regular expressions
261 matching commands whose last argument is text. See entry for
262 --exclude-safecmd directly above for further details.
263 --replace-context1cmd=replace-file
265 --append-context1cmd=append-file or
266 --append-context1cmd="cmd1,cmd2,..."
267 Replace or append to the list of regex matching commands whose last
268 argument is text but which require a particular context to work,
269 e.g. "\caption" will only work within a figure or table. These
270 commands behave like text commands, except when they occur in a
271 deleted section, when they are disabled, but their argument is
272 shown as deleted text.
273 --replace-context2cmd=replace-file
275 --append-context2cmd=append-file or
276 --append-context2cmd="cmd1,cmd2,..."
277 As corresponding commands for context1. The only difference is
278 that context2 commands are completely disabled in deleted sections,
279 including their arguments.
280 context2 commands are also the only commands in the preamble, whose
282 argument will be processed in word-by-word mode (which only works,
283 if they occur no more than once in the preamble). The algorithm
284 currently cannot cope with repeated context2 commands in the
285 preamble, as they occur e.g. for the "\author" argument in some
286 journal styles (not in the standard styles, though If such a
287 repetition is detected, the whole preamble will be processed in
288 line-by-line mode. In such a case, use "--replace-context2cmd"
289 option to just select the commands, which should be processed and
290 are not used repeatedly in the preamble.
291 --exclude-mboxsafecmd=exclude-file or
293 --exclude-mboxsafecmd="cmd1,cmd2,..."
294 --append-mboxsafecmd=append-file or
295 --append-mboxsafecmd="cmd1,cmd2,..."
296 Define safe commands, which additionally need to be protected by
297 encapsulating in an "\mbox{..}". This is sometimes needed to get
298 around incompatibilities between external packages and the ulem
299 package, which is used for highlighting in the default style
300 UNDERLINE as well as CULINECHBAR CFONTSTRIKE
301 --config var1=val1,var2=val2,... or -c var1=val1,..
303 -c configfile
304 Set configuration variables. The option can be repeated to set
305 different variables (as an alternative to the comma-separated
306 list). Available variables (see below for further explanations):
307 "ARRENV" (RegEx)
309 "COUNTERCMD" (RegEx)
311 "CUSTODIFCMD" (RegEx)
313 "FLOATENV" (RegEx)
315 "ITEMCMD" (RegEx)
317 "LISTENV" (RegEx)
319 "MATHARRENV" (RegEx)
321 "MATHARRREPL" (String)
323 "MATHENV" (RegEx)
325 "MATHREPL" (String)
327 "MINWORDSBLOCK" (Integer)
329 "PICTUREENV" (RegEx)
331 "SCALEDELGRAPHICS" (Float)
333 --add-to-config varenv1=pattern1,varenv2=pattern2,...
335 For configuration variables, which are a regular expression
336 (essentially those ending in ENV, COUNTERCMD and CUSTOMDIFCMD, see
337 list above) this option provides an alternative way to modify the
338 configuration variables. Instead of setting the complete pattern,
339 with this option it is possible to add an alternative pattern.
340 "varenv" must be one of the variables listed above that take a
341 regular expression as argument, and pattern is any regular
342 expression (which might need to be protected from the shell by
343 quotation). Several patterns can be added at once by using semi-
344 colons to separate them, e.g. "--add-to-config
345 "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote""
346 --show-safecmd
348 Print list of RegEx matching and excluding safe commands.
349 --show-textcmd
351 Print list of RegEx matching and excluding commands with text
352 argument.
353 --show-config
355 Show values of configuration variables.
356 --show-all
358 Combine all --show commands.
359 NB For all --show commands, no "old.tex" or "new.tex" file needs to
361 be specified, and no differencing takes place.
362 Other configuration options:
364 --allow-spaces
365 Allow spaces between bracketed or braced arguments to commands.
366 Note that this option might have undesirable side effects
367 (unrelated scope might get lumpeded with preceding commands) so
368 should only be used if the default produces erroneous results.
369 (Default requires arguments to directly follow each other without
370 intervening spaces).
371 --math-markup=level
373 Determine granularity of markup in displayed math environments:
374 Possible values for level are (both numerical and text labels are
375 acceptable):
376 "off" or 0: suppress markup for math environments. Deleted
378 equations will not appear in diff file. This mode can be used if
379 all the other modes cause invalid latex code.
380 "whole" or 1: Differencing on the level of whole equations. Even
382 trivial changes to equations cause the whole equation to be marked
383 changed. This mode can be used if processing in coarse or fine
384 mode results in invalid latex code.
385 "coarse" or 2: Detect changes within equations marked up with a
387 coarse granularity; changes in equation type (e.g.displaymath to
388 equation) appear as a change to the complete equation. This mode is
389 recommended for situations where the content and order of some
390 equations are still being changed. [Default]
391 "fine" or 3: Detect small change in equations and mark up at fine
393 granularity. This mode is most suitable, if only minor changes to
394 equations are expected, e.g. correction of typos.
395 --graphics-markup=level
397 Change highlight style for graphics embedded with C<\includegraphics> commands.
398 Possible values for level:
400 "none", "off" or 0: no highlighting for figures
402 "new-only" or 1: surround newly added or changed figures with a
404 blue frame [Default if graphicx package loaded]
405 "both" or 2: highlight new figures with a blue frame and show
407 deleted figures at reduced scale, and crossed out with a red
408 diagonal cross. Use configuration variable SCALEDELGRAPHICS to set
409 size of deleted figures.
410 Note that changes to the optional parameters will make the figure
412 appear as changed to latexdiff, and this figure will thus be
413 highlighted
414 --disable-citation-markup or --disable-auto-mbox
416 Suppress citation markup and markup of other vulnerable commands in
417 styles using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR) (the two
418 options are identical and are simply aliases)
419 --enable-citation-markup or --enforce-auto-mbox
421 Protect citation commands and other vulnerable commands in changed
422 sections with "\mbox" command, i.e. use default behaviour for ulem
423 package for other packages (the two options are identical and are
424 simply aliases)
425 Miscellaneous
427 --verbose or -V
428 Output various status information to stderr during processing.
429 Default is to work silently.
430 --driver=type
432 Choose driver for changebar package (only relevant for styles using
433 changebar: CCHANGEBAR CFONTCHBAR CULINECHBAR CHANGEBAR).
434 Possible drivers are listed in changebar manual, e.g.
435 pdftex,dvips,dvitops
436 [Default: dvips]
437 --ignore-warnings
439 Suppress warnings about inconsistencies in length between input and
440 parsed strings and missing characters. These warning messages are
441 often related to non-standard latex or latex constructions with a
442 syntax unknown to "latexdiff" but the resulting difference argument
443 is often fully functional anyway, particularly if the non-standard
444 latex only occurs in parts of the text which have not changed.
445 --label=label or -L label
447 Sets the labels used to describe the old and new files. The first
448 use of this option sets the label describing the old file and the
449 second use of the option sets the label for the new file, i.e. set
450 both labels like this "-L labelold -L labelnew". [Default: use the
451 filename and modification dates for the label]
452 --no-label
454 Suppress inclusion of old and new file names as comment in output
455 file
456 --visible-label
458 Include old and new filenames (or labels set with "--label" option)
459 as visible output.
460 --flatten
462 Replace "\input" and "\include" commands within body by the content
463 of the files in their argument. If "\includeonly" is present in
464 the preamble, only those files are expanded into the document.
465 However, no recursion is done, i.e. "\input" and "\include"
466 commands within included sections are not expanded. The included
467 files are assumed to
468 be located in the same directories as the old and new master
469 files, respectively, making it possible to organise files into old
470 and new directories. --flatten is applied recursively, so inputted
471 files can contain further "\input" statements.
472 Use of this option might result in prohibitive processing times for
474 larger documents, and the resulting difference document no longer
475 reflects the structure of the input documents.
476 --help or -h
478 Show help text
479 --version
481 Show version number
482 Internal options
484 These options are mostly for automated use by latexdiff-vc. They can be
485 used directly, but the API should be considered less stable than for
486 the other options.
487 --no-links
489 Suppress generation of hyperreferences, used for minimal diffs
490 (option --only-changes of latexdiff-vc)
491 Predefined styles
493 Major types
494 The major type determine the markup of plain text and some selected
495 latex commands outside floats by defining the markup commands
496 "\DIFadd{...}" and "\DIFdel{...}" .
497 "UNDERLINE"
499 Added text is wavy-underlined and blue, discarded text is
500 struck out and red (Requires color and ulem packages).
501 Overstriking does not work in displayed math equations such
502 that deleted parts of equation are underlined, not struck out
503 (this is a shortcoming inherent to the ulem package).
504 "CTRADITIONAL"
506 Added text is blue and set in sans-serif, and a red footnote
507 is created for each discarded piece of text. (Requires color
508 package)
509 "TRADITIONAL"
511 Like "CTRADITIONAL" but without the use of color.
512 "CFONT" Added text is blue and set in sans-serif, and discarded text
514 is red and very small size.
515 "FONTSTRIKE"
517 Added tex is set in sans-serif, discarded text small and
518 struck out
519 "CCHANGEBAR"
521 Added text is blue, and discarded text is red. Additionally,
522 the changed text is marked with a bar in the margin (Requires
523 color and changebar packages).
524 "CFONTCHBAR"
526 Like "CFONT" but with additional changebars (Requires color
527 and changebar packages).
528 "CULINECHBAR"
530 Like "UNDERLINE" but with additional changebars (Requires
531 color, ulem and changebar packages).
532 "CHANGEBAR"
534 No mark up of text, but mark margins with changebars
535 (Requires changebar package).
536 "INVISIBLE"
538 No visible markup (but generic markup commands will still be
539 inserted.
540 "BOLD" Added text is set in bold face, discarded is not shown.
542 "PDFCOMMENT"
544 The pdfcomment package is used to underline new text, and
545 mark deletions with a PDF comment. Note that this markup
546 might appear differently or not at all based on the pdf
547 viewer used. The viewer with best support for pdf markup is
548 probably acroread. This style is only recommended if the
549 number of differences is small.
550 Subtypes
552 The subtype defines the commands that are inserted at the begin and end
553 of added or discarded blocks, irrespectively of whether these blocks
554 contain text or commands (Defined commands: "\DIFaddbegin, \DIFaddend,
555 \DIFdelbegin, \DIFdelend")
556 "SAFE" No additional markup (Recommended choice)
558 "MARGIN" Mark beginning and end of changed blocks with symbols in the
560 margin nearby (using the standard "\marginpar" command - note
561 that this sometimes moves somewhat from the intended
562 position.
563 "COLOR" An alternative way of marking added passages in blue, and
565 deleted ones in red. (It is recommeneded to use instead the
566 main types to effect colored markup, although in some cases
567 coloring with dvipscol can be more complete, for example with
568 citation commands).
569 "DVIPSCOL"
571 An alternative way of marking added passages in blue, and
572 deleted ones in red. Note that "DVIPSCOL" only works with the
573 dvips converter, e.g. not pdflatex. (it is recommeneded to
574 use instead the main types to effect colored markup, although
575 in some cases coloring with dvipscol can be more complete).
576 "ZLABEL" can be used to highlight only changed pages, but requires
578 post-processing. It is recommend to not call this option
579 manually but use "latexdiff-vc" with "--only-changes" option.
580 Alternatively, use the script given within preamble of diff
581 files made using this style.
582 "ONLYCHANGEDPAGE"
584 also highlights changed pages, without the need for post-
585 processing, but might not work reliably if there is floating
586 material (figures, tables).
587 "LABEL" is similar to "ZLABEL", but does not need the zref package
589 and works less reliably (deprecated).
590 Float Types
592 Some of the markup used in the main text might cause problems when used
593 within floats (e.g. figures or tables). For this reason alternative
594 versions of all markup commands are used within floats. The float type
595 defines these alternative commands.
596 "FLOATSAFE"
598 Use identical markup for text as in the main body, but set
599 all commands marking the begin and end of changed blocks to
600 null-commands. You have to choose this float type if your
601 subtype is "MARGIN" as "\marginpar" does not work properly
602 within floats.
603 "TRADITIONALSAFE"
605 Mark additions the same way as in the main text. Deleted
606 environments are marked by angular brackets \[ and \] and the
607 deleted text is set in scriptscript size. This float type
608 should always be used with the "TRADITIONAL" and
609 "CTRADITIONAL" markup types as the \footnote command does not
610 work properly in floating environments.
611 "IDENTICAL"
613 Make no difference between the main text and floats.
614 Configuration Variables
616 "ARRENV" If a match to "ARRENV" is found within an inline math
617 environment within a deleted or added block, then the inlined
618 math is surrounded by "\mbox{"..."}". This is necessary as
619 underlining does not work within inlined array environments.
620 [ Default: "ARRENV"="(?:array|[pbvBV]matrix)"
622 "COUNTERCMD"
624 If a command in a deleted block which is also in the textcmd
625 list matches "COUNTERCMD" then an additional command
626 "\addtocounter{"cntcmd"}{-1}", where cntcmd is the matching
627 command, is appended in the diff file such that the numbering
628 in the diff file remains synchronized with the numbering in
629 the new file.
630 [ Default: "COUNTERCMD"="(?:footnote|part|section|subsection"
632 ...
633 "|subsubsection|paragraph|subparagraph)" ]
635 "CUSTOMDIFCMD"
637 This option is for advanced users and allows definition of
638 special versions of commands, which do not work as safe
639 commands.
640 Commands in "CUSTOMDIFCMD" that occur in added or deleted
642 blocks will be given an ADD or DEL prefix. The prefixed
643 versions of the command must be defined in the preamble,
644 either by putting them in the preamble of at least the new
645 file, or by creating a custom preamble file (Option
646 --preamble). For example the command "\blindtext" (from
647 package blindtext) does not interact well with underlining,
648 so that for the standard markup type, it is not satisfactory
649 to define it as a safe command. Instead, a customised
650 versions without underlining can be defined in the preamble:
651 "\newcommand{\DELblindtext}{{\color{red}\blindtext}}"
653 "\newcommand{\ADDblindtext}{{\color{blue}\blindtext}}"
655 and then latexdiff should be invoked with the option "-c
657 CUSTOMDIFCMD=blindtext".
658 [ Default: none ]
660 "FLOATENV"
662 Environments whose name matches the regular expression in
663 "FLOATENV" are considered floats. Within these environments,
664 the latexdiff markup commands are replaced by their FL
665 variaties.
666 [ Default: "(?:figure|table|plate)[\w\d*@]*" ]
668 "ITEMCMD" Commands representing new item line with list environments.
670 [ Default: \"item" ]
672 "LISTENV" Environments whose name matches the regular expression in
674 "LISTENV" are list environments.
675 [ Default: "(?:itemize|enumerate|description)" ]
677 "MATHENV","MATHREPL"
679 If both \begin and \end for a math environment (environment
680 name matching "MATHENV" or \[ and \]) are within the same
681 deleted block, they are replaced by a \begin and \end
682 commands for "MATHREPL" rather than being commented out.
683 [ Default: "MATHENV"="(?:displaymath|equation)" ,
685 "MATHREPL"="displaymath" ]
686 "MATHARRENV","MATHARRREPL"
688 as "MATHENV","MATHREPL" but for equation arrays
689 [ Default: "MATHARRENV"="eqnarray\*?" ,
691 "MATHREPL"="eqnarray" ]
692 "MINWORDSBLOCK"
694 Minimum number of tokens required to form an independent
695 block. This value is used in the algorithm to detect changes
696 of complete blocks by merging identical text parts of less
697 than "MINWORDSBLOCK" to the preceding added and discarded
698 parts.
699 [ Default: 3 ]
701 "PICTUREENV"
703 Within environments whose name matches the regular expression
704 in "PICTUREENV" all latexdiff markup is removed (in
705 pathologic cases this might lead to inconsistent markup but
706 this situation should be rare).
707 [ Default: "(?:picture|DIFnomarkup)[\w\d*@]*" ]
709 "SCALEDELGRAPHICS"
711 If "--graphics-markup=both" is chosen, "SCALEDELGRAPHICS" is
712 the factor, by which deleted figures will be scaled (i.e. 0.5
713 implies they are shown at half linear size).
714 [ Default: 0.5 ]
716 "VERBATIMENV"
718 RegEx describing environments like verbatim, whose contents
719 should be taken verbatim. The content of these environments
720 will not be processed in any way: deleted content is
721 commented out, new content is not marked up
722 [ Default: "comment" ]
724 "VERBATIMLINEENV"
726 RegEx describing environments like verbatim, whose contents
727 should be taken verbatim. The content of environments
728 described by VERBATIMLINEENV are compared in line mode, and
729 changes are marked up using the listings package. The markup
730 style is set based on the chosen mains markup type (Option
731 -t), or on an analysis of the preamble. Note that
732 "listings.sty" must be installed. If this file is not found
733 the fallback solution is to treat VERBATIMLINEENV
734 environments treated exactly the same way as VERBATIMENV
735 environments.
736 [ Default: "(?:verbatim[*]?|lstlisting" ]
738
740 Citations result in overfull boxes
741 There is an incompatibility between the "ulem" package, which
742 "latexdiff" uses for underlining and striking out in the
743 UNDERLINE style, the default style, and the way citations are
744 generated. In order to be able to mark up citations properly,
745 they are enclosed with an "\mbox" command. As mboxes cannot
746 be broken across lines, this procedure frequently results in
747 overfull boxes, possibly obscuring the content as it extends
748 beyond the right margin. The same occurs for some other
749 packages (e.g., siunitx). If this is a problem, you have two
750 possibilities.
751 1. Use "CFONT" type markup (option "-t CFONT"): If this
753 markup is chosen, then changed citations are no longer marked
754 up with the wavy line (additions) or struck out (deletions),
755 but are still highlighted in the appropriate color, and
756 deleted text is shown with a different font. Other styles not
757 using the "ulem" package will also work.
758 2. Choose option "--disable-citation-markup" which turns off
760 the marking up of citations: deleted citations are no longer
761 shown, and added citations are shown without markup. (This
762 was the default behaviour of latexdiff at versions 0.6 and
763 older)
764 For custom packages you can define the commands which need to
766 be protected by "\mbox" with "--append-mboxsafecmd" and
767 "--excludemboxsafecmd" options (submit your lists of command
768 as feature request at github page to set the default
769 behaviour of future versions, see section 6)
770 Changes in complicated mathematical equations result in latex
772 processing errors
773 Try options "--math-markup=whole". If even that fails, you
774 can turn off mark up for equations with "--math-markup=off".
775 How can I just show the pages where changes had been made
777 Use options -"-s ZLABEL" (some postprocessing required) or
778 "-s ONLYCHANGEDPAGE". "latexdiff-vc --ps|--pdf" with
779 "--only-changes" option takes care of the post-processing for
780 you (requires zref package to be installed).
781
783 Option allow-spaces not implemented entirely consistently. It breaks
784 the rules that number and type of white space does not matter, as
785 different numbers of inter-argument spaces are treated as significant.
786 Please submit bug reports using the issue tracker of the github
788 repository page https://github.com/ftilmann/latexdiff.git, or send them
789 to tilmann -- AT -- gfz-potsdam.de. Include the version number of
790 latexdiff (from comments at the top of the source or use --version).
791 If you come across latex files that are error-free and conform to the
792 specifications set out above, and whose differencing still does not
793 result in error-free latex, please send me those files, ideally edited
794 to only contain the offending passage as long as that still reproduces
795 the problem. If your file relies on non-standard class files, you must
796 include those. I will not look at examples where I have trouble to
797 latex the original files.
798
800 latexrevise, latexdiff-vc
801
803 latexdiff does not make use of external commands and thus should run on
804 any platform supporting Perl 5.6 or higher. If files with encodings
805 other than ASCII or UTF-8 are processed, Perl 5.8 or higher is
806 required.
807 The standard version of latexdiff requires installation of the Perl
809 package "Algorithm::Diff" (available from www.cpan.org -
810 http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone
811 version, latexdiff-so, which has this package inlined, is available,
812 too. latexdiff-fast requires the diff command to be present.
813
815 Version 1.3.0 Copyright (C) 2004-2018 Frederik Tilmann
816 This program is free software; you can redistribute it and/or modify it
818 under the terms of the GNU General Public License Version 3
819 Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N.
821 Becker, T. Doerges, K. Huebner, T. Connors, Sebastian Gouezel and many
822 others. Thanks to the many people who sent in bug reports, feature
823 suggestions, and other feedback.
824perl v5.22.1 2018-10-07 LATEXDIFF(1)