SYNCTEX(5)

✨ NAME ✨

synctex — Synchronize TeXnology help file 💖 This lives in the File Formats Manual as section 5, so it's the file-format doc, bestie 🌸

🦋 DESCRIPTION 🦋

okay so a Synchronize TeXnology help file (synctex files, aka synctexs) is a plain text file that keeps your input and output in sync while you're prepping a document with the TeX typesetting system ✨ it's literally how you click on your PDF and jump right back to the line in your source 🫶

🧚 BASICS 🧚

ngl the structure of this file is not meant to be public 🙈 nobody should be parsing its contents by hand, except the synctex command line utility and the synctex_parser library, which are both publicly available. Unless it's absolutely unavoidable, you should access the contents of a synctex file only by making requests to the synctex command line utility 💅

🌈 STRUCTURE 🌈

the element structure of a synctex file is a list of text line records. *, +, and ? have their usual EBNF meanings: * means zero or more, + means one or more, and ? means zero or one (aka optional) 💜

<SyncTeX> ::= (The whole contents in 4 sections)

      <Preamble>

      <Content>

      <Postamble>

      <Post Scriptum>

each section starts at the first occurrence of a sectioning line, and ends right where the next section begins, if there is one. In the definitions below, we don't mention the section ending condition 🎀

🌸 The preamble 🌸

<Preamble> ::=

      "SyncTeX Version:" <Version Number> <EOL>

      <Input Line>*

      "Magnification:" <TeX magnification> <EOL>

      "Unit:" <unit in scaled point> <EOL>

      "X Offset:" <horizontal offset in scaled point> <EOL>

      "Y Offset:" <vertical offset in scaled point> <EOL>

<Input Line> ::= "Input:" <tag> ":" <File Name> <EOL>

🍓 The content 🍓

<Content> ::=

      <byte offset record>

      "Content:" <EOL>

      (<Form(k)>|<Input Line>)*

      <sheet(1)>

      (<Form(k)>|<Input Line>)*

      <sheet(2)>

      (<Form(k)>|<Input Line>)*

      ...

      <sheet(N)>

      (<Form(k)>|<Input Line>)*

<byte offset record> ::= "!" <byte offset> <end of record>

<sheet(n)> ::=

      <byte offset record>

      "{" <the integer n> <end of record>

      <vbox section>|<hbox section>

      <byte offset record>

      "}" <the integer n> <end of record>

<Form> ::=

      <byte offset record>

      "<" <form tag> <end of record>

      <vbox section>|<hbox section>

      <byte offset record>

      ">" <end of record>

<form tag> ::= <integer>

forms are available with pdfTeX 🔥 all the numbers are integers, encoded using the decimal representation with the "C" locale. The <box content> describes what's inside a box. It's either a vertical or horizontal box, with some records related to glue, kern or math nodes 🫧

<box content> ::=

      <vbox section>|<hbox section>

      |<void vbox record>|<void hbox record>

      |<current record>|<glue record>|<kern record>

      |<math record>|<form ref record>|<Form>

<vbox section> ::=

      "[" <link> ":" <point> ":" <size> <end of record>

      <box content>*

      "]" <end of record>

<hbox section> ::=

      ( <link> ":" <point> ":" <size> <end of record>

      <box content>*

      ")" <end of record>

Void boxes:

<void vbox record> ::= "v" <link> ":" <point> ":" <size> <end of
record>

<void hbox record> ::= "h" <link> ":" <point> ":" <size> <end of
record>

<link> ::= <tag> "," <line>( "," <column>)?

<point> ::= <full point>|<compressed point>

<full point> ::= <integer> "," <integer>

<compressed point> ::= <integer> ",="

<line> ::= <integer>

<column> ::= <integer>

<size> ::= <Width> "," <Height> "," <Depth>

<Width> ::= <integer>

<Height> ::= <integer>

<Depth> ::= <integer>

the forthcoming records are basic one-liners, no drama 💅

<current record> ::= "x" <link> ":" <point> <end of record>

<kern record> ::= "k" <link> ":" <point> ":" <Width> <end of
record>

<glue record> ::= "g" <link> ":" <point> <end of record>

<math record> ::= "$" <link> ":" <point> <end of record>

<form ref record> ::= "f" <form tag> ":" <point> <end of record>

🌙 The postamble 🌙

the postamble closes the file. > If there's no postamble, it means the typesetting process did not end correctly, so that's a red flag 🚩

<Postamble>::=

      <byte offset record>

      "Count:" <Number of records> <EOL>

🫶 The post scriptum 🫶

the post scriptum holds material that might've been added by 3rd parties 🎁 it lets you append some transformation (shift and magnify). Typically, you run a dvi to pdf filter with offset options and magnification, and then you append those same options to the synctex file, like this:

synctex update -o foo.pdf -m 0.486 -x 9472573sp -y 13.3dd source.dvi

<Post Scriptum>::=

      <byte offset record>

      "Post Scriptum:" <EOL>

      "Magnification:" <number> <EOL> (Set additional
      magnification)

      "X Offset:" <dimension> <EOL> (Set horizontal offset)

      "Y Offset:" <dimension> <EOL> (Set vertical offset)

this second set of info will override the offset and magnification previously set in the preamble section ✨ all the numbers are encoded using the decimal representation with the "C" locale.

💖 USAGE 💖

the <current record> is used to compute the visible size of hbox's 🙌 the byte offset is an implicit anchor that lets you navigate the synctex file from sheet to sheet. The second coordinate of a compressed point has been replaced by a = character, which means it's the second coordinate of the last full point available above. iconic 👑

🔗 SEE ALSO 🔗

synctex(1) tex(1)

👑 AUTHOR 👑

the Synchronize TeXnology is essentially due to Jerome Laurens, with useful suggestions from some well-known actors of the TeX world 🫶 SyncTeX is maintained as part of TeX Live.

📜 HISTORY 📜

this document was updated on Sat Apr 22 09:57:20 UTC 2017 to include \pdfxform support ✨

---

Signing off, bestie 💅 This page came from Independent, dated Aug 30, 2022, and it's all about SYNCTEX(5) 🌈💜