Debian Codegraph @

texmf-dist/doc/man/man5/synctex.5

raw
1 .Dd Aug 30, 2022
2 .Dt SYNCTEX 5
3 .Os "Independent"
4 .\"
5 .\"
6 .Sh NAME
7 .Nm synctex
8 .Nd Synchronize TeXnology help file
9 .\"
10 .\"
11 .Sh DESCRIPTION
12 Synchronize TeXnology help file
13 .Pq synctexs
14 are text files that help input/output synchronization during document preparation with the TeX typesetting system.
15 .Sh BASICS
16 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 which are both publicly available. 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.
17 .\"
18 .Sh STRUCTURE
19 The element structure of a synctex file is a list of text line records as follows.
20 .Sq \&* ,
21 .Sq \&+ ,
22 and
23 .Sq \&?
24 have their usual EBNF meanings:
25 .Sq \&*
26 means zero or more,
27 .Sq \&+
28 means one or more, and
29 .Sq \&?
30 means zero or one
31 .Pq i.e., optional .
32 .Pp
33 .Bl -item -offset indent
34 .\"
35 .It
36 .Li <SyncTeX> ::=
37 .Pq The whole contents in 4 sections
38 .Bl -item -offset indent
39 .It
40 .Li <Preamble>
41 .It
42 .Li <Content>
43 .It
44 .Li <Postamble>
45 .It
46 .Li <Post Scriptum>
47 .El
48 .\"
49 .El
50 .Pp
51 Each section starts with the first occurrence of a sectioning line, and ends with the next section, if any.
52 In the following definitions, we do not mention the section ending condition.
53 .Sh The preamble
54 .Bl -item -offset indent
55 .\"
56 .It
57 .Li <Preamble> ::=
58 .Bl -item -offset indent
59 .It
60 .Qq SyncTeX Version:
61 <Version Number> <EOL>
62 .It
63 .Li <Input Line>*
64 .It
65 .Qq Magnification:
66 <TeX magnification> <EOL>
67 .It
68 .Qq Unit:
69 <unit in scaled point> <EOL>
70 .It
71 .Qq X Offset:
72 <horizontal offset in scaled point> <EOL>
73 .It
74 .Qq Y Offset:
75 <vertical offset in scaled point> <EOL>
76 .El
77 .It
78 .Li <Input Line> ::=
79 .Qq Input:
80 <tag>
81 .Qq \&:
82 <File Name> <EOL>
83 .\"
84 .El
85 .Sh The content
86 .Bl -item -offset indent
87 .It
88 .Li <Content> ::=
89 .Bl -item -offset indent
90 .It
91 .Li <byte offset record>
92 .It
93 .Qq Content:
94 <EOL>
95 .It
96 .Li (<Form(k)>|<Input Line>)*
97 .It
98 .Li <sheet(1)>
99 .It
100 .Li (<Form(k)>|<Input Line>)*
101 .It
102 .Li <sheet(2)>
103 .It
104 .Li (<Form(k)>|<Input Line>)*
105 .It
106 .Li ...
107 .It
108 .Li <sheet(N)>
109 .It
110 .Li (<Form(k)>|<Input Line>)*
111 .El
112 .It
113 .Li <byte offset record> ::=
114 .Qq \&!
115 <byte offset> <end of record>
116 .Pp
117 .El
118 .Pp
119 .Bl -item -offset indent
120 .It
121 .Li <sheet(n)> ::=
122 .Bl -item -offset indent
123 .It
124 .Li <byte offset record>
125 .It
126 .Qq \&{
127 <the integer n> <end of record>
128 .It
129 .Li <vbox section>|<hbox section>
130 .It
131 .Li <byte offset record>
132 .It
133 .Qq \&}
134 <the integer n> <end of record>
135 .El
136 .It
137 .Li <Form> ::=
138 .Bl -item -offset indent
139 .It
140 .Li <byte offset record>
141 .It
142 .Qq \&<
143 <form tag> <end of record>
144 .It
145 .Li <vbox section>|<hbox section>
146 .It
147 .Li <byte offset record>
148 .It
149 .Qq \&>
150 <end of record>
151 .El
152 .It
153 .Li <form tag> ::= <integer>
154 .El
155 .Pp
156 Forms are available with pdfTeX.
157 All the numbers are integers encoded using the decimal representation with "C" locale.
158 The <box content> describes what is inside a box.
159 It is either a vertical or horizontal box,
160 with some records related to glue, kern or math nodes.
161 .Bl -item -offset indent
162 .It
163 .Li <box content> ::=
164 .Bl -item -offset indent
165 .It
166 .Li <vbox section>|<hbox section>
167 .It
168 .Li |<void vbox record>|<void hbox record>
169 .It
170 .Li |<current record>|<glue record>|<kern record>
171 .It
172 .Li |<math record>|<form ref record>|<Form>
173 .El
174 .It
175 .Li <vbox section> ::=
176 .Bl -item -offset indent
177 .It
178 .Qq \&[
179 <link>
180 .Qq \&:
181 <point>
182 .Qq \&:
183 <size> <end of record>
184 .It
185 .Li <box content>*
186 .It
187 .Qq \&]
188 <end of record>
189 .El
190 .It
191 .Li <hbox section> ::=
192 .Bl -item -offset indent
193 .It
194 .Li \&(
195 <link>
196 .Qq \&:
197 <point>
198 .Qq \&:
199 <size> <end of record>
200 .It
201 .Li <box content>*
202 .It
203 .Qq \&)
204 <end of record>
205 .El
206 .El
207 .Pp
208 Void boxes:
209 .Bl -item -offset indent
210 .It
211 .Li <void vbox record> ::=
212 .Qq v
213 <link>
214 .Qq \&:
215 <point>
216 .Qq \&:
217 <size> <end of record>
218 .It
219 .Li <void hbox record> ::=
220 .Qq h
221 <link>
222 .Qq \&:
223 <point>
224 .Qq \&:
225 <size> <end of record>
226 .It
227 .Li <link> ::= <tag>
228 .Qq \&,
229 <line>(
230 .Qq \&,
231 <column>)?
232 .It
233 .Li <point> ::= <full point>|<compressed point>
234 .It
235 .Li <full point> ::=
236 <integer>
237 .Qq \&,
238 <integer>
239 .It
240 .Li <compressed point> ::=
241 <integer>
242 .Qq \&,=
243 .It
244 .Li <line> ::= <integer>
245 .It
246 .Li <column> ::= <integer>
247 .It
248 .Li <size> ::= <Width>
249 .Qq \&,
250 <Height>
251 .Qq \&,
252 <Depth>
253 .It
254 .Li <Width> ::= <integer>
255 .It
256 .Li <Height> ::= <integer>
257 .It
258 .Li <Depth> ::= <integer>
259 .El
260 .Pp
261 The forthcoming records are basic one liners.
262 .Bl -item -offset indent
263 .It
264 .Li <current record> ::=
265 .Qq x
266 <link>
267 .Qq \&:
268 <point> <end of record>
269 .It
270 .Li <kern record> ::=
271 .Qq k
272 <link>
273 .Qq \&:
274 <point>
275 .Qq \&:
276 <Width> <end of record>
277 .It
278 .Li <glue record> ::=
279 .Qq g
280 <link>
281 .Qq \&:
282 <point> <end of record>
283 .It
284 .Li <math record> ::=
285 .Qq $
286 <link>
287 .Qq \&:
288 <point> <end of record>
289 .It
290 .Li <form ref record> ::=
291 .Qq f
292 <form tag>
293 .Qq \&:
294 <point> <end of record>
295 .El
296 .Pp
297 .\" .Sx underline, .Dq double quotes, .Pq enclosed in parenthesis
298 .Sh The postamble
299 The postamble closes the file
300 If there is no postamble, it means that the typesetting process did not end correctly.
301 .Bl -item -offset indent
302 .\"
303 .It
304 .Li <Postamble>::=
305 .Bl -item -offset indent
306 .It
307 .Li <byte offset record>
308 .It
309 .Qq Count:
310 <Number of records> <EOL>
311 .El
312 .El
313 .Sh The post scriptum
314 The post scriptum contains material possibly added by 3rd parties.
315 It allows one to append some transformation (shift and magnify).
316 Typically, one applies a dvi to pdf filter with offset options and magnification,
317 then he appends the same options to the synctex file, for example
318 .Bd -literal -offset indent
319 synctex update -o foo.pdf -m 0.486 -x 9472573sp -y 13.3dd source.dvi
320 .Ed
321 .Bl -item -offset indent
322 .\"
323 .It
324 .Li <Post Scriptum>::=
325 .\"
326 .Bl -item -offset indent
327 .It
328 .Li <byte offset record>
329 .It
330 .Qq Post Scriptum:
331 <EOL>
332 .It
333 .Qq Magnification:
334 <number> <EOL>
335 .Pq Set additional magnification
336 .It
337 .Qq X Offset:
338 <dimension> <EOL>
339 .Pq Set horizontal offset
340 .It
341 .Qq Y Offset:
342 <dimension> <EOL>
343 .Pq Set vertical offset
344 .El
345 .El
346 This second information will override the offset and magnification previously available in the preamble section.
347 All the numbers are encoded using the decimal representation with "C" locale.
348 .Sh USAGE
349 .Pp
350 The <current record> is used to compute the visible size of hbox's.
351 The byte offset is an implicit anchor to navigate the synctex file from sheet to sheet. The second coordinate of
352 a compressed point has been replaced by a
353 .Qq =
354 character which means that it is the second coordinate of the
355 last full point available above.
356 .Sh SEE ALSO
357 .\" List links in ascending order by section, alphabetically within a section.
358 .\" Please do not reference files that do not exist without filing a bug report
359 .Xr synctex 1
360 .Xr tex 1
361 .Sh AUTHOR
362 The Synchronize TeXnology is essentially due to Jerome Laurens,
363 with useful suggestions by some well known actors of the TeX world.
364 .\" .Sh BUGS \" Document known, unremedied bugs
365 SyncTeX is maintained as part of TeX Live.
366 .Sh HISTORY \" Document history if command behaves in a unique manner
367 This document has been updated on Sat Apr 22 09:57:20 UTC 2017 to include \\pdfxform support.
368 .\" nroff -man synctex.5 | less
369 .\"groff -man -Tascii synctex.5 | less
370 .\"To convert a man page to plain pre-formatted text (e.g. for spell checking) use:
371 .\"nroff -man synctex.5 | col -b > synctex.5.txt
372 .\"To convert it to PostScript (for printing or further conversion to pdf) use:
373 .\"groff -man -Tps synctex.5 > synctex.5.ps
374 .\"To convert the man page to html use:
375 .\"man2html synctex.5