patchSynctex {patchSynctex}

Create correspondence between .pdf and .Rnw files

Description

patchSynctex(foo) uses the concordance file foo-concordance.tex generated by knitting (possibly Sweaveing) foo.Rnw with the option concordance=TRUE to patch foo.synctex(.gz) with information pointing to foo.Rnw.

Usage

patchSynctex(nwfile, syncfile=NULL, verbose=FALSE, ...)

Arguments

nwfile

name of the file to patch (used sans extension).

syncfile

output sync file (if nwfile is related to an included file).

verbose

if TRUE, emit a message stating the number of patches. Useful for debugging integration in your tools.

...

Unused. Allows any argument forced by your tools to be passed without causing an error.

Details

This function reads the information given in the nwfile-concordance.tex file (which must exist) to patch the nwfile.synctex(.gz) file, which originally contains pointers from nwfile.pdf to the source in nwfile.tex with information pointing to the latter's source in nwfile.Rnw.

Editors and viewers supporting Synctex will be able to use this information to allow forward- and backward search between PDF and ists original source, thus easing debugging.

The nwfile will be used sans extension ; this allows your favorite IDE to pass either the name of the noweb file or the name of the .tex file.

The syncfile argument allows to force the addition of the patched references to the main syncfile for a document that uses subfiles. This is a workaround that may or may not be well-supported by knitr and/or your viewer.

The function may raise errors (files not found), warnings (no patch found to be done) or messages (number of patched locations).

This function is principally intended for use by programmable IDEs able to execute R code. It is documented mostly for debugging purposes.

Value

Nothing useful.

Note

The current (1.8) version of knitr does not yet implement concordance for multifile projects (i. e. children chunks).

Author(s)

Jan Gleixner, Emmanuel Charpentier [e-mail]

References

Duncan Murdoch's excellent patchDVI package: https://cran.r-project.org/package=patchDVI.

Examples

if(requireNamespace("tools", quietly=TRUE) &&
   requireNamespace("knitr", quietly=TRUE)) {
    ## Minimal demonstrative knitr example.
    RnwSrc<-"
\\synctex=1
\\documentclass{article}
<<Setup, eval=TRUE, echo=FALSE, results='hide'>>=
opts_knit$set(concordance=TRUE, self.contained=TRUE)##$
require(patchSynctex)
@ 
\\author{A.~U.~Thor}
\\title{A minimal \\textsf{knitr} example}
\\date{Some time}
\\begin{document}
\\maketitle

A first paragraph of text, which offers a target for forward search\\,:
for example, in \\textsf{emacs} with \\textsf{AUCTeX}, typing
``C-c~C-v'' should bring you to your PDF viewer in the corresponding
typeset line.

<<TestFig, echo=FALSE>>=
curve(sin(x), from=-pi, to=pi, main='A curve generated by R',
      sub='back-searching from here should bring you close to the \\'TestFig\\' chunk.')
@ 

This second paragraph of text is also a convenient target for
back-searching. For example, in \\textsf{evince}, a ``<Ctrl>-click''
should bring you to the \\textsf{noweb} source, bypassing the \\LaTeX
intermediate file.
\\end{document}
"
    require(knitr)
    cat(RnwSrc, file="Minimal.Rnw")
    knit2pdf("Minimal.Rnw", quiet=TRUE)
    D1<-file.info("Minimal.synctex.gz")$mtime
    patchSynctex("Minimal", verbose=TRUE)
    ## should print a message telling the number of patches
    D2<-file.info("Minimal.synctex.gz")$mtime
    D1!=D2
    ## should return TRUE
    ## To see the effect, try (example on a Linux system)
    ## Not run: system("evince Minimal.pdf")
}