Source Browser ?

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\ constructs 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, which seems to relate to the way \LATEX\ works. There are some
31comments that \CONTEXT\ is not supported well because it has a layered page
32model, which indicates that there are some assumptions about how macro packages
33are supposed to work. Also the used heuristics not only involve some specific
34spot (location) but also involve the corners and edges. It is therefore not so
35much a (simple) generic system but a mechanism geared for a macro package like
36\LATEX. But we can kind of make it work by fooling the heuristics.
37
38Because we have a couple of users who need to edit complex sets of documents,
39coded in \TEX\ or \XML, I decided to come up with a variant that doesn't use the
40\SYNCTEX\ machinery but manipulates the few \SYNCTEX\ fields directly \footnote
41{This is something that in my opinion should have been possible right from the
42start but it's too late now to change the system and it would not be used beyond
43\CONTEXT\ anyway.} and eventually outputs a straightforward file for the editor.
44Of course we need to follow some rules so that the viewer can deal with it. It
45took a bit of trial and error to get the right information in the support file
46needed by the viewer but we got there.
47
48Actually the previous observation became obsolete when the library that viewers
49are supposed to used changed. Some \PDF\ viewers have their own parsers or use an
50older library which works fine. For the new ones unfortunately we need a cheat.
51
52The prerequisites of a decent \CONTEXT\ \quotation {click on preview and goto
53editor} are the following:
54
55\startitemize
56
57\startitem
58    It only makes sense to click on text in the text flow. Headers and footers
59    are often generated from structure, and special typographic elements can
60    originate in macros hooked into commands instead of in the source.
61\stopitem
62
63\startitem
64    Users should not be able to reach environments (styles) and other files
65    loaded from the (normally read|-|only) \TEX\ tree, like modules. We don't
66    want accidental changes in such files.
67\stopitem
68
69\startitem
70    We not only have \TEX\ files but also \XML\ files and these can normally
71    flush in rather arbitrary ways. Although the concept of lines is sort of
72    lost in such a file, there is still a relation between lines and the snippets
73    that make out the content of an \XML\ node.
74\stopitem
75
76\startitem
77    In the case of \XML\ files the overhead related to preserving line
78    numbers should be minimal and have no impact on loading and memory when
79    these features are not used.
80\stopitem
81
82\startitem
83    The overhead in terms of an auxiliary file size and complexity as well
84    as producing that file should be minimal. It should be easy to turn on and
85    off these features. (I'd never turn them on by default.)
86\stopitem
87
88\stopitemize
89
90It is unavoidable that we get more run time but I assume that for the average
91user that is no big deal. It pays off when you have a workflow when a book (or
92even a chapter in a book) is generated from hundreds of small \XML\ files. There
93is no overhead when \SYNCTEX\ is not used.
94
95In \CONTEXT\ we don't use the built|-|in \SYNCTEX\ features, that is: we let
96filename and line numbers be set but often these are overloaded explicitly. The
97output file is not compressed and constructed by \CONTEXT. There is no benefit in
98compression and the files are probably smaller than default \SYNCTEX\ anyway.
99
100\stopsection
101
102\startsection[title=Commands]
103
104Although you can enable this mechanism with directives it makes sense to do it
105using the following command.
106
107\starttyping
108\setupsynctex[state=start]
109\stoptyping
110
111The advantage of using an explicit command instead of some command line option is
112that in an editor it's easier to disable this trickery. Commenting that line will
113speed up processing when needed. This command can also be given in an environment
114(style). On the command line you can say:
115
116\starttyping
117context --synctex somefile.tex
118\stoptyping
119
120When your viewer doesn't return to the editor, you can try
121
122\starttyping
123\setupsynctex[state=repeat]
124\stoptyping
125
126or
127
128\starttyping
129context --synctex=repeat somefile.tex
130\stoptyping
131
132This will give a bit larger file that tries to fool the areas resolver in the
133library that the viewer uses. When on Mikael Sundqvist machine Okular didn't work
134we spent some time figuring out why and eventually came up with a cheat that
135seemed to work on the average with various viewers. The way viewers implement the
136\quote {go back to the editor and file} differ so we leave that for users to
137figure out. Very few editors are able to delegate resolving the file and line
138from position on the page to a script which would be a generic solution (actually
139also more independent of \TEX).
140
141Often an \XML\ files is very structured and although probably the main body of
142text is flushed as a stream, specific elements can be flushed out of order. In
143educational documents flushing for instance answers to exercises can happen out
144of order. In that case we still need to make sure that we go to the right spot in
145the file. It will never be 100\% perfect but it's better than nothing. The above
146command will also enable \XML\ support.
147
148If you don't want a file to be accessed, you can block it:
149
150\starttyping
151\blocksynctexfile[foo.tex]
152\stoptyping
153
154Of course you need to configure the viewer to respond to the request for editing.
155In Sumatra combined with \SCITE\ the magic command is:
156
157\starttyping
158c:\data\system\scite\wscite\scite.exe "%f" "-goto:%l"
159\stoptyping
160
161Such a command is independent of the macro package so you can just consult the
162manual or help info that comes with a viewer, given that it supports this linking
163back to the source at all.
164
165\stopsection
166
167\startsection[title=Methods]
168
169Contrary to the native \SYNCTEX\ we only deal with text which gives reasonable
170efficient output. If you enable tracing (see next section) you can what has
171become clickable. Instead of words you can also work with ranges, which not only
172gives less runtime but also much smaller \type {.synctex} files. Just try:
173
174\starttyping
175\setupsynctex[state=start,method=min] % or state=repeat
176\stoptyping
177
178to get words clickable and
179
180\starttyping
181\setupsynctex[state=start,method=max] % or state=repeat
182\stoptyping
183
184to get the more efficient ranges. The overhead for \type {min} is some 10 percent
185while \type {max} slows down around 5 percent.
186
187\stopsection
188
189\startsection[title=Tracing]
190
191In case you want to see what gets synced you can enable a tracker:
192
193\starttyping
194\enabletrackers[system.synctex.visualize]
195\enabletrackers[system.synctex.visualize=real]
196\stoptyping
197
198The following tracker outputs some status information about \XML\ flushing. Such
199trackers only make sense for developers.
200
201\starttyping
202\enabletrackers[system.synctex.xml]
203\stoptyping
204
205% At the cost of some extra overhead, the next (experimental) directive can be used
206% when the accuracy is not optimal.
207%
208% \starttyping
209% \enabledirectives[system.synctex.details]
210% \stoptyping
211
212\stopsection
213
214\startsection[title=Warning]
215
216Don't turn on this feature when you don't need it. This is one of those mechanism
217that hits performance badly.
218
219Depending on needs the functionality can be improved and|/|or extended. Of course
220you can always use the traditional \SYNCTEX\ method but don't expect it to behave
221as described here.
222
223\stopsection
224
225\startsection[title=Two-way]
226
227In for instance the \TEX shop editor, there is a two way connection. The nice
228thing about this editor is, is that it is also the first one to use the \type
229{mtx-synctex} script to resolve these links, instead of relying on a library. You
230can also use this script to inspect a \SYNCTEX\ file yourself. The help info
231shows the possible directives.
232
233\starttyping
234mtxrun --script synctex
235\stoptyping
236
237You can resolve positions in the \PDF\ as well as in the sources and list all the
238known areas in the log.
239
240\stopsection
241
242\stopchapter
243
244\stopcomponent
245