summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/synctex/README.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/web2c/synctex/README.txt')
-rw-r--r--Build/source/texk/web2c/synctex/README.txt163
1 files changed, 163 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/synctex/README.txt b/Build/source/texk/web2c/synctex/README.txt
new file mode 100644
index 00000000000..a599b6e57fa
--- /dev/null
+++ b/Build/source/texk/web2c/synctex/README.txt
@@ -0,0 +1,163 @@
+# Copyright (c) 2008 jerome DOT laurens AT u-bourgogne DOT fr
+#
+# This file is part of the SyncTeX package.
+#
+# License:
+# --------
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE
+#
+# Except as contained in this notice, the name of the copyright holder
+# shall not be used in advertising or otherwise to promote the sale,
+# use or other dealings in this Software without prior written
+# authorization from the copyright holder.
+#
+
+This file gives the .synctex file specifications.
+
+SyncTeX output file specifications, Version 2, Lun 31 mar 2008 13:50:31 UTC
+===========================================================================
+This is an EBNF file specification extended by ICU regex patterns
+(enclosed between 2 '/'s)
+
+The whole synctex file is made of various records gathered into four different sections:
+
+<synctex file> ::= <preamble> <contents> <postamble> <post scriptum>
+
+Each record is a sequence of text characters following an end of record mark or starting the file,
+and ending with an end of record mark.
+The first characters of a record will determine the type of the record.
+
+<end of record mark> ::= /\n/
+<end of record> ::= /[^\n]*/<end of record mark>
+
+The preamble:
+-------------
+
+<preamble> ::= <control record> <input record>* <informations> <forthcoming records>
+
+<control record> ::= /SyncTeX Version:/<version><end of record mark>
+<SyncTeX> ::=
+<version> ::= /1/
+
+<input record> ::= /Input:/<tag information><end of record mark>
+<tag information> ::= <tag>/:/<file name><end of record mark>
+<tag> ::= <integer>
+<file name> ::= /[^<end of record mark>]*/
+This is used to give a shortcut to filenames.
+
+<informations> ::= <output record>? <magnification record>? <unit record>? <x offset record>? <y offset record>?
+
+<output record> ::= /Output:/<output><end of record mark>
+<output> ::= /dvi|pdf|xdv|[0-9a-zA-Z]*/
+
+<magnification record> ::= /Magnification:/<magnification><end of record>
+<magnification> ::= <integer>
+This is the TeX magnification.
+
+<unit record> ::= /Unit:<unit><end of record>/
+<unit> ::= <integer>
+The SyncTeX unit is <unit> scaled point, 1 in general, 8192 when not given.
+
+<x offset record> ::= /X Offset:/<x offset><end of record>
+<x offset> ::= <integer>
+<y offset record> ::= /Y Offset:/<y offset><end of record>
+<y offset> ::= <integer>
+The offset or the origin of the system of coordinates from the top left point of the page.
+This defaults to 1in for both the vertical and horizontal offsets.
+Both offsets are given in this section in scaled point unit.
+
+<forthcoming records>: The preamble, like any other section may contain in the future any other kind of record,
+except the one starting the next section. In order to ensure some forwards compatibility,
+parsers should anticipate and parse unknown records: an unexpected record should be silently ignored by the parser.
+This means that this format is somehow open an more types of records can be added without breaking existing software.
+
+The preamble ends when a record is found that fits the following section.
+
+The contents:
+-------------
+<contents> ::= <contents record><sheet(1)><i line>*<sheet(2)><i line>*...<sheet(N)><i line>*
+
+<contents record>::=/Contents:/<byte offset><end of record>/
+<offset> ::= <byte offset>
+<sheet(n)> ::= <sheet(n) start><v content>*<sheet end>
+<sheet(n) start> ::= /{/<byte offset>/:/<the integer n><end of record>/
+<sheet end> ::= /}/<byte offset><end of record>
+
+<box content> ::= <vbox section>|<hbox section>|<void vbox record>|<void hbox record>
+<vbox section> ::= (<vbox start record><vbox content>*<vbox stop record>)|<box content>*
+<hbox content> ::= <glue record>|<kern record>|<math record>|<box content>
+<hbox section> ::= <hbox start record><box content>*<hbox stop record>
+
+<void vbox record> ::= /v/<link>/:/<point>/:/<size><end of record>
+<void hbox record> ::= /h/<link>/:/<point>/:/<size><end of record>
+<size> ::= <W>/,/<H>/,/<D>
+<W> ::= <integer>
+<H> ::= <integer>
+<D> ::= <integer>
+<link> ::= <tag>/,/<line>(/,/<column>)?
+<line> ::= <integer>
+<column> ::= <integer>
+
+<current record> ::= /x/<link>/:/<point><end of record>
+<kern record> ::= /k/<link>/:/<point>/:/<W><end of record>
+<glue record> ::= /g/<link>/:/<point><end of record>
+<math record> ::= /$/<link>/:/<point><end of record>
+
+The byte offset is an implicit anchor to navigate the synctex file from sheet to sheet.
+
+The postamble:
+--------------
+The postamble closes the file
+If there is no postamble, it means that the typesetting process did not end correctly.
+<postamble> ::= <postamble record><number of objects record>
+
+<postamble record> ::= /Postamble:/<byte offset><end of record>
+<number of objects record> ::= /Count:/<integer><end of record>
+
+The post scriptum:
+------------------
+The post scriptum contains material possibly added by 3rd parties.
+It allows to append some transformation (shift and magnify).
+Typically, one applies a dvi to pdf filter with offset options and magnification,
+then he appends the same options to the synctex file, for example
+
+ dvipdfmx -m 0.486 -x 9472573sp -y 13.3dd source.dvi
+ echo "X Offset:9472573" >> source.synctex
+ echo "Y Offset:13.3dd" >> source.synctex
+ echo "Magnification:0.486" >> source.synctex
+
+
+<post scriptum> ::= (<magnification line>|<x offset line>|<y offset line>)*
+<magnification line> ::= /Magnification:/<post magnification><end of line mark>
+<post magnification> ::= <unsigned decimal float>
+<x offset line> ::= /X Offset:/<post x offset><end of line mark>
+<post x offset> ::= <sign><unsigned decimal float><offset unit>
+<y offset> ::= <x offset>
+<sign> ::= /(+|-)?/
+<offset unit> ::= /(in|cm|mm|pt|bp|pc|sp|dd|cc|nd|nc)?/
+<end of line mark> ::= /[\n\r]*/
+<y offset line> ::= /Y Offset:/<post y offset><end of line mark>
+<post y offset> ::= <sign><unsigned decimal float><offset unit>
+
+This second information will override the offset and magnification previously available in the preamble section.
+All the numbers are encoded using the decimal representation with "C" locale.
+