Difference between revisions of "SyncTeX"

From Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
'''SyncTeX''' is a program that puts a lot of anchors in the output file that link to the corresponding position in the source file. This allows you to quickly jump from PDF to source.  
 
'''SyncTeX''' is a program that puts a lot of anchors in the output file that link to the corresponding position in the source file. This allows you to quickly jump from PDF to source.  
  
== MkIV ==
+
== Usage ==
  
In MkIV you can run
+
You can use the <code>--synctex</code> switch to enable SyncTeX.
context --synctex jobname
 
to use SyncTeX
 
  
== MkII ==
+
So in MkIV you can run
With a ConTeXt version > 2009.06.13 you can run
+
  context --synctex <i>jobname</i>
  texexec --synctex jobname
+
and in MkII you can use
that will create a file <code>jobname.synctex.gz</code>.
+
  texexec --synctex <i>jobname</i>
The command
 
  ctxtools --purge --all
 
or next run without --synctex will remove the file again.
 
  
This file can be used by your editor to display the proper file.
+
Alternatively you can add one of the following commands to your MkIV document:
 +
<texcode>
 +
\setupsynctex[state=start,method=min] % clickable words
 +
\setupsynctex[state=start,method=max] % more efficient clickable ranges
 +
</texcode>
 +
 
 +
This will create a file <code><i>jobname</i>.synctex</code>. The command
 +
context --purge
 +
or next run without <code>--synctex</code> will remove the file again.
 +
 
 +
To see what became clickable, use one of
 +
<texcode>
 +
\enabletrackers[system.synctex.visualize]
 +
\enabletrackers[system.synctex.visualize=real]
 +
</texcode>
 +
 
 +
This file can be used by your editor and PDF viewer to jump back and forth between the source and the PDF.
  
 
== Editors & Viewers ==
 
== Editors & Viewers ==
 +
 +
=== TeXshop ===
 +
 +
Works quite well, but needs “magic lines” like:
 +
 +
    % !TEX TS-program = ConTeXt2021
 +
    % !TEX useAlternatePath
 +
    % !TEX useConTeXtSyncParser
 +
 +
Setup see [[TeXShop|extra page on TeXshop]].
  
 
=== TeXWorks ===
 
=== TeXWorks ===
Line 23: Line 44:
 
You may need to modify the command for executing ConTeXt first (you need to add <code>--synctex</code> switch in preferences).
 
You may need to modify the command for executing ConTeXt first (you need to add <code>--synctex</code> switch in preferences).
  
=== Evince ===
+
=== Emacs + auctex ===
Evince (the GNOME PDF viewer) supports SyncTeX since version 2.32.0.
+
 
 +
To implement forward search with auctex (i.e., open the viewer at the right page from emacs)
 +
creating a shell script called '''synctex''' in some directory which precedes one containing
 +
the "usual" synctex (if any) in your $PATH with the following contents has been demonstrated
 +
to work on at least Slackware64 15.0:
 +
 
 +
#! /bin/zsh
 +
 +
# synctex replacement to allow forward search from emacs+auctex to (at least) evince
 +
 +
# Emacs + auctex calls synctex up to three times.
 +
# For example, attempting to view the PDF of <FILE>.tex would cause
 +
# emacs to run the following commands ($PWD is the path to the
 +
# current directory):
 +
#    synctex view -i <LINE>:<COL>:$PWD/./<FILE>.tex -o <FILE>.pdf
 +
#    synctex view -i <LINE>:<COL>:<FILE>.tex -o <FILE>.pdf
 +
#    synctex view -i <LINE>:<COL>:$PWD/<FILE>.tex -o <FILE>.pdf
 +
 +
line_number=${3%%:*}
 +
tex_file=${3##*:}
 +
synctex_file=${tex_file%.tex}.synctex
 +
 +
# Transmogrify the output format of mtxrun into something that emacs+auctex
 +
# (and maybe other editors?) recognizes:
 +
mtxrun --script synctex --find \
 +
    --file=$tex_file --line=$line_number $synctex_file \
 +
    | sed 's/.*page=/Page:/'
 +
 
 +
(Note: this has only been tested with simple document structures.)
 +
 
 +
=== Evince, Okular & Kile ===
 +
Okular (the KDE PDF viewer) and Evince (the GNOME one) support SyncTeX. (The latter since version 2.32.0)
 +
 
 +
To forward something from a text editor to Okular, do
 +
okular --unique '${pdffile}#src:${linenumber} ${texfile}'
 +
 
 +
Kile’s (the KDE TeX IDE) ForwardPDF function should support SyncTeX, but it doesn’t seem to work with ConTeXt at the time of writing
  
 
=== Skim.app & TextMate (Mac OS X) ===
 
=== Skim.app & TextMate (Mac OS X) ===
Line 48: Line 105:
 
Hopefully this functionality will become part of the official ConTeXt bundle one day. (The recipe given above is too specific. The code needs to be written to handle more different viewers and different locations, not only a single viewer at a specified location.)
 
Hopefully this functionality will become part of the official ConTeXt bundle one day. (The recipe given above is too specific. The code needs to be written to handle more different viewers and different locations, not only a single viewer at a specified location.)
  
{{Installation navbox}}
+
=== Bugs ===
 +
 
 +
(In 2021-10 I didn’t manage to get ConTeXt-SyncTeX working with Skim and different editors, while it worked with LaTeX-SyncTeX; there’s also no error message. I guess the parser fails on ConTeXt’s synctex files. [[User:Hraban|Hraban]] ([[User talk:Hraban|talk]]))
 +
 
 +
 
  
 
[[Category:Text Editors]]
 
[[Category:Text Editors]]

Latest revision as of 01:26, 17 November 2023

SyncTeX is a program that puts a lot of anchors in the output file that link to the corresponding position in the source file. This allows you to quickly jump from PDF to source.

Usage

You can use the --synctex switch to enable SyncTeX.

So in MkIV you can run

context --synctex jobname

and in MkII you can use

texexec --synctex jobname

Alternatively you can add one of the following commands to your MkIV document:

\setupsynctex[state=start,method=min] % clickable words
\setupsynctex[state=start,method=max] % more efficient clickable ranges

This will create a file jobname.synctex. The command

context --purge

or next run without --synctex will remove the file again.

To see what became clickable, use one of

\enabletrackers[system.synctex.visualize]
\enabletrackers[system.synctex.visualize=real]

This file can be used by your editor and PDF viewer to jump back and forth between the source and the PDF.

Editors & Viewers

TeXshop

Works quite well, but needs “magic lines” like:

   % !TEX TS-program = ConTeXt2021
   % !TEX useAlternatePath
   % !TEX useConTeXtSyncParser

Setup see extra page on TeXshop.

TeXWorks

You may need to modify the command for executing ConTeXt first (you need to add --synctex switch in preferences).

Emacs + auctex

To implement forward search with auctex (i.e., open the viewer at the right page from emacs) creating a shell script called synctex in some directory which precedes one containing the "usual" synctex (if any) in your $PATH with the following contents has been demonstrated to work on at least Slackware64 15.0:

#! /bin/zsh

# synctex replacement to allow forward search from emacs+auctex to (at least) evince

# Emacs + auctex calls synctex up to three times.
# For example, attempting to view the PDF of <FILE>.tex would cause
# emacs to run the following commands ($PWD is the path to the
# current directory):
#    synctex view -i <LINE>:<COL>:$PWD/./<FILE>.tex -o <FILE>.pdf
#    synctex view -i <LINE>:<COL>:<FILE>.tex -o <FILE>.pdf
#    synctex view -i <LINE>:<COL>:$PWD/<FILE>.tex -o <FILE>.pdf

line_number=${3%%:*}
tex_file=${3##*:}
synctex_file=${tex_file%.tex}.synctex

# Transmogrify the output format of mtxrun into something that emacs+auctex
# (and maybe other editors?) recognizes:
mtxrun --script synctex --find \
    --file=$tex_file --line=$line_number $synctex_file \
    | sed 's/.*page=/Page:/'

(Note: this has only been tested with simple document structures.)

Evince, Okular & Kile

Okular (the KDE PDF viewer) and Evince (the GNOME one) support SyncTeX. (The latter since version 2.32.0)

To forward something from a text editor to Okular, do

okular --unique '${pdffile}#src:${linenumber} ${texfile}'

Kile’s (the KDE TeX IDE) ForwardPDF function should support SyncTeX, but it doesn’t seem to work with ConTeXt at the time of writing

Skim.app & TextMate (Mac OS X)

In Skim/Preferences/Sync choose TextMate. The key combination

Shift + Apple + MouseClick

will bring you to the corresponding line in text editor.

In TextMate I have created my own command inside the ConTeXt bundle:

  • Save: Nothing
  • Command(s)
#!/bin/bash
pdf=${TM_FILEPATH%tex}pdf
/Applications/Skim.app/Contents/SharedSupport/displayline -r "$TM_LINE_NUMBER" "${pdf}"
  • Input: None
  • Output: Discard
  • Activation: Key Equivalent (choose one; I used Ctrl+Alt+Apple+O)
  • Scope Selector: text.tex.context

If you use Apple+R for typesetting that needs to be modified as well (to account for --synctex switch).

Hopefully this functionality will become part of the official ConTeXt bundle one day. (The recipe given above is too specific. The code needs to be written to handle more different viewers and different locations, not only a single viewer at a specified location.)

Bugs

(In 2021-10 I didn’t manage to get ConTeXt-SyncTeX working with Skim and different editors, while it worked with LaTeX-SyncTeX; there’s also no error message. I guess the parser fails on ConTeXt’s synctex files. Hraban (talk))