[OS X TeX] markup changes/revisions

[Peter Dyballa]

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


*Conditional compilation and "comments"*

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,  
using the askinclude package.

  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  
printed (two-column) version and the PDF version for browsing; there  
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.
  askinclude.sty
macros/latex/contrib/misc/askinclude.sty
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/