synctex_parser_readme.txt (9625B)
1 This file is part of the SyncTeX package. 2 3 Please refer to synctex_parser_readme.md 4 5 The Synchronization TeXnology named SyncTeX is a new feature 6 of recent TeX engines designed by Jerome Laurens. 7 It allows to synchronize between input and output, which means to 8 navigate from the source document to the typeset material and vice versa. 9 More information on http://itexmac2.sourceforge.net/SyncTeX.html 10 11 This package is mainly for developers, it mainly contains the following files: 12 13 synctex_parser_readme.txt 14 synctex_parser_version.txt 15 synctex_parser_utils.c 16 synctex_parser_utils.h 17 synctex_parser_local.h 18 synctex_parser_private.h 19 synctex_parser.h 20 synctex_parser.c 21 22 The file you are reading contains more information about the SyncTeX parser history. 23 24 In order to support SyncTeX in a viewer, it is sufficient to include 25 in the source the files synctex_parser.h and synctex_parser.c. 26 The synctex parser usage is described in synctex_parser.h header file. 27 28 The other files are used by tex engines or by the synctex command line utility: 29 30 ChangeLog 31 README.txt 32 am 33 man1 34 man5 35 synctex-common.h 36 synctex-convert.sh 37 synctex-e-mem.ch0 38 synctex-e-mem.ch1 39 synctex-e-rec.ch0 40 synctex-e-rec.ch1 41 synctex-etex.h 42 synctex-mem.ch0 43 synctex-mem.ch1 44 synctex-mem.ch2 45 synctex-pdf-rec.ch2 46 synctex-pdftex.h 47 synctex-rec.ch0 48 synctex-rec.ch1 49 synctex-rec.ch2 50 synctex-tex.h 51 synctex-xe-mem.ch2 52 synctex-xe-rec.ch2 53 synctex-xe-rec.ch3 54 synctex-xetex.h 55 synctex.c 56 synctex.defines 57 synctex.h 58 synctex_main.c 59 tests 60 61 62 Version: 63 -------- 64 This is version 1, which refers to the synctex output file format. 65 The files are identified by a build number. 66 In order to help developers to automatically manage the version and build numbers 67 and download the parser only when necessary, the synctex_parser.version 68 is an ASCII text file just containing the current version and build numbers. 69 70 History: 71 -------- 72 1.1: Thu Jul 17 09:28:13 UTC 2008 73 - First official version available in TeXLive 2008 DVD. 74 Unfortunately, the backwards synchronization is not working properly mainly for ConTeXt users, see below. 75 1.2: Tue Sep 2 10:28:32 UTC 2008 76 - Correction for ConTeXt support in the edit query. 77 The previous method was assuming that TeX boxes do not overlap, 78 which is reasonable for LaTeX but not for ConTeXt. 79 This assumption is no longer considered. 80 1.3: Fri Sep 5 09:39:57 UTC 2008 81 - Local variable "read" renamed to "already_read" to avoid conflicts. 82 - "inline" compiler directive renamed to "SYNCTEX_INLINE" for code support and maintenance 83 - _synctex_error cannot be inlined due to variable arguments (thanks Christiaan Hofman) 84 - Correction in the display query, extra boundary nodes are used for a more precise forwards synchronization 85 1.4: Fri Sep 12 08:12:34 UTC 2008 86 - For an unknown reason, the previous version was not the real 1.3 (as used in iTeXMac2 build 747). 87 As a consequence, a crash was observed. 88 - Some typos are fixed. 89 1.6: Mon Nov 3 20:20:02 UTC 2008 90 - The bug that prevented synchronization with compressed files on windows has been fixed. 91 - New interface to allow system specific customization. 92 - Note that some APIs have changed. 93 1.8: Mer 8 jul 2009 11:32:38 UTC 94 Note that version 1.7 was delivered privately. 95 - bug fix: synctex was causing a memory leak in pdftex and xetex, thus some processing speed degradation 96 - bug fix: the synctex command line tool was broken when updating a .synctex file 97 - enhancement: better accuracy of the synchronization process 98 - enhancement: the pdf output file and the associated .synctex file no longer need to live in the same directory. 99 The new -d option of the synctex command line tool manages this situation. 100 This is handy when using something like tex -output-directory=DIR ... 101 1.9: Wed Nov 4 11:52:35 UTC 2009 102 - Various typo fixed 103 - OutputDebugString replaced by OutputDebugStringA to deliberately disable unicode preprocessing 104 - New conditional created because OutputDebugStringA is only available since Windows 2K professional 105 1.10: Sun Jan 10 10:12:32 UTC 2010 106 - Bug fix in synctex_parser.c to solve a synchronization problem with amsmath's gather environment. 107 Concerns the synctex tool. 108 1.11: Sun Jan 17 09:12:31 UTC 2010 109 - Bug fix in synctex_parser.c, function synctex_node_box_visible_v: 'x' replaced by 'y'. 110 Only 3rd party tools are concerned. 111 1.12: Mon Jul 19 21:52:10 UTC 2010 112 - Bug fix in synctex_parser.c, function __synctex_open: the io_mode was modified even in case of a non zero return, 113 causing a void .synctex.gz file to be created even if it was not expected. Reported by Marek Kasik concerning a bug on evince. 114 1.13: Fri Mar 11 07:39:12 UTC 2011 115 - Bug fix in synctex_parser.c, better synchronization as suggested by Jan Sundermeyer (near line 3388). 116 - Stronger code design in synctex_parser_utils.c, function _synctex_get_name (really neutral behavior). 117 Only 3rd party tools are concerned. 118 1.14: Fri Apr 15 19:10:57 UTC 2011 119 - taking output_directory into account 120 - Replaced FOPEN_WBIN_MODE by FOPEN_W_MODE when opening the text version of the .synctex file. 121 - Merging with LuaTeX's version of synctex.c 122 1.15: Fri Jun 10 14:10:17 UTC 2011 123 This concerns the synctex command line tool and 3rd party developers. 124 TeX and friends are not concerned by these changes. 125 - Bug fixed in _synctex_get_io_mode_name, sometimes the wrong mode was returned 126 - Support for LuaTeX convention of './' file prefixing 127 1.16: Tue Jun 14 08:23:30 UTC 2011 128 This concerns the synctex command line tool and 3rd party developers. 129 TeX and friends are not concerned by these changes. 130 - Better forward search (thanks Jose Alliste) 131 - Support for LuaTeX convention of './' file prefixing now for everyone, not only for Windows 132 1.17: Fri Oct 14 08:15:16 UTC 2011 133 This concerns the synctex command line tool and 3rd party developers. 134 TeX and friends are not concerned by these changes. 135 - synctex_parser.c: cosmetic changes to enhance code readability 136 - Better forward synchronization. 137 The problem occurs for example with LaTeX \item command. 138 The fact is that this command creates nodes at parse time but these nodes are used only 139 after the text material of the \item is displayed on the page. The consequence is that sometimes, 140 forward synchronization spots an irrelevant point from the point of view of the editing process. 141 This was due to some very basic filtering policy, where a somehow arbitrary choice was made when 142 many different possibilities where offered for synchronisation. 143 Now, forward synchronization prefers nodes inside an hbox with as many acceptable spots as possible. 144 This is achieved with the notion of mean line and node weight. 145 - Adding support for the new file naming convention with './' 146 + function synctex_ignore_leading_dot_slash_in_path replaces synctex_ignore_leading_dot_slash 147 + function _synctex_is_equivalent_file_name is more permissive 148 Previously, the function synctex_scanner_get_tag would give an answer only when 149 the given file name was EXACTLY one of the file names listed in the synctex file. 150 The we added some changes accepting for example 'foo.tex' instead of './foo.tex'. 151 Now we have an even looser policy for dealing with file names. 152 If the given file name does not match exactly one the file names of the synctex file, 153 then we try to match the base names. If there is only one match of the base names, 154 then it is taken as a match for the whole names. 155 The base name is defined as following: 156 ./foo => foo 157 /my///.////foo => foo 158 /foo => /foo 159 /my//.foo => /my//.foo 160 1.17: Tue Mar 13 10:10:03 UTC 2012 161 - minor changes, no version changes 162 - syntax man pages are fixed as suggested by M. Shimata 163 see mail to tex-live@tug.org titled "syntax.5 has many warnings from groff" and "syntax.1 use invalid macro for mdoc" 164 1.17: Tue Jan 14 09:55:00 UTC 2014 165 - fixed a segfault, from Sebastian Ramacher 166 1.17: Mon Aug 04 167 - fixed a memory leak 168 1.18: Thu Jun 25 11:36:05 UTC 2015 169 - nested sheets now fully supported (does it make sense in TeX) 170 - cosmetic changes: uniform indentation 171 - suppression of warnings, mainly long/int ones. In short, zlib likes ints when size_t likes longs. 172 - CLI synctex tool can build out of TeXLive (modulo appropriate options passed to the compiler) 173 1.19: Thu Mar 9 21:26:27 UTC 2017 174 - the nested sheets patch was not a good solution. 175 It has been moved from the parser to the engine. 176 See the synctex.c source file for detailed explanations. 177 - there is a new synctex format specification. 178 We can see that a .synctex file can contain many times 179 the same vertical position because many objects belong 180 to the same line. When the options read -synctex=±2 or more, 181 a very basic compression algorithm is used: 182 if synctex is about write the same number then it writes 183 an = sign instead. This saves approximately 10% of the 184 synctex output file, either compressed or not. 185 The new synctex parser has been updated accordingly. 186 Actual tex frontend won't see any difference with the 187 TeX engines that include this new feature. 188 Frontends with the new parser won't see any difference 189 with the older TeX engines. 190 Frontends with the new parser will only see a difference 191 with new TeX engines if -synctex=±2 or more is used. 192 193 Acknowledgments: 194 ---------------- 195 The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh, 196 and significant help from XeTeX developer Jonathan Kew 197 198 Nota Bene: 199 ---------- 200 If you include or use a significant part of the synctex package into a software, 201 I would appreciate to be listed as contributor and see "SyncTeX" highlighted. 202 203 Copyright (c) 2008-2014 jerome DOT laurens AT u-bourgogne DOT fr 204