patchDVI: patch Sweave source references into .dvi file

In patchDVI: Package to Patch '.dvi' or '.synctex' Files

Description

This package allows source references in .dvi files to refer to the actual source file, rather than the intermediate .tex file. Dvi previewers such as yap and xdvi can make use of these source references to jump directly to the part of a document corresponding to a particular source line, and the previewer can send messages to editors to jump to the source corresponding to a location in the preview.

Usage

patchDVI(f, newname = f, patchLog = TRUE)
patchSynctex(f, newname=f, uncompress="pdftk %s output %s uncompress",
	     fromDVI = NULL, patchLog = TRUE)

Arguments

f	A character value giving the name of the .dvi or .synctex file to patch
newname	Output will go to this file; by default to overwrite the original
patchLog	Whether to attempt to patch the ‘.log’ file
uncompress	External command to uncompress a compressed PDF file
fromDVI	Name of DVI file in which to find concordance

Details

This function works with Sweave with option concordance=TRUE and some related functions.

Using patchDVI requires a change to the usual Sweave workflow, as follows:

1. Write the source file in .Rnw. Include the

\SweaveOpts{concordance=TRUE}

option to enable the patching.

2. Use Sweave to convert the file to .tex format.

3. Use latex to process the .tex file into a .dvi file or .pdf file.

4. Run patchDVI on the .dvi file or the .synctex file to patch in the Rnw links.

5. Use the previewer on the patched .dvi file or the original .pdf file.

All the information needed for the patching is stored in the .dvi file, so these 5 steps can be run from the command line, there's no need to keep an R session running (though they'll all work from within one session as well). At some distant date in the future maybe the previewers will learn how to read the concordance info, and step 4 will no longer be necessary.

The patchLog option makes use of the new patchLog function.

Value

A string containing a message about what was done.

Note

In a .dvi file, the concordance is stored in a TeX "special" in the following format (as of version 0.5): concordance:<oldname>:<newname>:<firstline> <rle pairs>*. Here <oldname> is the name of the .tex file to replace, <newname> is the name of the .Rnw file to substitute for it, and <firstline> is the line number from the .Rnw file of the first line in the .tex file.

The <rle pairs> are a sequence of pairs (length, value), separated by spaces (no parentheses), with the length indicating the number of repetitions of the value. Using inverse.rle these are converted to a sequence of differences in the line numbers of the concordance.

Since colons are used to delimit the elements, they must not be used in <oldname> or <newname>: names like ‘C:/source.Rnw’ will not work.

For example, a concordance might contain

\Sconcordance{\concordance:optimization.tex:optimization.Rnw:1 2 1 2 4 39 1 1 4 ...}

saying that source references to optimization.tex should be replaced with optimization.Rnw. Line 1 of the .tex file corresponds to line 1 of the .Rnw file. The diffs for successive lines are 1 1 4 4 1 <repeated 39 times> 4 ..., so the corresponding lines in the .Rnw file (including the first) are 1 2 3 7 11 12 13 ....

The same format is used in a stream object in a .pdf file. (Version 2.12.2 and earlier of R used a different format which was actually invalid according to the PDF specification.) This is not always successfully read by the patching code, because some versions of pdflatex compress parts of the file, and patchDVI currently can't read compressed parts of files. We suggest installing the pdftk open source PDF toolkit (available from http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/) to decompress the file; patchSynctex will make use of it if found. The uncompress argument can be modified to call a different uncompress utility. The Latex commands \pdfcompresslevel=0\pdfobjcompresslevel=0 at the start of your document instruct pdflatex not to compress the file, but some Latex packages (e.g. beamer) will override these settings.

If your workflow involves using latex and dvipdfm, then you will need a recent enough version of latex that supports the -synctex=1 option, and then you can specify the name of the ‘.dvi’ file in the fromDVI argument.

This format is subject to change in future R releases.

Author(s)

Duncan Murdoch

References

The yap previewer is part of MikTeX, from www.miktex.org.

See Also

DVIspecials for the function to read .dvi files, SweaveMiktex for a simple script to run Sweave, MikTeX and patchDVI.

Examples

## Not run: 
patchDVI("mypaper.dvi")

## End(Not run)

patchDVI documentation built on May 5, 2020, 3 p.m.