Warning, /graphics/okular/core/synctex/synctex_parser_readme.md is written in an unsupported language. File is not indexed.
0001 # __SyncTeX__ 0002 0003 This file is part of the __SyncTeX__ package. 0004 0005 [//]: # (Version: 1.19) 0006 [//]: # (Date: Fri Jul 14 16:20:41 UTC 2017) 0007 0008 ## Important 0009 0010 * Changes in version `1.19` 0011 0012 A long standing bug affecting only pdftex has been fixed by adding support to pdf forms. As a side effect, the synchronization algorithm gains in accuracy for all the engines, especially from pdf to source. Of course, there is a small cost in both memory footprint and computational time, but none is noticeable. 0013 0014 Some technical changes in the API. 0015 * more consistent type naming convention 0016 * `_s` suffix for struct's 0017 * `_p` suffix for pointers 0018 * `_t` suffix for standard types 0019 * `_f` suffix for functions... 0020 0021 thus `synctex_node_t` has become `synctex_node_p`. 0022 0023 * supplemental argument in `synctex_display_query`. Set `page_hint` to the currently displayed pdf page number (0 based). If this info is not available, set `page_hint` to 0, it corresponds to the old behaviour. 0024 * rename `synctex_next_result` to `synctex_scanner_next_result` 0025 * additional `synctex_parser_private.h` header where 0026 more API are exposed. For an advanced usage only (eg parallel synchronizations). 0027 * `SYNCTEX_NO_UPDATER` preprocessor macro to deactivate some code useless to frontends. 0028 0029 ## What is it ? 0030 0031 The *Synchronization TeXnology* named __SyncTeX__ is a new feature 0032 of recent __TeX__ engines designed by Jérôme Laurens. 0033 It allows to synchronize between input and output, which means to 0034 navigate from the source document to the typeset material and vice versa. 0035 Browse the source code for more information. 0036 0037 ## Contents 0038 This package is mainly for developers, it contains the following files: 0039 0040 * `synctex_parser_readme.md` (this file) 0041 * `synctex_parser_version.txt` 0042 * `synctex_parser_utils.c` 0043 * `synctex_parser_utils.h` 0044 * `synctex_parser_local.h` 0045 * `synctex_parser.h` 0046 * `synctex_parser_advanced.h` 0047 * `synctex_parser.c` 0048 0049 The file you are reading contains more informations about the __SyncTeX__ parser history. 0050 0051 ## Source 0052 0053 All stable sources are available from [TeXLive repository](http://www.tug.org/svn/texlive/trunk/Build/source/texk/web2c/synctexdir/). 0054 0055 Latest development sources are available from GitHub. 0056 0057 Please notice that due to the complexity of the TeXLive TeX distribution, there might be some delay before synchronization occurs between various repositories. 0058 0059 ## Usage 0060 0061 In order to support __SyncTeX__ in a viewer, it is sufficient to include 0062 in the source the files `synctex_parser.c` and `synctex_parser_utils.c`. 0063 The synctex parser usage is described in `synctex_parser.h` header file. 0064 0065 More advanced usage is found in `synctex_parser_advanced.h` 0066 0067 The other files are used by tex engines or by the synctex command line utility: 0068 0069 ``` 0070 ChangeLog 0071 README.txt 0072 am 0073 man1 0074 man5 0075 synctex-common.h 0076 synctex-convert.sh 0077 synctex-e-mem.ch0 0078 synctex-e-mem.ch1 0079 synctex-e-rec.ch0 0080 synctex-e-rec.ch1 0081 synctex-etex.h 0082 synctex-mem.ch0 0083 synctex-mem.ch1 0084 synctex-mem.ch2 0085 synctex-pdf-rec.ch2 0086 synctex-pdftex.h 0087 synctex-rec.ch0 0088 synctex-rec.ch1 0089 synctex-rec.ch2 0090 synctex-tex.h 0091 synctex-xe-mem.ch2 0092 synctex-xe-rec.ch2 0093 synctex-xe-rec.ch3 0094 synctex-xetex.h 0095 synctex.c 0096 synctex.defines 0097 synctex.h 0098 synctex_main.c 0099 tests 0100 ... 0101 ``` 0102 0103 ## Version: 0104 0105 This is version 1, which refers to the synctex output file format. 0106 0107 The files are identified by a build number. 0108 In order to help developers to automatically manage the version and build numbers 0109 and download the parser only when necessary, the `synctex_parser_version.txt` 0110 is an ASCII text file just containing the current version and build numbers eg `1.19`. 0111 0112 ## History: 0113 0114 * 1.1: Thu Jul 17 09:28:13 UTC 2008 0115 - First official version available in TeXLive 2008 DVD. 0116 Unfortunately, the backwards synchronization is not working properly mainly for ConTeXt users, see below. 0117 * 1.2: Tue Sep 2 10:28:32 UTC 2008 0118 - Correction for ConTeXt support in the edit query. 0119 The previous method was assuming that TeX boxes do not overlap, 0120 which is reasonable for LaTeX but not for ConTeXt. 0121 This assumption is no longer considered. 0122 * 1.3: Fri Sep 5 09:39:57 UTC 2008 0123 - Local variable "read" renamed to "already_read" to avoid conflicts. 0124 - "inline" compiler directive renamed to "SYNCTEX_INLINE" for code support and maintenance 0125 - _synctex_error cannot be inlined due to variable arguments (thanks Christiaan Hofman) 0126 - Correction in the display query, extra boundary nodes are used for a more precise forwards synchronization 0127 * 1.4: Fri Sep 12 08:12:34 UTC 2008 0128 - For an unknown reason, the previous version was not the real 1.3 (as used in iTeXMac2 build 747). 0129 As a consequence, a crash was observed. 0130 - Some typos are fixed. 0131 * 1.6: Mon Nov 3 20:20:02 UTC 2008 0132 - The bug that prevented synchronization with compressed files on windows has been fixed. 0133 - New interface to allow system specific customization. 0134 - Note that some APIs have changed. 0135 * 1.8: Mer 8 jul 2009 11:32:38 UTC 0136 Note that version 1.7 was delivered privately. 0137 - bug fix: synctex was causing a memory leak in pdftex and xetex, thus some processing speed degradation 0138 - bug fix: the synctex command line tool was broken when updating a .synctex file 0139 - enhancement: better accuracy of the synchronization process 0140 - enhancement: the pdf output file and the associated .synctex file no longer need to live in the same directory. 0141 The new -d option of the synctex command line tool manages this situation. 0142 This is handy when using something like tex -output-directory=DIR ... 0143 * 1.9: Wed Nov 4 11:52:35 UTC 2009 0144 - Various typo fixed 0145 - OutputDebugString replaced by OutputDebugStringA to deliberately disable unicode preprocessing 0146 - New conditional created because OutputDebugStringA is only available since Windows 2K professional 0147 * 1.10: Sun Jan 10 10:12:32 UTC 2010 0148 - Bug fix in synctex_parser.c to solve a synchronization problem with amsmath's gather environment. 0149 Concerns the synctex tool. 0150 * 1.11: Sun Jan 17 09:12:31 UTC 2010 0151 - Bug fix in synctex_parser.c, function synctex_node_box_visible_v: 'x' replaced by 'y'. 0152 Only 3rd party tools are concerned. 0153 * 1.12: Mon Jul 19 21:52:10 UTC 2010 0154 - Bug fix in synctex_parser.c, function __synctex_open: the io_mode was modified even in case of a non zero return, 0155 causing a void .synctex.gz file to be created even if it was not expected. Reported by Marek Kasik concerning a bug on evince. 0156 * 1.13: Fri Mar 11 07:39:12 UTC 2011 0157 - Bug fix in synctex_parser.c, better synchronization as suggested by Jan Sundermeyer (near line 3388). 0158 - Stronger code design in synctex_parser_utils.c, function _synctex_get_name (really neutral behavior). 0159 Only 3rd party tools are concerned. 0160 * 1.14: Fri Apr 15 19:10:57 UTC 2011 0161 - taking output_directory into account 0162 - Replaced FOPEN_WBIN_MODE by FOPEN_W_MODE when opening the text version of the .synctex file. 0163 - Merging with LuaTeX's version of synctex.c 0164 * 1.15: Fri Jun 10 14:10:17 UTC 2011 0165 This concerns the synctex command line tool and 3rd party developers. 0166 TeX and friends are not concerned by these changes. 0167 - Bug fixed in _synctex_get_io_mode_name, sometimes the wrong mode was returned 0168 - Support for LuaTeX convention of './' file prefixing 0169 * 1.16: Tue Jun 14 08:23:30 UTC 2011 0170 This concerns the synctex command line tool and 3rd party developers. 0171 TeX and friends are not concerned by these changes. 0172 - Better forward search (thanks Jose Alliste) 0173 - Support for LuaTeX convention of './' file prefixing now for everyone, not only for Windows 0174 * 1.17: Fri Oct 14 08:15:16 UTC 2011 0175 This concerns the synctex command line tool and 3rd party developers. 0176 TeX and friends are not concerned by these changes. 0177 - synctex_parser.c: cosmetic changes to enhance code readability 0178 - Better forward synchronization. 0179 The problem occurs for example with LaTeX \item command. 0180 The fact is that this command creates nodes at parse time but these nodes are used only 0181 after the text material of the \item is displayed on the page. The consequence is that sometimes, 0182 forward synchronization spots an irrelevant point from the point of view of the editing process. 0183 This was due to some very basic filtering policy, where a somehow arbitrary choice was made when 0184 many different possibilities where offered for synchronisation. 0185 Now, forward synchronization prefers nodes inside an hbox with as many acceptable spots as possible. 0186 This is achieved with the notion of mean line and node weight. 0187 - Adding support for the new file naming convention with './' 0188 - function `synctex_ignore_leading_dot_slash_in_path replaces` `synctex_ignore_leading_dot_slash` 0189 - function `_synctex_is_equivalent_file_name` is more permissive 0190 Previously, the function synctex_scanner_get_tag would give an answer only when 0191 the given file name was EXACTLY one of the file names listed in the synctex file. 0192 The we added some changes accepting for example 'foo.tex' instead of './foo.tex'. 0193 Now we have an even looser policy for dealing with file names. 0194 If the given file name does not match exactly one the file names of the synctex file, 0195 then we try to match the base names. If there is only one match of the base names, 0196 then it is taken as a match for the whole names. 0197 The base name is defined as following: 0198 0199 `./foo => foo 0200 /my///.////foo => foo 0201 /foo => /foo 0202 /my//.foo => /my//.foo` 0203 0204 * 1.17: Tue Mar 13 10:10:03 UTC 2012 0205 - minor changes, no version changes 0206 - syntax man pages are fixed as suggested by M. Shimata 0207 see mail to tex-live@tug.org titled "syntax.5 has many warnings from groff" and "syntax.1 use invalid macro for mdoc" 0208 - 1.17: Tue Jan 14 09:55:00 UTC 2014, fixed a segfault, patch from Sebastian Ramacher 0209 - 1.17: Mon Aug 04, fixed a memory leak 0210 * 1.18: Thu Jun 25 11:36:05 UTC 2015 0211 - nested sheets now fully supported (does it make sense in TeX) 0212 - cosmetic changes: uniform indentation 0213 - suppression of warnings, mainly long/int ones. In short, zlib likes ints when size_t likes longs. 0214 - CLI synctex tool can build out of TeXLive (modulo appropriate options passed to the compiler) 0215 * 1.19: Mon Jul 3 20:03:56 UTC 2017 0216 - the nested sheets patch was not a good solution. 0217 It has been moved from the parser to the engine. 0218 See the `synctex.c` source file for detailed explanations. 0219 - there is a new synctex format specification. 0220 We can see that a `.synctex` file can contain many times 0221 the same vertical position because many objects belong 0222 to the same line. When the options read `-synctex=±2` or more, 0223 a very basic compression algorithm is used: 0224 if synctex is about to write the same number then it writes 0225 an `=` sign instead. This saves approximately 10% of the 0226 synctex output file, either compressed or not. 0227 The new synctex parser has been updated accordingly. 0228 Actual tex frontend won't see any difference with the 0229 TeX engines that include this new feature. 0230 Frontends with the new parser won't see any difference 0231 with the older TeX engines. 0232 Frontends with the new parser will only see a difference 0233 with new TeX engines if `-synctex=±2` or more is used. 0234 0235 ## Acknowledgments: 0236 0237 The author received useful remarks from the __pdfTeX__ developers, especially Hahn The Thanh, 0238 and significant help from __XeTeX__ developer Jonathan Kew. 0239 0240 ## Nota Bene: 0241 0242 If you include or use a significant part of the __SyncTeX__ package into a software, 0243 I would appreciate to be listed as contributor and see __SyncTeX__" highlighted. 0244 0245 Copyright (c) 2008-2017 jerome DOT laurens AT u-bourgogne DOT fr 0246