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 In some circumstances "Misplaced \noalign" error can occur if there
416 are certain types of changes in tables. In this case please use
417 "--graphics-markup=none" as a work-around.
418 --disable-citation-markup or --disable-auto-mbox
420 Suppress citation markup and markup of other vulnerable commands in
421 styles using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR) (the two
422 options are identical and are simply aliases)
423 --enable-citation-markup or --enforce-auto-mbox
425 Protect citation commands and other vulnerable commands in changed
426 sections with "\mbox" command, i.e. use default behaviour for ulem
427 package for other packages (the two options are identical and are
428 simply aliases)
429 Miscellaneous
431 --verbose or -V
432 Output various status information to stderr during processing.
433 Default is to work silently.
434 --driver=type
436 Choose driver for changebar package (only relevant for styles using
437 changebar: CCHANGEBAR CFONTCHBAR CULINECHBAR CHANGEBAR).
438 Possible drivers are listed in changebar manual, e.g.
439 pdftex,dvips,dvitops
440 [Default: pdftex]
441 --ignore-warnings
443 Suppress warnings about inconsistencies in length between input and
444 parsed strings and missing characters. These warning messages are
445 often related to non-standard latex or latex constructions with a
446 syntax unknown to "latexdiff" but the resulting difference argument
447 is often fully functional anyway, particularly if the non-standard
448 latex only occurs in parts of the text which have not changed.
449 --label=label or -L label
451 Sets the labels used to describe the old and new files. The first
452 use of this option sets the label describing the old file and the
453 second use of the option sets the label for the new file, i.e. set
454 both labels like this "-L labelold -L labelnew". [Default: use the
455 filename and modification dates for the label]
456 --no-label
458 Suppress inclusion of old and new file names as comment in output
459 file
460 --visible-label
462 Include old and new filenames (or labels set with "--label" option)
463 as visible output.
464 --flatten
466 Replace "\input" and "\include" commands within body by the content
467 of the files in their argument. If "\includeonly" is present in
468 the preamble, only those files are expanded into the document.
469 However, no recursion is done, i.e. "\input" and "\include"
470 commands within included sections are not expanded. The included
471 files are assumed to
472 be located in the same directories as the old and new master
473 files, respectively, making it possible to organise files into old
474 and new directories. --flatten is applied recursively, so inputted
475 files can contain further "\input" statements. Also handles files
476 included by the import package ("\import" and "\subimport"), and
477 "\subfile" command.
478 Use of this option might result in prohibitive processing times for
480 larger documents, and the resulting difference document no longer
481 reflects the structure of the input documents.
482 --filter-script=filterscript
484 Run files through this filterscript (full path preferred) before
485 processing. The filterscript must take STDIN input and output to
486 STDOUT. When coupled with --flatten, each file will be run through
487 the filter as it is brought in.
488 --ignore-filter-stderr
490 When running with --filter-script, STDERR from the script may cause
491 readability issues. Turn this flag on to ignore STDERR from the
492 filter script.
493 --help or -h
495 Show help text
496 --version
498 Show version number
499 Internal options
501 These options are mostly for automated use by latexdiff-vc. They can be
502 used directly, but the API should be considered less stable than for
503 the other options.
504 --no-links
506 Suppress generation of hyperreferences, used for minimal diffs
507 (option --only-changes of latexdiff-vc)
508 Predefined styles
510 Major types
511 The major type determine the markup of plain text and some selected
512 latex commands outside floats by defining the markup commands
513 "\DIFadd{...}" and "\DIFdel{...}" .
514 "UNDERLINE"
516 Added text is wavy-underlined and blue, discarded text is
517 struck out and red (Requires color and ulem packages).
518 Overstriking does not work in displayed math equations such
519 that deleted parts of equation are underlined, not struck out
520 (this is a shortcoming inherent to the ulem package).
521 "CTRADITIONAL"
523 Added text is blue and set in sans-serif, and a red footnote
524 is created for each discarded piece of text. (Requires color
525 package)
526 "TRADITIONAL"
528 Like "CTRADITIONAL" but without the use of color.
529 "CFONT" Added text is blue and set in sans-serif, and discarded text
531 is red and very small size.
532 "FONTSTRIKE"
534 Added tex is set in sans-serif, discarded text small and
535 struck out
536 "CCHANGEBAR"
538 Added text is blue, and discarded text is red. Additionally,
539 the changed text is marked with a bar in the margin (Requires
540 color and changebar packages).
541 "CFONTCHBAR"
543 Like "CFONT" but with additional changebars (Requires color
544 and changebar packages).
545 "CULINECHBAR"
547 Like "UNDERLINE" but with additional changebars (Requires
548 color, ulem and changebar packages).
549 "CHANGEBAR"
551 No mark up of text, but mark margins with changebars
552 (Requires changebar package).
553 "INVISIBLE"
555 No visible markup (but generic markup commands will still be
556 inserted.
557 "BOLD" Added text is set in bold face, discarded is not shown.
559 "PDFCOMMENT"
561 The pdfcomment package is used to underline new text, and
562 mark deletions with a PDF comment. Note that this markup
563 might appear differently or not at all based on the pdf
564 viewer used. The viewer with best support for pdf markup is
565 probably acroread. This style is only recommended if the
566 number of differences is small.
567 Subtypes
569 The subtype defines the commands that are inserted at the begin and end
570 of added or discarded blocks, irrespectively of whether these blocks
571 contain text or commands (Defined commands: "\DIFaddbegin, \DIFaddend,
572 \DIFdelbegin, \DIFdelend")
573 "SAFE" No additional markup (Recommended choice)
575 "MARGIN" Mark beginning and end of changed blocks with symbols in the
577 margin nearby (using the standard "\marginpar" command - note
578 that this sometimes moves somewhat from the intended
579 position.
580 "COLOR" An alternative way of marking added passages in blue, and
582 deleted ones in red. (It is recommeneded to use instead the
583 main types to effect colored markup, although in some cases
584 coloring with dvipscol can be more complete, for example with
585 citation commands).
586 "DVIPSCOL"
588 An alternative way of marking added passages in blue, and
589 deleted ones in red. Note that "DVIPSCOL" only works with the
590 dvips converter, e.g. not pdflatex. (it is recommeneded to
591 use instead the main types to effect colored markup, although
592 in some cases coloring with dvipscol can be more complete).
593 "ZLABEL" can be used to highlight only changed pages, but requires
595 post-processing. It is recommend to not call this option
596 manually but use "latexdiff-vc" with "--only-changes" option.
597 Alternatively, use the script given within preamble of diff
598 files made using this style.
599 "ONLYCHANGEDPAGE"
601 also highlights changed pages, without the need for post-
602 processing, but might not work reliably if there is floating
603 material (figures, tables).
604 "LABEL" is similar to "ZLABEL", but does not need the zref package
606 and works less reliably (deprecated).
607 Float Types
609 Some of the markup used in the main text might cause problems when used
610 within floats (e.g. figures or tables). For this reason alternative
611 versions of all markup commands are used within floats. The float type
612 defines these alternative commands.
613 "FLOATSAFE"
615 Use identical markup for text as in the main body, but set
616 all commands marking the begin and end of changed blocks to
617 null-commands. You have to choose this float type if your
618 subtype is "MARGIN" as "\marginpar" does not work properly
619 within floats.
620 "TRADITIONALSAFE"
622 Mark additions the same way as in the main text. Deleted
623 environments are marked by angular brackets \[ and \] and the
624 deleted text is set in scriptscript size. This float type
625 should always be used with the "TRADITIONAL" and
626 "CTRADITIONAL" markup types as the \footnote command does not
627 work properly in floating environments.
628 "IDENTICAL"
630 Make no difference between the main text and floats.
631 Configuration Variables
633 "ARRENV" If a match to "ARRENV" is found within an inline math
634 environment within a deleted or added block, then the inlined
635 math is surrounded by "\mbox{"..."}". This is necessary as
636 underlining does not work within inlined array environments.
637 [ Default: "ARRENV"="(?:array|[pbvBV]matrix)"
639 "COUNTERCMD"
641 If a command in a deleted block which is also in the textcmd
642 list matches "COUNTERCMD" then an additional command
643 "\addtocounter{"cntcmd"}{-1}", where cntcmd is the matching
644 command, is appended in the diff file such that the numbering
645 in the diff file remains synchronized with the numbering in
646 the new file.
647 [ Default: "COUNTERCMD"="(?:footnote|part|section|subsection"
649 ...
650 "|subsubsection|paragraph|subparagraph)" ]
652 "CUSTOMDIFCMD"
654 This option is for advanced users and allows definition of
655 special versions of commands, which do not work as safe
656 commands.
657 Commands in "CUSTOMDIFCMD" that occur in added or deleted
659 blocks will be given an ADD or DEL prefix. The prefixed
660 versions of the command must be defined in the preamble,
661 either by putting them in the preamble of at least the new
662 file, or by creating a custom preamble file (Option
663 --preamble). For example the command "\blindtext" (from
664 package blindtext) does not interact well with underlining,
665 so that for the standard markup type, it is not satisfactory
666 to define it as a safe command. Instead, a customised
667 versions without underlining can be defined in the preamble:
668 "\newcommand{\DELblindtext}{{\color{red}\blindtext}}"
670 "\newcommand{\ADDblindtext}{{\color{blue}\blindtext}}"
672 and then latexdiff should be invoked with the option "-c
674 CUSTOMDIFCMD=blindtext".
675 [ Default: none ]
677 "FLOATENV"
679 Environments whose name matches the regular expression in
680 "FLOATENV" are considered floats. Within these environments,
681 the latexdiff markup commands are replaced by their FL
682 variaties.
683 [ Default: "(?:figure|table|plate)[\w\d*@]*" ]
685 "ITEMCMD" Commands representing new item line with list environments.
687 [ Default: \"item" ]
689 "LISTENV" Environments whose name matches the regular expression in
691 "LISTENV" are list environments.
692 [ Default: "(?:itemize|enumerate|description)" ]
694 "MATHENV","MATHREPL"
696 If both \begin and \end for a math environment (environment
697 name matching "MATHENV" or \[ and \]) are within the same
698 deleted block, they are replaced by a \begin and \end
699 commands for "MATHREPL" rather than being commented out.
700 [ Default: "MATHENV"="(?:displaymath|equation)" ,
702 "MATHREPL"="displaymath" ]
703 "MATHARRENV","MATHARRREPL"
705 as "MATHENV","MATHREPL" but for equation arrays
706 [ Default: "MATHARRENV"="eqnarray\*?" ,
708 "MATHREPL"="eqnarray" ]
709 "MINWORDSBLOCK"
711 Minimum number of tokens required to form an independent
712 block. This value is used in the algorithm to detect changes
713 of complete blocks by merging identical text parts of less
714 than "MINWORDSBLOCK" to the preceding added and discarded
715 parts.
716 [ Default: 3 ]
718 "PICTUREENV"
720 Within environments whose name matches the regular expression
721 in "PICTUREENV" all latexdiff markup is removed (in
722 pathologic cases this might lead to inconsistent markup but
723 this situation should be rare).
724 [ Default: "(?:picture|DIFnomarkup)[\w\d*@]*" ]
726 "SCALEDELGRAPHICS"
728 If "--graphics-markup=both" is chosen, "SCALEDELGRAPHICS" is
729 the factor, by which deleted figures will be scaled (i.e. 0.5
730 implies they are shown at half linear size).
731 [ Default: 0.5 ]
733 "VERBATIMENV"
735 RegEx describing environments like verbatim, whose contents
736 should be taken verbatim. The content of these environments
737 will not be processed in any way: deleted content is
738 commented out, new content is not marked up
739 [ Default: "comment" ]
741 "VERBATIMLINEENV"
743 RegEx describing environments like verbatim, whose contents
744 should be taken verbatim. The content of environments
745 described by VERBATIMLINEENV are compared in line mode, and
746 changes are marked up using the listings package. The markup
747 style is set based on the chosen mains markup type (Option
748 -t), or on an analysis of the preamble. Note that
749 "listings.sty" must be installed. If this file is not found
750 the fallback solution is to treat VERBATIMLINEENV
751 environments treated exactly the same way as VERBATIMENV
752 environments.
753 [ Default: "(?:verbatim[*]?|lstlisting" ]
755
757 Citations result in overfull boxes
758 There is an incompatibility between the "ulem" package, which
759 "latexdiff" uses for underlining and striking out in the
760 UNDERLINE style, the default style, and the way citations are
761 generated. In order to be able to mark up citations properly,
762 they are enclosed with an "\mbox" command. As mboxes cannot
763 be broken across lines, this procedure frequently results in
764 overfull boxes, possibly obscuring the content as it extends
765 beyond the right margin. The same occurs for some other
766 packages (e.g., siunitx). If this is a problem, you have two
767 possibilities.
768 1. Use "CFONT" type markup (option "-t CFONT"): If this
770 markup is chosen, then changed citations are no longer marked
771 up with the wavy line (additions) or struck out (deletions),
772 but are still highlighted in the appropriate color, and
773 deleted text is shown with a different font. Other styles not
774 using the "ulem" package will also work.
775 2. Choose option "--disable-citation-markup" which turns off
777 the marking up of citations: deleted citations are no longer
778 shown, and added citations are shown without markup. (This
779 was the default behaviour of latexdiff at versions 0.6 and
780 older)
781 For custom packages you can define the commands which need to
783 be protected by "\mbox" with "--append-mboxsafecmd" and
784 "--excludemboxsafecmd" options (submit your lists of command
785 as feature request at github page to set the default
786 behaviour of future versions, see section 6)
787 Changes in complicated mathematical equations result in latex
789 processing errors
790 Try options "--math-markup=whole". If even that fails, you
791 can turn off mark up for equations with "--math-markup=off".
792 How can I just show the pages where changes had been made
794 Use options -"-s ZLABEL" (some postprocessing required) or
795 "-s ONLYCHANGEDPAGE". "latexdiff-vc --ps|--pdf" with
796 "--only-changes" option takes care of the post-processing for
797 you (requires zref package to be installed).
798
800 Option allow-spaces not implemented entirely consistently. It breaks
801 the rules that number and type of white space does not matter, as
802 different numbers of inter-argument spaces are treated as significant.
803 Please submit bug reports using the issue tracker of the github
805 repository page https://github.com/ftilmann/latexdiff.git, or send them
806 to tilmann -- AT -- gfz-potsdam.de. Include the version number of
807 latexdiff (from comments at the top of the source or use --version).
808 If you come across latex files that are error-free and conform to the
809 specifications set out above, and whose differencing still does not
810 result in error-free latex, please send me those files, ideally edited
811 to only contain the offending passage as long as that still reproduces
812 the problem. If your file relies on non-standard class files, you must
813 include those. I will not look at examples where I have trouble to
814 latex the original files.
815
817 latexrevise, latexdiff-vc
818
820 latexdiff does not make use of external commands and thus should run on
821 any platform supporting Perl 5.6 or higher. If files with encodings
822 other than ASCII or UTF-8 are processed, Perl 5.8 or higher is
823 required.
824 The standard version of latexdiff requires installation of the Perl
826 package "Algorithm::Diff" (available from www.cpan.org -
827 http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone
828 version, latexdiff-so, which has this package inlined, is available,
829 too. latexdiff-fast requires the diff command to be present.
830
832 Version 1.3.2 Copyright (C) 2004-2021 Frederik Tilmann
833 This program is free software; you can redistribute it and/or modify it
835 under the terms of the GNU General Public License Version 3
836 Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N.
838 Becker, T. Doerges, K. Huebner, T. Connors, Sebastian Gouezel and many
839 others. Thanks to the many people who sent in bug reports, feature
840 suggestions, and other feedback.
841perl v5.30.0 2021-12-27 LATEXDIFF(1)