summaryrefslogtreecommitdiff
path: root/support/latexdiff/doc/latexdiff-man.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/latexdiff/doc/latexdiff-man.tex
Initial commit
Diffstat (limited to 'support/latexdiff/doc/latexdiff-man.tex')
-rw-r--r--support/latexdiff/doc/latexdiff-man.tex367
1 files changed, 367 insertions, 0 deletions
diff --git a/support/latexdiff/doc/latexdiff-man.tex b/support/latexdiff/doc/latexdiff-man.tex
new file mode 100644
index 0000000000..1059eb25a3
--- /dev/null
+++ b/support/latexdiff/doc/latexdiff-man.tex
@@ -0,0 +1,367 @@
+\documentclass[a4]{article}
+\usepackage{graphicx}
+%\def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}}
+%\def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}}
+\setlength{\parindent}{0pt}
+%\setlength{\textwidth}{6.5in}
+%\setlength{\oddsidemargin}{0.0in}
+\title{Marking up differences between latex files with {\em latexdiff}}
+\author{F.J. Tilmann\thanks{tilmann@gfz-potsdam.de}}
+\date{\today}
+
+\begin{document}
+\maketitle
+
+\section*{Preamble}
+
+{\em latexdiff} is a Perl script, which compares two
+latex files and marks up significant differences between them. Various options are available for visual markup using standard
+latex packages such as {\em color.sty}. Changes not directly affecting visible
+text, for example in formatting commands, are still marked in the
+latex source.
+
+A rudimentary revision facilility is provided by another Perl script,
+{\em latexrevise}, which accepts or rejects all changes. Manual editing
+of the difference file can be used to override this default behaviour
+and accept or reject selected changes only.
+
+There is no explicit support for annotations as these are trivial to implement.
+For example, I include the following command definition in the preamble
+\begin{verbatim}
+\newcommand{\remark}[1]{{ \bf [ \footnotesize #1 ]}}
+\end{verbatim}
+and mark up annotations as follows
+\begin{verbatim}
+... The roadrunner is the fastest running bird \remark{Check this
+again with a zoologist!}. The most famous roadrunner ...
+\end{verbatim}
+Alternatively, instead of a command like \verb#\remark# in the example just given, an
+equivalent annotation environment could be defined.
+{\em latexrevise} can remove such comments or
+environments from the text body.
+
+%It is planned that the revision capabilities of this system will be
+%further expanded, dependent on the amount of feedback received.
+
+On the following pages you find the {\em man} pages for {\em
+ latexdiff} and {\em latexrevise} and a simple example.
+
+\include{latexdiff}
+\setcounter{section}{0}
+
+\include{latexrevise}
+\setcounter{section}{0}
+
+\include{latexdiff-vc}
+\setcounter{section}{0}
+
+\section*{A simple example}
+
+We start with a draft text, \verb|example-draft.tex|, listed here in
+full but also included in the distribution (except that the ``verbatim'' environment had
+to be renamed to ``Verbatim'' for the listing).
+
+{\scriptsize
+\begin{verbatim}
+\documentclass[12pt,a4paper]{article}
+
+\setlength{\topmargin}{-0.2in}
+\setlength{\textheight}{9.5in}
+\setlength{\oddsidemargin}{0.0in}
+
+\setlength{\textwidth}{6.5in}
+
+\title{latexdiff Example - Draft version}
+\author{F Tilmann}
+
+\begin{document}
+\maketitle
+
+\section*{Introduction}
+
+This is an extremely simple document that showcases some of latexdiff features.
+Type
+\begin{Verbatim}
+latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
+\end{Verbatim}
+to create the difference file. You can inspect this file directly. Then run either
+\begin{Verbatim}
+pdflatex example-diff.tex
+xpdf example-diff.pdf
+\end{Verbatim}
+or
+\begin{Verbatim}
+latex example-diff.tex
+dvips -o example-diff.ps example-diff.dvi
+gv example-diff.ps
+\end{Verbatim}
+to display the markup. Of course, instead of \verb|xpdf| you can use
+\verb|okular, evince, acroread| or any other pdf or postscript viewer.
+
+\section*{Another section title}
+
+A paragraph with a line only in the draft document. More things
+could be said were it not for the constraints of time and space.
+
+More things could be said were it not for the constraints of time and space.
+
+And here is a tipo.
+
+Here is a table:
+
+\begin{tabular}{ll}
+Name & Description \\
+\hline
+Gandalf & Grey \\
+Saruman & White
+\end{tabular}
+
+And sometimes a whole paragraph gets completely rewritten. In this
+case latexdiff marks up the whole paragraph even if some words in it
+are identical.
+No change, no markup!
+\end{document}
+\end{verbatim}
+}
+
+We can now edit
+this text as we would do with any other latex file to create
+a new revision of the text, \verb|example-rev.tex|. We should run
+\begin{verbatim}
+latex example-rev.tex
+\end{verbatim}
+and look at the resulting \verb|.dvi| file to make sure that all
+changes are valid. An example revision is listed here:
+
+{\scriptsize
+\begin{verbatim}
+\documentclass[12pt,a4paper]{article}
+
+\setlength{\topmargin}{-0.2in}
+\setlength{\textheight}{9.5in}
+\setlength{\oddsidemargin}{0.0in}
+
+\setlength{\textwidth}{6in}
+
+\title{latexdiff Example - Revised version}
+\author{F Tilmann}
+% Note how in the preamble visual markup is never used (even
+% if some preamble might eventually end up as visible text.)
+
+\begin{document}
+\maketitle
+
+\section*{Introduction}
+
+This is an extremely simple document that showcases some of the latexdiff features.
+Type
+\begin{Verbatim}
+latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
+\end{Verbatim}
+to create the difference file. You can inspect this file directly. Then run either
+\begin{Verbatim}
+pdflatex example-diff.tex
+xpdf example-diff.pdf
+\end{Verbatim}
+or
+\begin{Verbatim}
+latex example-diff.tex
+dvips -o example-diff.ps example-diff.dvi
+gv example-diff.ps
+\end{Verbatim}
+to display the markup.
+
+\section*{Yet another section title}
+
+ More things could be said were it not for the constraints of time and space.
+
+A paragraph with a line only in the revised document.
+More things could be said were it not for the constraints of time and space.
+
+And here is a typo.
+
+Here is a table:
+
+\begin{tabular}{ll}
+Name & Description \\
+\hline
+Gandalf & White \\
+Saruman & Evil
+\end{tabular}
+
+And now for something completely different, with not a paragraph in sight.
+No change,
+no markup!
+\end{document}
+\end{verbatim}
+}
+
+To compare both revisions, type
+\begin{verbatim}
+latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
+\end{verbatim}
+This results in the following difference file (a few newlines have been
+added in this listing for legibility reasosn):
+{\scriptsize
+\begin{verbatim}
+\documentclass[12pt,a4paper]{article}
+
+\setlength{\topmargin}{-0.2in}
+\setlength{\textheight}{9.5in}
+\setlength{\oddsidemargin}{0.0in}
+
+%DIF 7c7
+%DIF < \setlength{\textwidth}{6.5in}
+%DIF -------
+\setlength{\textwidth}{6in} %DIF >
+%DIF -------
+
+%DIF 9c9
+%DIF < \title{latexdiff Example - Draft version}
+%DIF -------
+\title{latexdiff Example - Revised version} %DIF >
+%DIF -------
+\author{F Tilmann}
+% Note how in the preamble visual markup is never used (even %DIF >
+% if some preamble might eventually end up as visible text.) %DIF >
+%DIF PREAMBLE EXTENSION ADDED BY LATEXDIFF
+%DIF UNDERLINE PREAMBLE %DIF PREAMBLE
+\RequirePackage[normalem]{ulem} %DIF PREAMBLE
+\RequirePackage{color} %DIF PREAMBLE
+\providecommand{\DIFadd}[1]{{\color{blue}\uline{#1}}} %DIF PREAMBLE
+\providecommand{\DIFdel}[1]{{\color{red}\sout{#1}}} %DIF PREAMBLE
+%DIF SAFE PREAMBLE %DIF PREAMBLE
+\providecommand{\DIFaddbegin}{} %DIF PREAMBLE
+\providecommand{\DIFaddend}{} %DIF PREAMBLE
+\providecommand{\DIFdelbegin}{} %DIF PREAMBLE
+\providecommand{\DIFdelend}{} %DIF PREAMBLE
+%DIF FLOATSAFE PREAMBLE %DIF PREAMBLE
+\providecommand{\DIFaddFL}[1]{\DIFadd{#1}} %DIF PREAMBLE
+\providecommand{\DIFdelFL}[1]{\DIFdel{#1}} %DIF PREAMBLE
+\providecommand{\DIFaddbeginFL}{} %DIF PREAMBLE
+\providecommand{\DIFaddendFL}{} %DIF PREAMBLE
+\providecommand{\DIFdelbeginFL}{} %DIF PREAMBLE
+\providecommand{\DIFdelendFL}{} %DIF PREAMBLE
+%DIF END PREAMBLE EXTENSION ADDED BY LATEXDIFF
+
+\begin{document}
+\maketitle
+
+\section*{Introduction}
+
+This is an extremely simple document that showcases some of latexdiff features.
+Type
+\begin{Verbatim}
+latexdiff -t UNDERLINE example-draft.tex example-rev.tex > example-diff.tex
+\end{Verbatim}
+to create the difference file. You can inspect this file directly. Then run either
+\begin{Verbatim}
+pdflatex example-diff.tex
+xpdf example-diff.pdf
+\end{Verbatim}
+or
+\begin{Verbatim}
+latex example-diff.tex
+dvips -o example-diff.ps example-diff.dvi
+gv example-diff.ps
+\end{Verbatim}
+to display the markup.
+
+\section*{\DIFaddbegin \DIFadd{Yet another }\DIFaddend \DIFdelbegin
+\DIFdel{Another }\DIFdelend section title}
+
+ \DIFdelbegin \DIFdel{A paragraph with a line only in the draft
+ document. }\DIFdelend More things could
+ be said were it not for the constraints of time and space.
+
+\DIFaddbegin \DIFadd{A paragraph with a line only in the revised
+ document. }\DIFaddend More things could be said
+were it not for the constraints of time and space.
+
+And here is a \DIFaddbegin \DIFadd{typo}\DIFaddend \DIFdelbegin
+\DIFdel{tipo}\DIFdelend .
+
+Here is a table:
+
+\begin{tabular}{ll}
+Name & Description \\
+\hline
+Gandalf & \DIFaddbegin \DIFadd{White }\DIFaddend \DIFdelbegin
+\DIFdel{Grey }\DIFdelend \\
+Saruman & \DIFaddbegin \DIFadd{Evil
+}\DIFaddend \DIFdelbegin \DIFdel{White
+}\DIFdelend \end{tabular}
+
+And \DIFaddbegin \DIFadd{now for something completely different, with not
+ a paragraph in sight}\DIFaddend \DIFdelbegin \DIFdel{sometimes a whole
+ paragraph gets completely rewritten. In this
+case latexdiff marks up the whole paragraph even if some words in it
+are identical}\DIFdelend .
+No change,
+no markup!
+\end{document}
+\end{verbatim}
+}
+Type
+\begin{verbatim}
+pdflatex example-diff.tex
+xpdf example-diff.pdf
+\end{verbatim}
+to make the markup visible. This is what it looks like:
+
+\vspace{1cm}
+\framebox[\textwidth]{\includegraphics[width=\textwidth]{example-diff}}
+\vspace{1cm}
+
+If you approve of all the changes in the revision, just continue with
+\verb|example-rev.tex| for the next revision. If you like to adopt
+most but not all changes you can use \verb|latexrevise| in the
+following manner. Simply edit \verb|example-diff.tex| to remove the \verb|\DIFdelbegin| and
+\verb|\DIFdelend| tags around the text you would like to keep and
+simply remove the text between \verb|\DIFaddbegin| and
+\verb|\DIFaddend| tags, if you do not wish to keep them. Say you are happy with all proposed changes for the
+example above except in
+the last paragraph where you prefer the original draft. You have
+to change
+
+{\scriptsize
+\begin{verbatim}
+...
+And \DIFaddbegin \DIFadd{now for something completely different, with not
+ a paragraph in sight}\DIFaddend \DIFdelbegin \DIFdel{sometimes a whole
+ paragraph gets completely rewritten. In this
+case latexdiff marks up the whole paragraph even if some words in it
+are identical}\DIFdelend .
+...
+\end{verbatim}
+}
+into
+{\scriptsize
+\begin{verbatim}
+...
+And \DIFdel{sometimes a whole
+ paragraph gets completely rewritten. In this
+case latexdiff marks up the whole paragraph even if some words in it
+are identical}.
+...
+\end{verbatim}
+}
+and run
+\begin{verbatim}
+latexrevise -a example-diff.tex > example-final.tex
+\end{verbatim}
+\verb|example-final.tex| is then almost identical to
+\verb|example-rev.tex| except for the last paragraph.
+
+\section*{External tools}
+The following is an incomplete list of wrappers written by others providing some added functionality. These are not included with the distribution but need to be downloaded and installed separately.
+
+\begin{description}
+ \item[latexdiffcite] (Author: Christer van der Meeren) is a wrapper around latexdiff to make citations diff properly. It works by expanding \verb|\cite| type commands using the bbl or bib file, such that citations are treated just like normal text rather than as atomic in the plain latexdiff. \\
+\verb|https://latexdiffcite.readthedocs.org|
+\item[git-latexdiff] (lead author: Matthieu Moy) is a wrapper (bash scipt) around latexdiff that allows using it to diff two revisions of a LaTeX file under git revision control Similar functionality is provided by \verb|latexdiff-vc --git| with \verb|--flatten| option included with this distribution but git-latexdiff allows more fine-grained control on varous aspects. (Not to be confused with latexdiff-git, which is normally installed as a soft link to latexdiff-vc) \\
+\verb|https://gitorious.org/git-latexdiff/|
+
+\end{description}
+
+\end{document}