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", "biblatex"
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. Also handles files
472 included by the import package ("\import" and "\subimport"), and
473 "\subfile" command.
474 Use of this option might result in prohibitive processing times for
476 larger documents, and the resulting difference document no longer
477 reflects the structure of the input documents.
478 --filter-script=filterscript
480 Run files through this filterscript (full path preferred) before
481 processing. The filterscript must take STDIN input and output to
482 STDOUT. When coupled with --flatten, each file will be run through
483 the filter as it is brought in.
484 --ignore-filter-stderr
486 When running with --filter-script, STDERR from the script may cause
487 readability issues. Turn this flag on to ignore STDERR from the
488 filter script.
489 --help or -h
491 Show help text
492 --version
494 Show version number
495 Internal options
497 These options are mostly for automated use by latexdiff-vc. They can be
498 used directly, but the API should be considered less stable than for
499 the other options.
500 --no-links
502 Suppress generation of hyperreferences, used for minimal diffs
503 (option --only-changes of latexdiff-vc)
504 Predefined styles
506 Major types
507 The major type determine the markup of plain text and some selected
508 latex commands outside floats by defining the markup commands
509 "\DIFadd{...}" and "\DIFdel{...}" .
510 "UNDERLINE"
512 Added text is wavy-underlined and blue, discarded text is
513 struck out and red (Requires color and ulem packages).
514 Overstriking does not work in displayed math equations such
515 that deleted parts of equation are underlined, not struck out
516 (this is a shortcoming inherent to the ulem package).
517 "CTRADITIONAL"
519 Added text is blue and set in sans-serif, and a red footnote
520 is created for each discarded piece of text. (Requires color
521 package)
522 "TRADITIONAL"
524 Like "CTRADITIONAL" but without the use of color.
525 "CFONT" Added text is blue and set in sans-serif, and discarded text
527 is red and very small size.
528 "FONTSTRIKE"
530 Added tex is set in sans-serif, discarded text small and
531 struck out
532 "CCHANGEBAR"
534 Added text is blue, and discarded text is red. Additionally,
535 the changed text is marked with a bar in the margin (Requires
536 color and changebar packages).
537 "CFONTCHBAR"
539 Like "CFONT" but with additional changebars (Requires color
540 and changebar packages).
541 "CULINECHBAR"
543 Like "UNDERLINE" but with additional changebars (Requires
544 color, ulem and changebar packages).
545 "CHANGEBAR"
547 No mark up of text, but mark margins with changebars
548 (Requires changebar package).
549 "INVISIBLE"
551 No visible markup (but generic markup commands will still be
552 inserted.
553 "BOLD" Added text is set in bold face, discarded is not shown.
555 "PDFCOMMENT"
557 The pdfcomment package is used to underline new text, and
558 mark deletions with a PDF comment. Note that this markup
559 might appear differently or not at all based on the pdf
560 viewer used. The viewer with best support for pdf markup is
561 probably acroread. This style is only recommended if the
562 number of differences is small.
563 Subtypes
565 The subtype defines the commands that are inserted at the begin and end
566 of added or discarded blocks, irrespectively of whether these blocks
567 contain text or commands (Defined commands: "\DIFaddbegin, \DIFaddend,
568 \DIFdelbegin, \DIFdelend")
569 "SAFE" No additional markup (Recommended choice)
571 "MARGIN" Mark beginning and end of changed blocks with symbols in the
573 margin nearby (using the standard "\marginpar" command - note
574 that this sometimes moves somewhat from the intended
575 position.
576 "COLOR" An alternative way of marking added passages in blue, and
578 deleted ones in red. (It is recommeneded to use instead the
579 main types to effect colored markup, although in some cases
580 coloring with dvipscol can be more complete, for example with
581 citation commands).
582 "DVIPSCOL"
584 An alternative way of marking added passages in blue, and
585 deleted ones in red. Note that "DVIPSCOL" only works with the
586 dvips converter, e.g. not pdflatex. (it is recommeneded to
587 use instead the main types to effect colored markup, although
588 in some cases coloring with dvipscol can be more complete).
589 "ZLABEL" can be used to highlight only changed pages, but requires
591 post-processing. It is recommend to not call this option
592 manually but use "latexdiff-vc" with "--only-changes" option.
593 Alternatively, use the script given within preamble of diff
594 files made using this style.
595 "ONLYCHANGEDPAGE"
597 also highlights changed pages, without the need for post-
598 processing, but might not work reliably if there is floating
599 material (figures, tables).
600 "LABEL" is similar to "ZLABEL", but does not need the zref package
602 and works less reliably (deprecated).
603 Float Types
605 Some of the markup used in the main text might cause problems when used
606 within floats (e.g. figures or tables). For this reason alternative
607 versions of all markup commands are used within floats. The float type
608 defines these alternative commands.
609 "FLOATSAFE"
611 Use identical markup for text as in the main body, but set
612 all commands marking the begin and end of changed blocks to
613 null-commands. You have to choose this float type if your
614 subtype is "MARGIN" as "\marginpar" does not work properly
615 within floats.
616 "TRADITIONALSAFE"
618 Mark additions the same way as in the main text. Deleted
619 environments are marked by angular brackets \[ and \] and the
620 deleted text is set in scriptscript size. This float type
621 should always be used with the "TRADITIONAL" and
622 "CTRADITIONAL" markup types as the \footnote command does not
623 work properly in floating environments.
624 "IDENTICAL"
626 Make no difference between the main text and floats.
627 Configuration Variables
629 "ARRENV" If a match to "ARRENV" is found within an inline math
630 environment within a deleted or added block, then the inlined
631 math is surrounded by "\mbox{"..."}". This is necessary as
632 underlining does not work within inlined array environments.
633 [ Default: "ARRENV"="(?:array|[pbvBV]matrix)"
635 "COUNTERCMD"
637 If a command in a deleted block which is also in the textcmd
638 list matches "COUNTERCMD" then an additional command
639 "\addtocounter{"cntcmd"}{-1}", where cntcmd is the matching
640 command, is appended in the diff file such that the numbering
641 in the diff file remains synchronized with the numbering in
642 the new file.
643 [ Default: "COUNTERCMD"="(?:footnote|part|section|subsection"
645 ...
646 "|subsubsection|paragraph|subparagraph)" ]
648 "CUSTOMDIFCMD"
650 This option is for advanced users and allows definition of
651 special versions of commands, which do not work as safe
652 commands.
653 Commands in "CUSTOMDIFCMD" that occur in added or deleted
655 blocks will be given an ADD or DEL prefix. The prefixed
656 versions of the command must be defined in the preamble,
657 either by putting them in the preamble of at least the new
658 file, or by creating a custom preamble file (Option
659 --preamble). For example the command "\blindtext" (from
660 package blindtext) does not interact well with underlining,
661 so that for the standard markup type, it is not satisfactory
662 to define it as a safe command. Instead, a customised
663 versions without underlining can be defined in the preamble:
664 "\newcommand{\DELblindtext}{{\color{red}\blindtext}}"
666 "\newcommand{\ADDblindtext}{{\color{blue}\blindtext}}"
668 and then latexdiff should be invoked with the option "-c
670 CUSTOMDIFCMD=blindtext".
671 [ Default: none ]
673 "FLOATENV"
675 Environments whose name matches the regular expression in
676 "FLOATENV" are considered floats. Within these environments,
677 the latexdiff markup commands are replaced by their FL
678 variaties.
679 [ Default: "(?:figure|table|plate)[\w\d*@]*" ]
681 "ITEMCMD" Commands representing new item line with list environments.
683 [ Default: \"item" ]
685 "LISTENV" Environments whose name matches the regular expression in
687 "LISTENV" are list environments.
688 [ Default: "(?:itemize|enumerate|description)" ]
690 "MATHENV","MATHREPL"
692 If both \begin and \end for a math environment (environment
693 name matching "MATHENV" or \[ and \]) are within the same
694 deleted block, they are replaced by a \begin and \end
695 commands for "MATHREPL" rather than being commented out.
696 [ Default: "MATHENV"="(?:displaymath|equation)" ,
698 "MATHREPL"="displaymath" ]
699 "MATHARRENV","MATHARRREPL"
701 as "MATHENV","MATHREPL" but for equation arrays
702 [ Default: "MATHARRENV"="eqnarray\*?" ,
704 "MATHREPL"="eqnarray" ]
705 "MINWORDSBLOCK"
707 Minimum number of tokens required to form an independent
708 block. This value is used in the algorithm to detect changes
709 of complete blocks by merging identical text parts of less
710 than "MINWORDSBLOCK" to the preceding added and discarded
711 parts.
712 [ Default: 3 ]
714 "PICTUREENV"
716 Within environments whose name matches the regular expression
717 in "PICTUREENV" all latexdiff markup is removed (in
718 pathologic cases this might lead to inconsistent markup but
719 this situation should be rare).
720 [ Default: "(?:picture|DIFnomarkup)[\w\d*@]*" ]
722 "SCALEDELGRAPHICS"
724 If "--graphics-markup=both" is chosen, "SCALEDELGRAPHICS" is
725 the factor, by which deleted figures will be scaled (i.e. 0.5
726 implies they are shown at half linear size).
727 [ Default: 0.5 ]
729 "VERBATIMENV"
731 RegEx describing environments like verbatim, whose contents
732 should be taken verbatim. The content of these environments
733 will not be processed in any way: deleted content is
734 commented out, new content is not marked up
735 [ Default: "comment" ]
737 "VERBATIMLINEENV"
739 RegEx describing environments like verbatim, whose contents
740 should be taken verbatim. The content of environments
741 described by VERBATIMLINEENV are compared in line mode, and
742 changes are marked up using the listings package. The markup
743 style is set based on the chosen mains markup type (Option
744 -t), or on an analysis of the preamble. Note that
745 "listings.sty" must be installed. If this file is not found
746 the fallback solution is to treat VERBATIMLINEENV
747 environments treated exactly the same way as VERBATIMENV
748 environments.
749 [ Default: "(?:verbatim[*]?|lstlisting" ]
751
753 Citations result in overfull boxes
754 There is an incompatibility between the "ulem" package, which
755 "latexdiff" uses for underlining and striking out in the
756 UNDERLINE style, the default style, and the way citations are
757 generated. In order to be able to mark up citations properly,
758 they are enclosed with an "\mbox" command. As mboxes cannot
759 be broken across lines, this procedure frequently results in
760 overfull boxes, possibly obscuring the content as it extends
761 beyond the right margin. The same occurs for some other
762 packages (e.g., siunitx). If this is a problem, you have two
763 possibilities.
764 1. Use "CFONT" type markup (option "-t CFONT"): If this
766 markup is chosen, then changed citations are no longer marked
767 up with the wavy line (additions) or struck out (deletions),
768 but are still highlighted in the appropriate color, and
769 deleted text is shown with a different font. Other styles not
770 using the "ulem" package will also work.
771 2. Choose option "--disable-citation-markup" which turns off
773 the marking up of citations: deleted citations are no longer
774 shown, and added citations are shown without markup. (This
775 was the default behaviour of latexdiff at versions 0.6 and
776 older)
777 For custom packages you can define the commands which need to
779 be protected by "\mbox" with "--append-mboxsafecmd" and
780 "--excludemboxsafecmd" options (submit your lists of command
781 as feature request at github page to set the default
782 behaviour of future versions, see section 6)
783 Changes in complicated mathematical equations result in latex
785 processing errors
786 Try options "--math-markup=whole". If even that fails, you
787 can turn off mark up for equations with "--math-markup=off".
788 How can I just show the pages where changes had been made
790 Use options -"-s ZLABEL" (some postprocessing required) or
791 "-s ONLYCHANGEDPAGE". "latexdiff-vc --ps|--pdf" with
792 "--only-changes" option takes care of the post-processing for
793 you (requires zref package to be installed).
794
796 Option allow-spaces not implemented entirely consistently. It breaks
797 the rules that number and type of white space does not matter, as
798 different numbers of inter-argument spaces are treated as significant.
799 Please submit bug reports using the issue tracker of the github
801 repository page https://github.com/ftilmann/latexdiff.git, or send them
802 to tilmann -- AT -- gfz-potsdam.de. Include the version number of
803 latexdiff (from comments at the top of the source or use --version).
804 If you come across latex files that are error-free and conform to the
805 specifications set out above, and whose differencing still does not
806 result in error-free latex, please send me those files, ideally edited
807 to only contain the offending passage as long as that still reproduces
808 the problem. If your file relies on non-standard class files, you must
809 include those. I will not look at examples where I have trouble to
810 latex the original files.
811
813 latexrevise, latexdiff-vc
814
816 latexdiff does not make use of external commands and thus should run on
817 any platform supporting Perl 5.6 or higher. If files with encodings
818 other than ASCII or UTF-8 are processed, Perl 5.8 or higher is
819 required.
820 The standard version of latexdiff requires installation of the Perl
822 package "Algorithm::Diff" (available from www.cpan.org -
823 http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone
824 version, latexdiff-so, which has this package inlined, is available,
825 too. latexdiff-fast requires the diff command to be present.
826
828 Version 1.3.0 Copyright (C) 2004-2018 Frederik Tilmann
829 This program is free software; you can redistribute it and/or modify it
831 under the terms of the GNU General Public License Version 3
832 Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N.
834 Becker, T. Doerges, K. Huebner, T. Connors, Sebastian Gouezel and many
835 others. Thanks to the many people who sent in bug reports, feature
836 suggestions, and other feedback.
837perl v5.22.1 2020-06-13 LATEXDIFF(1)