Here is the patch to embed pdfsync into pdftex

Latest news?

pdfsync.sty has finally reached version 1.0. Now it is available on CTAN

At the end of this summer (2007), pdfsync is slowly migrating to pdftex itself. We are working at giving pdftex all the pdfsync ability and more...

What is pdfsync?

pdfsync is an acronym for synchronization between a pdf file and the TeX or so source file used in the production process. As TeX system is not a WYSIWYG editor, you cannot modify the output directly, instead, you must edit a source file then run the production process. The pdfsync helps you finding what part of the output corresponds to what line of the source file, and conversely what line of the source file corresponds to a location of a given page in the ouput. This feature is achieved with the help of an auxiliary file: foo.pdfsync corresponding to a foo.pdf.

iTeXMac is the first non commercial software to support pdfsync. iTeXMac2, AucTeX, TextMate, TeXniscope, TeXShop, PDFViewer also support pdfsync with various efficiency.

VTeX also has a "synchronization of the editor and the previewer in the PDF mode".

Problems due to pdfsync should be reported.

What is the foo.pdfsync file?

This is a text file that contains information about the foo.pdf file and the source file used to generate it.
It is actually generated by pdflactex, provided you have the pdfsync.sty package and add in the preamble of your file
\usepackage{pdfsync}
This information is used by TeX front ends to allow synchronization from source to output, a la src-special.
This concept is generic and might be used with any kind of text (tex, xml, mp, raw) to pdf processor.

Download pdfsync.sty for LaTeX or Plain users?

The latest version of pdfsync.sty for LaTeX is 1.0, it is available from CTAN since 2007 January 16. For Plain TeX, pdfsync.tex version 0.5 has been posted on 2004, Jan 13, it is available at sourceforge at the bottom of the page there. For ConTeXt, there is a pdfsync module as part of the ConTeXt distribution.

All the necessary instructions to use the pdfsync feature should be given by your TeX front end if it supports it.

What does the foo.pdfsync contain?

Basically, it contains two converse many to many mappings between line numbers in TeX source files and locations in pages of an output pdf file.

What is the foo.pdfsync file format?

General format: text file
Encoding: subset of ASCII
General organization: by line
EOL format: undefined

First line: Name

meaning:	the core name of the pdf output (\jobname in TeX) This is the only encoding dependent part.
type:	a single word, case sensitive
Example:	foo
status:	required

Second line: Version

meaning:	The version number, no yet used
type:	printf("version %u", versionNumber), case insensitive
Example:	Version 0
status:	required

I use C's printf format syntax. For version 1, nothing else is required in the preamble

The rest of the file is an ordered sequence of lines with the following format. All these lines formats are references by the first character. The contents of the examples are the colored characters, sorry for monochrome users.

Version 0 variant

"(" line:

status:	Optional
type:	printf("(%s", inputFileName), case sensitive
meaning:	The source file changes, all subsequent line and column numbers now refer to inputFileName. The path is relative to the directory containing the .pdfsync file. The "tex" extension is not required and can be added if necessary. Path separators are unix "/". The file extension is not required, "tex" is the default
Example:	(Chapter1/MyOtherFoo

")" line:

status:	Optional, but must match a corresponding "(" line
type:	printf(")")
meaning:	The end of the input file has been reached. Subsequent line and column numbers now refer to the calling file.
Example:	)

"l" (ell) line:

status:	Optional
type:	printf("l %u %u %u", recordNumber, lineNumber, columnNumber)
meaning:	recordNumber allows to uniquelly identify the milestone.
Example:	l 464 173

"s" line:

status:	Optional
type:	printf("s %u", sheetNumber)
meaning:	Each time a new page is shipped out. All subsequent locations refer to the page of the pdf output numbered sheetNumber, until next page is shipped out. sheetNumber is a 1 based page number, increasing by one each time.
Example:	s 0

"p" line:

status:	Optional
type:	printf("p %u %u %u", recordNumber, xPosition, yPosition)
meaning:	A location in the current pdf page. It is automatically generated when using pdfsync.sty with pdflatex. TeX unit is used,
Example:	p 464 7149061 19993810

"p*" line:

status:	Optional
type:	printf("p* %u %u %u", recordNumber, xPosition, yPosition), star variant of the "p" line
meaning:	A location in the current pdf page. This information is recorded when the user do wants it. Pdf viewers can display different kind of information for that kind of line (like iTeXMac does)
Example:	p* 474 7149061 19043538

How dos it work?

Sample pdfsync file:

foo
version 0
l 0 13
l 1 19
l 2 24
l 3 33
l 4 35
l 5 13
l 6 17
[...]
l 431 134
l 432 134
[...]
s 1
p 430 2368143 54651247
p 398 21086469 3154577
[...]
p 431 2368143 402063
l 433 134
[...]
l 464 173
[...]
l 527 215
s 2
p 525 2368143 54651247
[...]
p 464 7149061 19993810
p* 474 7149061 19043538
p 475 14470540 19043538
[...]

what corresponds to line 173 of my foo.tex? I can see that the corresponding counter is 464, due to the line l 464 173. For 464, we find a p 464 7149061 19993810 line, after the s 2 one, it corresponds to a point of the second page of foo.pdf with tex coordinates 7149061 19993810, .

We can see that the "l" lines are written in the foo.pdfsync synchronously, which is not the case for "p" lines. We can also observe that sometimes no "p" line correspond to some "l" line, or multiple "p" lines do. Similarly, multiple "l" line can correspond to a unique location in a page. The most important problem is the support for multiple input files, which is not detailled here. However, people will appreciate the difficulties to design and implement the pdfsync feature.

Note to implementors

iTeXMac implementation of pdfsync is mainly gathered in iTMPDFSYNCKit. This is an UTF-8 file.

Credits

The elaboration of this pdfsync concept is the result of a collaboration gathering Piero d'Ancona and J.Laurens.

Document revision

Revision 1, Thu Jan 22 11:32:16 GMT 2004