The [synctex] command.
Introduction
The synctex command lets you manage two-way synchronization between
a LaTeX source file and its PDF output. It establishes the correspondance
between a location in the LaTeX sources (identified by a file name and line
and column numbers) and a location in the PDF output file (identified by a
page index and the coordinates of a point on this page).
The implementation of the synctex command is based on the
SyncTeX utility written by Jérôme Laurens (see
Synchronization for TeX on
Github).
Synopsis
The formal syntax of the [synctex] command is:
| synctex subcommand ?options? |
The possible subcommands are described below. Depending on the
subcommand, some options may be specified.
The [create] subcommand
This subcommand lets you create a new TeX synchronizer. The complete syntax is:
synctex create ?-dir path? file
The file argument is the path of the pdf/dvi/xdv file associated to the
synctex file. By default, the synctex file is expected to be in the
same directory as the pdf file but, if it is not, one can use the -dir option to specify another location.
The command returns a unique token which can be used in the other
subcommands.
The [delete] subcommand
This subcommand lets you delete a TeX synchronizer. The complete syntax is:
synctex delete token
The token argument is the token returned by the [synctex create] command.
After deletion of the synchronizer, the token is no longer valid.
The [info] subcommand
This subcommand lets you get information about the syntex scanner. The
complete syntax is:
synctex info token ?key?
The token argument is the token returned by the [synctex create] command.
If no key argument is specified, the command returns a dictionary containing the following keys:
Otherwise, if the key argument is specified, the command just returns
the corresponding value.
The outfile key designates the pdf file that was declared in the
[synctex create] command. The syncfile key
designates the corresponding synctex file (possibly compressed).
The [list] subcommand
This subcommand gets the list of TeX synchronizers. The complete syntax is:
synctex list
It returns a list of tokens for the currently existing synchronizers.
The [pdftotex] subcommand
This subcommand is used for Pdf to TeX synchronization. The complete syntax is:
synctex pdftotex token page x y
The token argument is the token returned by the [synctex create] command.
Given a zero-based page index and a position on the page (specified by the x and y coordinates in page coordinates with the origin in the
upper left corner), the command returns a three-item list containing the
name of the corresponding LaTeX file, the line number and the column
number.
The [reload] subcommand
This subcommand lets you regenerate the synctex scanner. The complete syntax is:
synctex reload token
The synctex scanner is generated when the [synctex create] is executed and is rebuilt automatically whenever the command detects
that the synctex file on disk has been modified (typically after a new TeX
run).
This command lets you force the reconstruction of the scanner if
necessary.
The [textopdf] subcommand
This subcommand is used for TeX to Pdf synchronization. The complete syntax is:
synctex textopdf token texfile line ?col?
The token argument is the token returned by the [synctex create] command.
Given a LaTeX source file, a line number and an optional column number
(equal to 0 by default), the command returns a three-item list containing
the zero-based page index and the x and y coordinates of a point on
this page. The returned coordinates are in page space coordinate system
with the origin in the upper left corner.
The [valid] subcommand
This subcommand tells whether a token is valid. The complete
syntax is:
synctex valid token
This is useful to check whether token corresponds to a valid
synchronizer. A token becomes invalid as soon as the
[synctex delete] command is executed.
Note about page coordinates
The SyncTex parser makes use of page space coordinates, defined in
a 72 dpi coordinate system with the origin at the upper-left corner of the
current page and the y-axis oriented downwards.
On the contrary, Alpha's PDFView (based on
Apple's PDFKit framework) sets the origin on the lower-left corner and the
y-axis is oriented upwards.
So coordinates obtained with the [synctex textopdf] command must be flipped if you want to pass them to the
[$pdfToken] associated with a PDFView,
and vice-versa. The conversion can be easily accomplished using the
[$pdfToken flip] command.
Examples
Here are a few examples to demonstrate the use of the synctex command.
Open the Tcl Shell (with ⌘Y) and enter the following commands, one by one.
The examples below assume that we have a LaTeX file called
test.tex that was typeset by pdflatex with the --synctex=1
option to produce the files test.pdf and test.synctex.gz.
Create a synctex synchronizer:
set syncTkn [synctex create /full/path/of/test.pdf]
Get information about this synchronizer:
synctex info $syncTkn
Find the position in the PDF file corresponding to line 123 in the LaTeX file
synctex textopdf $syncTkn /full/path/of/test.tex 123
The result of the previous command could be something like
3 316.56 263.11 which means position x=316.56 and
y=263.11 on page 4 (page at index 3). These coordinates are in PDF points with the
origin in the upper left corner of the page.
Now find the line corresponding to some position in the PDF file,
say position (20,30) on the third page (page at index 2):
synctex pdftotex $syncTkn 2 20 30
The result of the previous command could be something like
/full/path/of/test.tex 261 0 which means line 261, column 0 in the
LaTeX file.
When you do not need the synchronizer anymore, delete it like this:
synctex delete $syncTkn
Last updated 2020-07-09 19:37:51