PDF Preview and SyncTeX
Previewing with SyncTeX
RStudio supports previewing PDFs using SyncTeX, which enables high-fidelity synchronization between PDFs and the source files that generated them.
SyncTeX functionality is only available when using Sweave and knitr for producing PDFs, not for formats such as RMarkdown or Quarto.
Using SyncTex you can:
- Click on a line of code within a source file to navigate the PDF viewer to the corresponding location in the PDF.
- Click on a location within a PDF file to open the source editor to the corresponding line of source code.
RStudio includes a built-in PDF viewer that natively supports SyncTeX. On some platforms RStudio also integrates with a native PDF viewer that supports SyncTeX (the default PDF previewing configuration on each platform is described below).
Forward Search (Source to PDF)
When you invoke the Compile PDF command in RStudio and the PDF is displayed, the viewer automatically performs a forward-search so that you see the page that corresponds to the area of the document you were editing.
At any point after compiling you can perform a forward search by doing the following:
- Control-Click (or Command-Click on the Mac) a line of source code
- Press Control-F8 (or Command-F8 on the Mac)
- Click the SyncTeX button on the editing toolbar
The PDF viewer will be navigated to the appropriate location and a visual indicator of the region that was synced to will be displayed.
Inverse Search (PDF to Source)
To view the source code that generated a given region of a PDF, you can either:
- Control-Click (or Command-Click on the Mac) any part of the PDF
- Click the SyncTeX button on the PDF viewer toolbar (this will sync to the top of the currently displayed page)
Note that in most cases an inverse search will automatically re-activate the RStudio source editor, however in some cases (using Evince on Linux or Firefox over the web) you will need to manually re-activate RStudio.
Supported Viewers
RStudio Viewer
RStudio includes a built-in PDF viewer that supports SyncTeX and works on all platforms (including over the web with RStudio Workbench (previously RStudio Server Pro) and RStudio Server Open Source). The RStudio viewer is based on PDF.js (an open-source project by the Mozilla Foundation). More details on PDF.js are provided below.
PDF.js provides very good rendering of PDFs over the web as well on Mac OS X, however has some fidelity issues when running within RStudio desktop on Windows or Linux. As a result RStudio default configuration on those platforms is to integrate with native PDF viewers as described below.
Sumatra (Windows)
On Windows RStudio ships with Sumatra, an open-source viewer that fully supports SyncTeX and is well regarded as a fast, lightweight, high-fidelity PDF reader.
Note that the gesture for inverse search (PDF to Source) in Sumatra differs from the RStudio Viewer. Rather than control-click you should double-click the region of the PDF you wish to sync to.
While Sumatra is the default PDF previewer on Windows, you can also configure RStudio to use it's own internal viewer or the system viewer. Note that if you choose to use the RStudio Viewer you should be aware that rendering of PDFs may not be as high-fidelity as desired. Specifically, mathematical symbols may not render correctly and some typefaces will have artifacts at their baseline.
Evince (Linux)
On Linux systems running Gnome RStudio integrates with Evince (the standard Gnome PDF viewer). Evince is based on the well-tested Poppler PDF rendering library and fully supports SyncTeX. Note that Evince SyncTeX support is only available in Evince 2.91.3 or higher, which means that the following minimum versions of various distributions are required:
- Ubuntu 11.10+
- Debian 7+
- Fedora 15+
Note that when performing a reverse search from Evince back to RStudio, the RStudio window does not activate automatically.
On Linux systems running KDE or older versions of Evince, RStudio will integrate with the system viewer by default (without any support for SyncTeX). You can also choose to use the RStudio internal viewer, however in this case rendering of PDFs may not be as high fidelity as desired. Specifically, plot legends and titles may have some vertical distortion.
System Viewers
On any platform you can also configure RStudio to use the system PDF viewer. Note that in this case SyncTeX forward-search and inverse-search will not be available
Notes on PDF.js
RStudio's built-in PDF viewer is based on the open-source PDF.js project. PDF.js is sponsored by the Mozilla foundation and aims to become the default PDF viewer for future versions of Firefox.
When viewing PDFs in the built-in viewer it is important to understand that PDFs may not render with perfect fidelity (due to PDF.js being a relatively new project). If you see a problem with symbols or typefaces in the viewer, you should be sure to try the PDF in another reader before concluding that the PDF itself doesn't look as you wish it to.
If you do notice rendering problems you can help make PDF.js better by:
- Trying out your PDF in the reference implementation of PDF.js at: http://mozilla.github.com/pdf.js/web/viewer.html.
- Reporting any problems you find on the PDF.js issue tracker.
Comments
0 comments
Article is closed for comments.