[OS X TeX] markup changes/revisions

Peter Dyballa Peter_Dyballa at Web.DE
Wed Mar 1 06:49:41 EST 2006

Am 01.03.2006 um 12:07 schrieb Rechtsanwalt Friedrich Vosberg:

> I just want to run a markup processor in TeXShop.

Parts of what you want could be done with GNU Emacs and file hooks.

Here are two answers from the TeX FAQ (http://www.tex.ac.uk/cgi-bin/
texfaq2html):

*Marking changed parts of your document*

One often needs clear indications of how a document has changed, but
the commonest technique, "change bars" (also known as "revision
bars"), requires surprisingly much trickery of the programmer (the
problem being that TeX 'proper' doesn't provide the programmer with
any information about the "current position" from which a putative
start- or end-point of a bar might be calculated; PDFTeX does provide
the information, but we're not aware yet of any programmer taking
advantage of the fact to write a PDFTeX-based changebar package).

The simplest package that offers change bars is Peter Schmitt's
backgrnd.tex; this was written as a Plain TeX application that
patches the output routine, but it appears to work at least on simple
LaTeX documents. Wise LaTeX users will be alerted by the information
that backgrnd patches their output routine, and will watch its
behaviour very carefully (patching the LaTeX output routine is not
something to undertake lightly...).

The longest-established solution is the changebar package, which
uses \special commands supplied by the driver you're using. You need
therefore to tell the package which driver to generate \specials for
(in the same way that you need to tell the graphics package); the
list of available drivers is pretty restricted, but does include
dvips. The package comes with a shell script chbar.sh (for use on
UNIX machines) that will compare two documents and generate a third
which is marked-up with changebar macros to highlight changes. The
(excellent) shareware WinEDT editor has a macro that will generate
changebar (or other) macros to show differences from an earlier
version of your file, stored in an RCS-controlled repository - see
http://www.winedt.org/Macros/LaTeX/RCSdiff.php

The vertbars package uses the techniques of the lineno package (which
must be present); it's thus the smallest of the packages for change
bar marking, since it leaves all the trickery to another package. The
framed package is another that provides bars as a side-effect of
other desirable functionality: its leftbar environment is simply a
stripped-down frame (note, though, that the environment makes a
separate paragraph of its contents, so it is best used when the
convention is to mark a whole changed paragraph.

Finally, the memoir class allows marginal editorial comments, which
you can obviously use to delimit areas of changed text.

Another way to keep track of changes is employed by some word-
processors - to produce a document that embodies both "old" and "new"
versions. The Perl script latexdiff does this for LaTeX documents;
you feed it the two documents, and it produces a new LaTeX document
in which the changes are very visible. An example of the output is
embedded in the documentation,  latexdiff-man.pdf  (part of the
distribution). A rudimentary revision facility is provided by another
Perl script, latexrevise, which accepts or rejects all changes.
Manual editing of the difference file can be used to accept or reject
selected changes only.
backgrnd.tex
macros/generic/misc/backgrnd.tex
changebar.sty
macros/latex/contrib/changebar (gzipped tar, browse)
framed.sty
macros/latex/contrib/misc/framed.sty
latexdiff, latexrevise
support/latexdiff (gzipped tar, browse)
lineno.sty
macros/latex/contrib/lineno (gzipped tar, browse)
memoir.cls
macros/latex/contrib/memoir (gzipped tar, browse)
vertbars.sty
macros/latex/contrib/misc/vertbars.sty

While LaTeX (or any other TeX-derived package) isn't really like a
compiler, people regularly want to do compiler-like things using it.
Common requirements are conditional 'compilation' and 'block
comments', and several LaTeX-specific means to this end are available.

The simple \newcommand{\gobble}[1]{} and  \iffalse ... \fi aren't
really satisfactory (as a general solution) for comments, since the
matter being skipped is nevertheless scanned by TeX, not always as
you would expect. The scanning imposes restrictions on what you're
allowed to skip; this may not be a problem in today's job, but could
return to bite you tomorrow. For an example of surprises that may
come to bite you, consider the following example (derived from real
user experience):

\iffalse % ignoring this bit
consider what happens if we
use \verb|\iftrue| -- a surprise
\fi

The \iftrue is spotted by TeX as it scans, ignoring the \verb
command; so the \iffalse isn't terminated by the following \fi. Also,
\gobble is pretty inefficient at consuming anything non-trivial,
since all the matter to be skipped is copied to the argument stack
before being ignored.

If your requirement is for a document from which whole chapters (or
the like) are missing, consider the LaTeX \include/\includeonly
system. If you '\include' your files (rather than \input them - see
What's going on in my \include commands?), LaTeX writes macro traces
of what's going on at the end of each chapter to the .aux file; by
using \includeonly, you can give LaTeX an exhaustive list of the
files that are needed. Files that don't get \included are skipped
entirely, but the document processing continues as if they were
there, and page, footnote, and other numbers are not disturbed. Note
that you can choose which sections you want included interactively,

The inverse can be done using the excludeonly package: this allows
you to exclude a (list of) \included files from your document, by
means of an \excludeonly command.

If you want to select particular pages of your document, use Heiko
Oberdiek's pagesel or the selectp packages. You can do something
similar with an existing PDF document (which you may have compiled
using pdflatex in the first place), using the pdfpages package. The
job is then done with a document looking like:

\documentclass{article}
\usepackage[final]{pdfpages}
\begin{document}
\includepdf[pages=30-40]{yoursource.pdf}
\end{document}

(To include all of the document, you write

\includepdf[pages=-]{yoursource.pdf}

omitting the start and end pages in the optional argument.)

If you want flexible facilities for including or excluding small
portions of a file, consider the comment, version or optional packages.

The comment package allows you to declare areas of a document to be
included or excluded; you make these declarations in the preamble of
your file. The command \includecomment{version-name} declares an
environment version-name whose content will be included in your
document, while \excludecomment{version-name} defines an environment
whose content will be excluded from the document. The package uses a
method for exclusion that is pretty robust, and can cope with ill-
formed bunches of text (e.g., with unbalanced braces or \if commands).

These FAQs employ the comment package to alter layout between the
are narrowversion and wideversion for the two versions of the file.

version offers similar facilities to comment.sty (i.e.,
\includeversion and \excludeversion commands); it's far "lighter
weight", but is less robust (and in particular, cannot deal with very
large areas of text being included/excluded).

A significant development of version, confusingly called versions
(i.e., merely a plural of the old package name). Versions adds a
command \markversion{version-name} which defines an environment that
prints the included text, with a clear printed mark around it.

optional defines a command \opt; its first argument is an
'inclusion flag', and its second is text to be included or excluded.
Text to be included or excluded must be well-formed (nothing
mismatched), and should not be too big - if a large body of text is
needed, \input should be used in the argument. The documentation (in
the package file itself) tells you how to declare which sections are
to be included: this can be done in the document preamble, but the
documentation also suggests ways in which it can be done on the
command line that invokes LaTeX, or interactively.

And, not least of this style of conditional compilation, verbatim
(which should be available in any distribution) defines a comment
environment, which enables the dedicated user of the source text
editor to suppress bits of a LaTeX source file. The memoir class
offers the same environment.

An interesting variation is the xcomment package. This defines an
environment whose body is all excluded, apart from environments named
in its argument. So, for example:

\begin{xcomment}{figure,table}
This text is not included
\begin{figure}
This figure is included
\end{figure}
This is not included, either
\begin{table}
This table also included
\end{table}
...
\end{xcomment}

A further valuable twist is offered by the extract package. This
allows you to produce a "partial copy" of an existing document: the
package was developed to permit production of a "book of examples"
from a set of lecture notes. The package documentation shows the
following usage:

\usepackage[
active,
generate=foobar,
extract-env={figure,table},
extract-cmd={chapter,section}
]{extract}

which will cause the package to produce a file foobar.tex
containing all the figure and table environments, and the \chapter
and \section commands, from the document being processed. The new
file foobar.tex is generated in the course of an otherwise ordinary
run on the 'master' document. The package provides a good number of
other facilities, including (numeric or labelled) ranges of
environments to extract, and an extract environment which you can use
to create complete ready-to-run LaTeX documents with stuff you've
extracted.
comment.sty
macros/latex/contrib/comment (gzipped tar, browse)
excludeonly.sty
macros/latex/contrib/misc/excludeonly.sty
extract.sty
macros/latex/contrib/extract (gzipped tar, browse)
memoir.cls
macros/latex/contrib/memoir (gzipped tar, browse)
optional.sty
macros/latex/contrib/misc/optional.sty
pagesel.sty
Distributed with Heiko Oberdiek's packages  macros/latex/contrib/
oberdiek (gzipped tar, browse)
pdfpages.sty
macros/latex/contrib/pdfpages (gzipped tar, browse)
selectp.sty
macros/latex/contrib/misc/selectp.sty
verbatim.sty
Distributed as part of macros/latex/required/tools (gzipped tar, browse)
version.sty
macros/latex/contrib/misc/version.sty
versions.sty
macros/latex/contrib/versions/versions.sty
xcomment.sty
Distributed as part of macros/latex/contrib/seminar (gzipped tar,
browse)

You too could think of packing the different versions of a paragraph
into separate files and only one is included, maybe based on some
'argument' (a \def definition) you pass to tex ...

--
Mit friedvollen Grüßen

Pete

The human animal differs from the lesser primates in his passion for
lists of "Ten Best".
-- H. Allen Smith

------------------------- Info --------------------------
Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
& FAQ: http://latex.yauh.de/faq/
TeX FAQ: http://www.tex.ac.uk/faq
List Archive: http://tug.org/pipermail/macostex-archives/