7

Only today I decided to see the contents of a .synctex file and I saw a lot of lines with packages paths and so on.

But some lines down I could see a lot of numbers, maybe coordinates I suppose.

For example,

Output:pdf
Magnification:1000
Unit:1
X Offset:0
Y Offset:0
Content:
!15728
{1
[192,56:4736286,51753031:28827951,47016745,0
h192,56:4736286,4736286:0,0,0
h192,56:4736286,4736286:0,0,0
[192,56:4736286,4736286:0,0,0
(192,56:4736286,4155173:0,0,0
k192,56:4736286,4155173:-791972
)
]
[192,56:4736286,51753031:28827951,47016745,0
[192,56:5594039,51753031:27970198,47532077,0
[192,56:5594039,5007386:27970198,786432,0
(192,56:5594039,5007386:27970198,0,0
h192,56:5594039,5007386:27970198,0,0
)
]

At the end I found

Input:210:/media/./main.aux
!72
Postamble:
Count:53291
!27
Post scriptum:

So, is it possible to have an idea how it works? What is the meaning of those lines and numbers?

3

First of all: The most important (but unfortunately slightly outdated) reference is the SyncTeX manpage which contains a grammar describing SyncTeX's lines.

Some of the most important concepts will follow. A synctex file consists of a few different parts (each of them is labeled by name: in the synctex file):

  • preamble: This section describes the synctex version, the output format, magnification, units and offsets.
  • content: This is the relevant part. The content section holds forms and sheets (explanation follows). Here you'll find information about the horizontal and vertical boxes as well as glues etc. which are typeset by TeX.
  • postamble: This part holds the count (number of synctex records) as well as a byte offset. The postamble closes the file. From the manpage:

    If there is no postamble, it means that the typesetting process did not end correctly.

  • postscriptum: This section is mostly empty. It is intended for 3rd party material and allows further transformations (shifting, magnification). That might be relevant if you to further DVI to PDF processing which affects the synchronization. Settings provided here will override the values from the preamble.

As preamble, postamble and postscriptum are rarely what you want to inspect, I'll focus on the content.

Let's introduce a few "lines":

  • every line starting with Input:TAG:FILENAME is a change of sources. So afterwards, all references will point to the file name given here. You are missing such a line in your example.
  • every line starting with !NUMBER is a byte offset record, i.e. the byte distance to the beginning of the file.
  • every line with {TAG is the beginning of a sheet (basically a page) which is obviously ended by }. Similarly there is <TAG which starts a form (PDF form, but you'll not see it in a run-of-the-mill document) ended by >.

By TAG synctex refers to a unique identifier for that object. You'll notice that these will be unsigned integers. In your example there is {1 for instance.

You may have as many sheets or forms as you want. Each of them (as well as their end) will be preceded by a byte offset record. A sheet (or form) may contain vboxes and hboxes.

A vbox is started by [LINK:POINT:SIZE and ended by ]. Similarly a hbox is started by (LINK:POINT:SIZE and ended by ). Within these parentheses there will be different box types, e.g. other vboxes/hboxes, void hboxes/vboxes (no content, only size, lines prefixed by hLINK:POINT:SIZE or vLINK:POINT:SIZE), glue, kern, math and form ref records or even complete forms.

This LINK part is quite important because it holds TAG,LINE (and optionally ,COLUMN). The point denotes where the box is (X,Y) and the size WIDTH,HEIGHT,DEPTH. So taking the line

[192,56:4736286,51753031:28827951,47016745,0

from your example we note that this is the start of a vbox without column specification tagged 192 at line 56. It has x value 4736286 and y value 51753031, a width of 28827951, a height of 47016745 and a depth of 0. The numbers appear to be quite large but usually they are given in sp so it's understandable.

As already described you have some other lines in your example which are slightly different:

  • h192,56:5594039,5007386:27970198,0,0 denotes a void hbox, i.e. a horizontal box which has no relevant content to be referred to but blocks output space.
  • k192,56:4736286,4155173:-791972 is a kern record describing LINK:POINT:WIDTH, so this is a kern of width -791972.

There are many more record types one could inspect but please refer to the man page for a general overview. As previously stated, I have come to the conclusion that at some points the man page is not in sync with the real output of the synctex program. But it's a good start nonetheless.

Please note that there is currently only one real synctex library out there, the reference implementation. So if you have any in-depth questions you will have to look at the source code. Please note that the man page states (concerning the file structure):

The structure of this file should not be considered public, in the sense that no one should need to parse its contents, except the synctex command line utility, and the synctex_parser library. Unless it is absolutely not avoidable, access to the contents of the synctex file should only be made through requests made to the synctex command line utility.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.