workflows-synctex.tex /size: 8165 b    last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/workflows
2
3\environment workflows-style
4
5\startcomponent workflows-xml
6
7\startchapter[title=\SYNCTEX]
8
9\startsection[title=Introduction]
10
11Some users like the \SYNCTEX\ feature that is built in the \TEX\ engines.
12Personally I never use it because it doesn't work well with the kind of documents
13I maintain. If you have one document source, and don't shuffle around (reuse)
14text too much it probably works out okay but that is not our practice. Here I
15will describe how you can enable a more \CONTEXT\ specific \SYNCTEX\ support so
16that aware \PDF\ viewers can bring you back to the source.
17
18\stopsection
19
20\startsection[title=What we want]
21
22The \SYNCTEX\ method roughly works as follows. Internally \TEX\ constricts linked
23lists of glyphs, kerns, glue, boxes, rules etc. These elements are called nodes.
24Some nodes carry information about the file and line where they were created. In
25the backend this information gets somehow translated in a (sort of) verbose tree
26that describes the makeup in terms of boxes, glue and kerns. From that
27information the \SYNCTEX\ parser library, hooked into a \PDF\ viewer, can go back
28from a position on the screen to a line in a file. One would expect this to be a
29relative simple rectangle based model, but as far as I can see it's way more
30complex than that. There are some comments that \CONTEXT\ is not supported well
31because it has a layered page model, which indicates that there are some
32assumptions about how macro packages are supposed to work. Also the used
33heuristics not only involve some specific spot (location) but also involve the
34corners and edges. It is therefore not so much a (simple) generic system but a
35mechanism geared for a macro package like \LATEX.
36
37Because we have a couple of users who need to edit complex sets of documents,
38coded in \TEX\ or \XML, I decided to come up with a variant that doesn't use the
39\SYNCTEX\ machinery but manipulates the few \SYNCTEX\ fields directly \footnote {This
40is something that in my opinion should have been possible right from the start
41but it's too late now to change the system and it would not be used beyond
42\CONTEXT\ anyway.} and eventually outputs a straightforward file for the editor.
43Of course we need to follow some rules so that the editor can deal with it. It
44took a bit of trial and error to get the right information in the support file
45needed by the viewer but we got there.
46
47The prerequisites of a decent \CONTEXT\ \quotation {click on preview and goto
48editor} are the following:
49
50\startitemize
51
52\startitem
53    It only makes sense to click on text in the text flow. Headers and footers
54    are often generated from structure, and special typographic elements can
55    originate in macros hooked into commands instead of in the source.
56\stopitem
57
58\startitem
59    Users should not be able to reach environments (styles) and other files
60    loaded from the (normally read|-|only) \TEX\ tree, like modules. We don't
61    want accidental changes in such files.
62\stopitem
63
64\startitem
65    We not only have \TEX\ files but also \XML\ files and these can normally
66    flush in rather arbitrary ways. Although the concept of lines is sort of
67    lost in such a file, there is still a relation between lines and the snippets
68    that make out the content of an \XML\ node.
69\stopitem
70
71\startitem
72    In the case of \XML\ files the overhead related to preserving line
73    numbers should be minimal and have no impact on loading and memory when
74    these features are not used.
75\stopitem
76
77\startitem
78    The overhead in terms of an auxiliary file size and complexity as well
79    as producing that file should be minimal. It should be easy to turn on and
80    off these features. (I'd never turn them on by default.)
81\stopitem
82
83\stopitemize
84
85It is unavoidable that we get more run time but I assume that for the average
86user that is no big deal. It pays off when you have a workflow when a book (or
87even a chapter in a book) is generated from hundreds of small \XML\ files. There
88is no overhead when \SYNCTEX\ is not used.
89
90In \CONTEXT\ we don't use the built|-|in \SYNCTEX\ features, that is: we let
91filename and line numbers be set but often these are overloaded explicitly. The
92output file is not compressed and constructed by \CONTEXT. There is no benefit in
93compression and the files are probably smaller than default \SYNCTEX\ anyway.
94
95\stopsection
96
97\startsection[title=Commands]
98
99Although you can enable this mechanism with directives it makes sense to do it
100using the following command.
101
102\starttyping
103\setupsynctex[state=start]
104\stoptyping
105
106The advantage of using an explicit command instead of some command line option is
107that in an editor it's easier to disable this trickery. Commenting that line will
108speed up processing when needed. This command can also be given in an environment
109(style). On the command line you can say
110
111\starttyping
112context --synctex somefile.tex
113\stoptyping
114
115A third method is to put this at the top of your file:
116
117\starttyping
118% synctex=yes
119\stoptyping
120
121Often an \XML\ files is very structured and although probably the main body of
122text is flushed as a stream, specific elements can be flushed out of order. In
123educational documents flushing for instance answers to exercises can happen out
124of order. In that case we still need to make sure that we go to the right spot in
125the file. It will never be 100\% perfect but it's better than nothing. The above
126command will also enable \XML\ support.
127
128If you don't want a file to be accessed, you can block it:
129
130\starttyping
131\blocksynctexfile[foo.tex]
132\stoptyping
133
134Of course you need to configure the viewer to respond to the request for editing.
135In Sumatra combined with \SCITE\ the magic command is:
136
137\starttyping
138c:\data\system\scite\wscite\scite.exe "%f" "-goto:%l"
139\stoptyping
140
141Such a command is independent of the macro package so you can just consult the
142manual or help info that comes with a viewer, given that it supports this linking
143back to the source at all.
144
145\stopsection
146
147\startsection[title=Methods]
148
149Contrary to the native \SYNCTEX\ we only deal with text which gives reasonable
150efficient output. If you enable tracing (see next section) you can what has
151become clickable. Instead of words you can also work with ranges, which not only
152gives less runtime but also much smaller \type {.synctex} files. Just try:
153
154\starttyping
155\setupsynctex[state=start,method=min]
156\stoptyping
157
158to get words clickable and
159
160\starttyping
161\setupsynctex[state=start,method=max]
162\stoptyping
163
164to get the more efficient ranges. The overhead for \type {min} is some 10 percent
165while \type {max} slows down around 5 percent.
166
167\stopsection
168
169\startsection[title=Tracing]
170
171In case you want to see what gets synced you can enable a tracker:
172
173\starttyping
174\enabletrackers[system.synctex.visualize]
175\enabletrackers[system.synctex.visualize=real]
176\stoptyping
177
178The following tracker outputs some status information about \XML\ flushing. Such
179trackers only make sense for developers.
180
181\starttyping
182\enabletrackers[system.synctex.xml]
183\stoptyping
184
185% At the cost of some extra overhead, the next (experimental) directive can be used
186% when the accuracy is not optimal.
187%
188% \starttyping
189% \enabledirectives[system.synctex.details]
190% \stoptyping
191
192\stopsection
193
194\startsection[title=Warning]
195
196Don't turn on this feature when you don't need it. This is one of those mechanism
197that hits performance badly.
198
199Depending on needs the functionality can be improved and|/|or extended. Of course
200you can always use the traditional \SYNCTEX\ method but don't expect it to behave
201as described here.
202
203\stopsection
204
205\startsection[title=Two-way]
206
207In for instance the \TEX shop editor, there is a two way connection. The nice
208thing about this editor is, is that it is also the first one to use the \type
209{mtx-synctex} script to resolve these links, instead of relying on a library. You
210can also use this script to inspect a \SYNCTEX\ file yourself, The help into
211shows the possible directives.
212
213\starttyping
214mtxrun --script synctex
215\stoptyping
216
217You can resolve positions in the \PDF\ as well as in the sources and list all the
218known areas in the log.
219
220\stopsection
221
222\stopchapter
223
224\stopcomponent
225