source/texk/web2c/synctexdir/README.txt

   1 # Copyright (c) 2008, 2009, 2010, 2011 jerome DOT laurens AT u-bourgogne DOT fr
   2 #
   3 # This file is part of the SyncTeX package.
   4 #
   5 # License:
   6 # --------
   7 # Permission is hereby granted, free of charge, to any person
   8 # obtaining a copy of this software and associated documentation
   9 # files (the "Software"), to deal in the Software without
  10 # restriction, including without limitation the rights to use,
  11 # copy, modify, merge, publish, distribute, sublicense, and/or sell
  12 # copies of the Software, and to permit persons to whom the
  13 # Software is furnished to do so, subject to the following
  14 # conditions:
  15 #
  16 # The above copyright notice and this permission notice shall be
  17 # included in all copies or substantial portions of the Software.
  18 #
  19 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  20 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  21 # OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  22 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  23 # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  24 # WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  25 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  26 # OTHER DEALINGS IN THE SOFTWARE
  27 #
  28 # Except as contained in this notice, the name of the copyright holder
  29 # shall not be used in advertising or otherwise to promote the sale,
  30 # use or other dealings in this Software without prior written
  31 # authorization from the copyright holder.
  32 #
  33 # Acknowledgments:
  34 # ----------------
  35 # The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh,
  36 # and significant help from XeTeX developer Jonathan Kew
  37 #
  38 # Nota Bene:
  39 # ----------
  40 # If you include or use a significant part of the synctex package into a software,
  41 # I would appreciate to be listed as contributor and see "SyncTeX" highlighted.
  42 #
  43 # Version 1
  44 # Thu Jun 19 09:39:21 UTC 2008
  45
  46
  47 This file gives the .synctex file specifications.
  48
  49 SyncTeX output file specifications, Version 2, Lun 31 mar 2008 13:50:31 UTC
  50 ===========================================================================
  51 This is an EBNF file specification extended by ICU regex patterns
  52 (enclosed between 2 '/'s)
  53
  54 The whole synctex file is made of various records gathered into four different sections:
  55
  56 <synctex file> ::= <preamble> <contents> <postamble> <post scriptum>
  57
  58 Each record is a sequence of text characters following an end of record mark or starting the file,
  59 and ending with an end of record mark.
  60 The first characters of a record will determine the type of the record.
  61
  62 <end of record mark> ::= /\n/
  63 <end of record> ::= /[^\n]*/<end of record mark>
  64
  65 The preamble:
  66 -------------
  67
  68 <preamble> ::= <control record> <input record>* <informations> <forthcoming records>
  69
  70 <control record> ::= /SyncTeX Version:/<version><end of record mark>
  71 <SyncTeX> ::=
  72 <version> ::= /1/
  73
  74 <input record> ::= /Input:/<tag information><end of record mark>
  75 <tag information> ::= <tag>/:/<file name><end of record mark>
  76 <tag> ::= <integer>
  77 <file name> ::= /[^<end of record mark>]*/
  78 This is used to give a shortcut to filenames.
  79
  80 <informations> ::= <output record>? <magnification record>? <unit record>? <x offset record>? <y offset record>?
  81
  82 <output record> ::= /Output:/<output><end of record mark>
  83 <output> ::= /dvi|pdf|xdv|[0-9a-zA-Z]*/
  84
  85 <magnification record> ::= /Magnification:/<magnification><end of record>
  86 <magnification> ::= <integer>
  87 This is the TeX magnification.
  88
  89 <unit record> ::= /Unit:<unit><end of record>/
  90 <unit> ::= <integer>
  91 The SyncTeX unit is <unit> scaled point, 1 in general, 8192 when not given.
  92
  93 <x offset record> ::= /X Offset:/<x offset><end of record>
  94 <x offset> ::= <integer>
  95 <y offset record> ::= /Y Offset:/<y offset><end of record>
  96 <y offset> ::= <integer>
  97 The offset or the origin of the system of coordinates from the top left point of the page.
  98 This defaults to 1in for both the vertical and horizontal offsets.
  99 Both offsets are given in this section in scaled point unit.
 100
 101 <forthcoming records>: The preamble, like any other section may contain in the future any other kind of record,
 102 except the one starting the next section. In order to ensure some forwards compatibility,
 103 parsers should anticipate and parse unknown records: an unexpected record should be silently ignored by the parser.
 104 This means that this format is somehow open an more types of records can be added without breaking existing software.
 105
 106 The preamble ends when a record is found that fits the following section.
 107
 108 The contents:
 109 -------------
 110 <contents> ::= <contents record><sheet(1)><i line>*<sheet(2)><i line>*...<sheet(N)><i line>*
 111
 112 <contents record>::=/Contents:/<byte offset><end of record>/
 113 <offset> ::= <byte offset>
 114 <sheet(n)> ::= <sheet(n) start><v content>*<sheet end>
 115 <sheet(n) start> ::= /{/<byte offset>/:/<the integer n><end of record>/
 116 <sheet end> ::= /}/<byte offset><end of record>
 117
 118 <box content> ::= <vbox section>|<hbox section>|<void vbox record>|<void hbox record>
 119 <vbox section> ::= (<vbox start record><vbox content>*<vbox stop record>)|<box content>*
 120 <hbox content> ::= <glue record>|<kern record>|<math record>|<box content>
 121 <hbox section> ::= <hbox start record><box content>*<hbox stop record>
 122
 123 <void vbox record> ::= /v/<link>/:/<point>/:/<size><end of record>
 124 <void hbox record> ::= /h/<link>/:/<point>/:/<size><end of record>
 125 <size> ::= <W>/,/<H>/,/<D>
 126 <W> ::= <integer>
 127 <H> ::= <integer>
 128 <D> ::= <integer>
 129 <link> ::= <tag>/,/<line>(/,/<column>)?
 130 <line> ::= <integer>
 131 <column> ::= <integer>
 132
 133 <current record> ::= /x/<link>/:/<point><end of record>
 134 <kern record> ::= /k/<link>/:/<point>/:/<W><end of record>
 135 <glue record> ::= /g/<link>/:/<point><end of record>
 136 <math record> ::= /$/<link>/:/<point><end of record>
 137
 138 The byte offset is an implicit anchor to navigate the synctex file from sheet to sheet.
 139
 140 The postamble:
 141 --------------
 142 The postamble closes the file
 143 If there is no postamble, it means that the typesetting process did not end correctly.
 144 <postamble> ::= <postamble record><number of objects record>
 145
 146 <postamble record> ::= /Postamble:/<byte offset><end of record>
 147 <number of objects record> ::= /Count:/<integer><end of record>
 148
 149 The post scriptum:
 150 ------------------
 151 The post scriptum contains material possibly added by 3rd parties.
 152 It allows to append some transformation (shift and magnify).
 153 Typically, one applies a dvi to pdf filter with offset options and magnification,
 154 then he appends the same options to the synctex file, for example
 155
 156         dvipdfmx -m 0.486 -x 9472573sp -y 13.3dd source.dvi
 157         echo "X Offset:9472573" >> source.synctex
 158         echo "Y Offset:13.3dd" >> source.synctex
 159         echo "Magnification:0.486" >> source.synctex
 160
 161
 162 <post scriptum> ::= (<magnification line>|<x offset line>|<y offset line>)*
 163 <magnification line> ::= /Magnification:/<post magnification><end of line mark>
 164 <post magnification> ::= <unsigned decimal float>
 165 <x offset line> ::= /X Offset:/<post x offset><end of line mark>
 166 <post x offset> ::= <sign><unsigned decimal float><offset unit>
 167 <y offset> ::= <x offset>
 168 <sign> ::= /(+|-)?/
 169 <offset unit> ::= /(in|cm|mm|pt|bp|pc|sp|dd|cc|nd|nc)?/
 170 <end of line mark> ::= /[\n\r]*/
 171 <y offset line> ::= /Y Offset:/<post y offset><end of line mark>
 172 <post y offset> ::= <sign><unsigned decimal float><offset unit>
 173
 174 This second information will override the offset and magnification previously available in the preamble section.
 175 All the numbers are encoded using the decimal representation with "C" locale.
 176