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 "endfloat"
184 Ensure that "\begin{figure}" and "\end{figure}" always
185 appear by themselves on a line.
186 "hyperref"
188 Change name of "\DIFadd" and "\DIFdel" commands to
189 "\DIFaddtex" and "\DIFdeltex" and define new "\DIFadd" and
190 "\DIFdel" commands, which provide a wrapper for these
191 commands, using them for the text but not for the link
192 defining command (where any markup would cause errors).
193 "apacite", "biblatex"
195 Redefine the commands recognised as citation commands.
196 "siunitx"
198 Treat "\SI" as equivalent to citation commands (i.e.
199 protect with "\mbox" if markup style uses ulem package.
200 "cleveref"
202 Treat "\cref,\Cref", etc as equivalent to citation commands
203 (i.e. protect with "\mbox" if markup style uses ulem
204 package.
205 "glossaries"
207 Define most of the glossaries commands as safe, protecting
208 them with \mbox'es where needed
209 "mhchem"
211 Treat "\ce" as a safe command, i.e. it will be highlighted
212 (note that "\cee" will not be highlighted in equations as
213 this leads to processing errors)
214 "chemformula" or "chemmacros"
216 Treat "\ch" as a safe command outside equations, i.e. it
217 will be highlighted (note that "\ch" will not be
218 highlighted in equations as this leads to processing
219 errors)
220 [ Default: scan the preamble for "\usepackage" commands to
222 determine
223 loaded packages. ]
224 --show-preamble
226 Print generated or included preamble commands to stdout.
227 Configuration
229 --exclude-safecmd=exclude-file or -A exclude-file or
230 --exclude-safecmd="cmd1,cmd2,..."
231 --replace-safecmd=replace-file
232 --append-safecmd=append-file or -a append-file or
233 --append-safecmd="cmd1,cmd2,..."
234 Exclude from, replace or append to the list of regular expressions
235 (RegEx) matching commands which are safe to use within the scope of
236 a "\DIFadd" or "\DIFdel" command. The file must contain one Perl-
237 RegEx per line (Comment lines beginning with # or % are ignored).
238 Note that the RegEx needs to match the whole of the token, i.e.,
239 /^regex$/ is implied and that the initial "\" of the command is not
240 included. The --exclude-safecmd and --append-safecmd options can
241 be combined with the ---replace-safecmd option and can be used
242 repeatedly to add cumulatively to the lists.
243 --exclude-safecmd and --append-safecmd can also take a comma
244 separated list as input. If a comma for one of the regex is
245 required, escape it thus "\,". In most cases it will be necessary
246 to protect the comma-separated list from the shell by putting it in
247 quotation marks.
248 --exclude-textcmd=exclude-file or -X exclude-file or
250 --exclude-textcmd="cmd1,cmd2,..."
251 --replace-textcmd=replace-file
252 --append-textcmd=append-file or -x append-file or
253 --append-textcmd="cmd1,cmd2,..."
254 Exclude from, replace or append to the list of regular expressions
255 matching commands whose last argument is text. See entry for
256 --exclude-safecmd directly above for further details.
257 --replace-context1cmd=replace-file
259 --append-context1cmd=append-file or
260 --append-context1cmd="cmd1,cmd2,..."
261 Replace or append to the list of regex matching commands whose last
262 argument is text but which require a particular context to work,
263 e.g. "\caption" will only work within a figure or table. These
264 commands behave like text commands, except when they occur in a
265 deleted section, when they are disabled, but their argument is
266 shown as deleted text.
267 --replace-context2cmd=replace-file
269 --append-context2cmd=append-file or
270 --append-context2cmd="cmd1,cmd2,..."
271 As corresponding commands for context1. The only difference is
272 that context2 commands are completely disabled in deleted sections,
273 including their arguments.
274 context2 commands are also the only commands in the preamble, whose
276 argument will be processed in word-by-word mode (which only works,
277 if they occur no more than once in the preamble). The algorithm
278 currently cannot cope with repeated context2 commands in the
279 preamble, as they occur e.g. for the "\author" argument in some
280 journal styles (not in the standard styles, though If such a
281 repetition is detected, the whole preamble will be processed in
282 line-by-line mode. In such a case, use "--replace-context2cmd"
283 option to just select the commands, which should be processed and
284 are not used repeatedly in the preamble.
285 --exclude-mboxsafecmd=exclude-file or
287 --exclude-mboxsafecmd="cmd1,cmd2,..."
288 --append-mboxsafecmd=append-file or
289 --append-mboxsafecmd="cmd1,cmd2,..."
290 Define safe commands, which additionally need to be protected by
291 encapsulating in an "\mbox{..}". This is sometimes needed to get
292 around incompatibilities between external packages and the ulem
293 package, which is used for highlighting in the default style
294 UNDERLINE as well as CULINECHBAR CFONTSTRIKE
295 --config var1=val1,var2=val2,... or -c var1=val1,..
297 -c configfile
298 Set configuration variables. The option can be repeated to set
299 different variables (as an alternative to the comma-separated
300 list). Available variables (see below for further explanations):
301 "ARRENV" (RegEx)
303 "COUNTERCMD" (RegEx)
305 "CUSTODIFCMD" (RegEx)
307 "FLOATENV" (RegEx)
309 "ITEMCMD" (RegEx)
311 "LISTENV" (RegEx)
313 "MATHARRENV" (RegEx)
315 "MATHENV" (RegEx)
317 "MATHREPL" (String)
319 "MINWORDSBLOCK" (Integer)
321 "PICTUREENV" (RegEx)
323 "SCALEDELGRAPHICS" (Float)
325 --add-to-config varenv1=pattern1,varenv2=pattern2,...
327 For configuration variables, which are a regular expression
328 (essentially those ending in ENV, COUNTERCMD and CUSTOMDIFCMD, see
329 list above) this option provides an alternative way to modify the
330 configuration variables. Instead of setting the complete pattern,
331 with this option it is possible to add an alternative pattern.
332 "varenv" must be one of the variables listed above that take a
333 regular expression as argument, and pattern is any regular
334 expression (which might need to be protected from the shell by
335 quotation). Several patterns can be added at once by using semi-
336 colons to separate them, e.g. "--add-to-config
337 "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote""
338 --show-safecmd
340 Print list of RegEx matching and excluding safe commands.
341 --show-textcmd
343 Print list of RegEx matching and excluding commands with text
344 argument.
345 --show-config
347 Show values of configuration variables.
348 --show-all
350 Combine all --show commands.
351 NB For all --show commands, no "old.tex" or "new.tex" file needs to
353 be specified, and no differencing takes place.
354 Other configuration options:
356 --allow-spaces
357 Allow spaces between bracketed or braced arguments to commands.
358 Note that this option might have undesirable side effects
359 (unrelated scope might get lumpeded with preceding commands) so
360 should only be used if the default produces erroneous results.
361 (Default requires arguments to directly follow each other without
362 intervening spaces).
363 --math-markup=level
365 Determine granularity of markup in displayed math environments:
366 Possible values for level are (both numerical and text labels are
367 acceptable):
368 "off" or 0: suppress markup for math environments. Deleted
370 equations will not appear in diff file. This mode can be used if
371 all the other modes cause invalid latex code.
372 "whole" or 1: Differencing on the level of whole equations. Even
374 trivial changes to equations cause the whole equation to be marked
375 changed. This mode can be used if processing in coarse or fine
376 mode results in invalid latex code.
377 "coarse" or 2: Detect changes within equations marked up with a
379 coarse granularity; changes in equation type (e.g.displaymath to
380 equation) appear as a change to the complete equation. This mode is
381 recommended for situations where the content and order of some
382 equations are still being changed. [Default]
383 "fine" or 3: Detect small change in equations and mark up at fine
385 granularity. This mode is most suitable, if only minor changes to
386 equations are expected, e.g. correction of typos.
387 --graphics-markup=level
389 Change highlight style for graphics embedded with C<\includegraphics> commands.
390 Possible values for level:
392 "none", "off" or 0: no highlighting for figures
394 "new-only" or 1: surround newly added or changed figures with a
396 blue frame [Default if graphicx package loaded]
397 "both" or 2: highlight new figures with a blue frame and show
399 deleted figures at reduced scale, and crossed out with a red
400 diagonal cross. Use configuration variable SCALEDELGRAPHICS to set
401 size of deleted figures.
402 Note that changes to the optional parameters will make the figure
404 appear as changed to latexdiff, and this figure will thus be
405 highlighted.
406 In some circumstances "Misplaced \noalign" error can occur if there
408 are certain types of changes in tables. In this case please use
409 "--graphics-markup=none" as a work-around.
410 --no-del
412 Suppress deleted text from the diff. It is similar in effect to the
413 BOLD style, but the deleted text ist not just invisible in the
414 output, it is also not included in the diff text file. This can be
415 more robust than just making it invisible.
416 --disable-citation-markup or --disable-auto-mbox
418 Suppress citation markup and markup of other vulnerable commands in
419 styles using ulem (UNDERLINE,FONTSTRIKE, CULINECHBAR) (the two
420 options are identical and are simply aliases)
421 --enable-citation-markup or --enforce-auto-mbox
423 Protect citation commands and other vulnerable commands in changed
424 sections with "\mbox" command, i.e. use default behaviour for ulem
425 package for other packages (the two options are identical and are
426 simply aliases)
427 Miscellaneous
429 --verbose or -V
430 Output various status information to stderr during processing.
431 Default is to work silently.
432 --driver=type
434 Choose driver for changebar package (only relevant for styles using
435 changebar: CCHANGEBAR CFONTCHBAR CULINECHBAR CHANGEBAR).
436 Possible drivers are listed in changebar manual, e.g.
437 pdftex,dvips,dvitops
438 [Default: pdftex]
439 --ignore-warnings
441 Suppress warnings about inconsistencies in length between input and
442 parsed strings and missing characters. These warning messages are
443 often related to non-standard latex or latex constructions with a
444 syntax unknown to "latexdiff" but the resulting difference argument
445 is often fully functional anyway, particularly if the non-standard
446 latex only occurs in parts of the text which have not changed.
447 --label=label or -L label
449 Sets the labels used to describe the old and new files. The first
450 use of this option sets the label describing the old file and the
451 second use of the option sets the label for the new file, i.e. set
452 both labels like this "-L labelold -L labelnew". [Default: use the
453 filename and modification dates for the label]
454 --no-label
456 Suppress inclusion of old and new file names as comment in output
457 file
458 --visible-label
460 Include old and new filenames (or labels set with "--label" option)
461 as visible output.
462 --flatten
464 Replace "\input" and "\include" commands within body by the content
465 of the files in their argument. If "\includeonly" is present in
466 the preamble, only those files are expanded into the document.
467 However, no recursion is done, i.e. "\input" and "\include"
468 commands within included sections are not expanded. The included
469 files are assumed to
470 be located in the same directories as the old and new master
471 files, respectively, making it possible to organise files into old
472 and new directories. --flatten is applied recursively, so inputted
473 files can contain further "\input" statements. Also handles files
474 included by the import package ("\import" and "\subimport"), and
475 "\subfile" command.
476 Use of this option might result in prohibitive processing times for
478 larger documents, and the resulting difference document no longer
479 reflects the structure of the input documents.
480 --filter-script=filterscript
482 Run files through this filterscript (full path preferred) before
483 processing. The filterscript must take STDIN input and output to
484 STDOUT. When coupled with --flatten, each file will be run through
485 the filter as it is brought in.
486 --ignore-filter-stderr
488 When running with --filter-script, STDERR from the script may cause
489 readability issues. Turn this flag on to ignore STDERR from the
490 filter script.
491 --help or -h
493 Show help text
494 --version
496 Show version number
497 Internal options
499 These options are mostly for automated use by latexdiff-vc. They can be
500 used directly, but the API should be considered less stable than for
501 the other options.
502 --no-links
504 Suppress generation of hyperreferences, used for minimal diffs
505 (option --only-changes of latexdiff-vc)
506 Predefined styles
508 Major types
509 The major type determine the markup of plain text and some selected
510 latex commands outside floats by defining the markup commands
511 "\DIFadd{...}" and "\DIFdel{...}" .
512 "UNDERLINE"
514 Added text is wavy-underlined and blue, discarded text is
515 struck out and red (Requires color and ulem packages).
516 Overstriking does not work in displayed math equations such
517 that deleted parts of equation are underlined, not struck out
518 (this is a shortcoming inherent to the ulem package).
519 "CTRADITIONAL"
521 Added text is blue and set in sans-serif, and a red footnote
522 is created for each discarded piece of text. (Requires color
523 package)
524 "TRADITIONAL"
526 Like "CTRADITIONAL" but without the use of color.
527 "CFONT" Added text is blue and set in sans-serif, and discarded text
529 is red and very small size.
530 "FONTSTRIKE"
532 Added tex is set in sans-serif, discarded text small and
533 struck out
534 "CCHANGEBAR"
536 Added text is blue, and discarded text is red. Additionally,
537 the changed text is marked with a bar in the margin (Requires
538 color and changebar packages).
539 "CFONTCHBAR"
541 Like "CFONT" but with additional changebars (Requires color
542 and changebar packages).
543 "CULINECHBAR"
545 Like "UNDERLINE" but with additional changebars (Requires
546 color, ulem and changebar packages).
547 "CHANGEBAR"
549 No mark up of text, but mark margins with changebars
550 (Requires changebar package).
551 "INVISIBLE"
553 No visible markup (but generic markup commands will still be
554 inserted.
555 "BOLD" Added text is set in bold face, discarded is not shown. (also
557 see --no-del option for another possibility to hide deleted
558 text)
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 "MINWORDSBLOCK"
705 Minimum number of tokens required to form an independent
706 block. This value is used in the algorithm to detect changes
707 of complete blocks by merging identical text parts of less
708 than "MINWORDSBLOCK" to the preceding added and discarded
709 parts.
710 [ Default: 3 ]
712 "PICTUREENV"
714 Within environments whose name matches the regular expression
715 in "PICTUREENV" all latexdiff markup is removed (in
716 pathologic cases this might lead to inconsistent markup but
717 this situation should be rare).
718 [ Default: "(?:picture|DIFnomarkup)[\w\d*@]*" ]
720 "SCALEDELGRAPHICS"
722 If "--graphics-markup=both" is chosen, "SCALEDELGRAPHICS" is
723 the factor, by which deleted figures will be scaled (i.e. 0.5
724 implies they are shown at half linear size).
725 [ Default: 0.5 ]
727 "VERBATIMENV"
729 RegEx describing environments like verbatim, whose contents
730 should be taken verbatim. The content of these environments
731 will not be processed in any way: deleted content is
732 commented out, new content is not marked up
733 [ Default: "comment" ]
735 "VERBATIMLINEENV"
737 RegEx describing environments like verbatim, whose contents
738 should be taken verbatim. The content of environments
739 described by VERBATIMLINEENV are compared in line mode, and
740 changes are marked up using the listings package. The markup
741 style is set based on the chosen mains markup type (Option
742 -t), or on an analysis of the preamble. Note that
743 "listings.sty" must be installed. If this file is not found
744 the fallback solution is to treat VERBATIMLINEENV
745 environments treated exactly the same way as VERBATIMENV
746 environments.
747 [ Default: "(?:verbatim[*]?|lstlisting" ]
749
751 Citations result in overfull boxes
752 There is an incompatibility between the "ulem" package, which
753 "latexdiff" uses for underlining and striking out in the
754 UNDERLINE style, the default style, and the way citations are
755 generated. In order to be able to mark up citations properly,
756 they are enclosed with an "\mbox" command. As mboxes cannot
757 be broken across lines, this procedure frequently results in
758 overfull boxes, possibly obscuring the content as it extends
759 beyond the right margin. The same occurs for some other
760 packages (e.g., siunitx). If this is a problem, you have two
761 possibilities.
762 1. Use "CFONT" type markup (option "-t CFONT"): If this
764 markup is chosen, then changed citations are no longer marked
765 up with the wavy line (additions) or struck out (deletions),
766 but are still highlighted in the appropriate color, and
767 deleted text is shown with a different font. Other styles not
768 using the "ulem" package will also work.
769 2. Choose option "--disable-citation-markup" which turns off
771 the marking up of citations: deleted citations are no longer
772 shown, and added citations are shown without markup. (This
773 was the default behaviour of latexdiff at versions 0.6 and
774 older)
775 For custom packages you can define the commands which need to
777 be protected by "\mbox" with "--append-mboxsafecmd" and
778 "--excludemboxsafecmd" options (submit your lists of command
779 as feature request at github page to set the default
780 behaviour of future versions, see section 6)
781 Changes in complicated mathematical equations result in latex
783 processing errors
784 Try options "--math-markup=whole". If even that fails, you
785 can turn off mark up for equations with "--math-markup=off".
786 How can I just show the pages where changes had been made
788 Use options -"-s ZLABEL" (some postprocessing required) or
789 "-s ONLYCHANGEDPAGE". "latexdiff-vc --ps|--pdf" with
790 "--only-changes" option takes care of the post-processing for
791 you (requires zref package to be installed).
792
794 Option allow-spaces not implemented entirely consistently. It breaks
795 the rules that number and type of white space does not matter, as
796 different numbers of inter-argument spaces are treated as significant.
797 Please submit bug reports using the issue tracker of the github
799 repository page https://github.com/ftilmann/latexdiff.git, or send them
800 to tilmann -- AT -- gfz-potsdam.de. Include the version number of
801 latexdiff (from comments at the top of the source or use --version).
802 If you come across latex files that are error-free and conform to the
803 specifications set out above, and whose differencing still does not
804 result in error-free latex, please send me those files, ideally edited
805 to only contain the offending passage as long as that still reproduces
806 the problem. If your file relies on non-standard class files, you must
807 include those. I will not look at examples where I have trouble to
808 latex the original files.
809
811 latexrevise, latexdiff-vc
812
814 latexdiff does not make use of external commands and thus should run on
815 any platform supporting Perl 5.6 or higher. If files with encodings
816 other than ASCII or UTF-8 are processed, Perl 5.8 or higher is
817 required.
818 The standard version of latexdiff requires installation of the Perl
820 package "Algorithm::Diff" (available from www.cpan.org -
821 http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone
822 version, latexdiff-so, which has this package inlined, is available,
823 too. latexdiff-fast requires the diff command to be present.
824
826 Version 1.3.3 Copyright (C) 2004-2022 Frederik Tilmann
827 This program is free software; you can redistribute it and/or modify it
829 under the terms of the GNU General Public License Version 3
830 Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N.
832 Becker, T. Doerges, K. Huebner, T. Connors, Sebastian Gouezel and many
833 others. Thanks to the many people who sent in bug reports, feature
834 suggestions, and other feedback.
835perl v5.30.0 2022-09-25 LATEXDIFF(1)