1
2
3\environment workflowsstyle
4
5\startcomponent workflowsxml
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 doesnt work well with the kind of documents
13I maintain. If you have one document source, and dont 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 its 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 doesnt 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 its 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 readonly) \TEX\ tree, like modules. We dont
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. (Id 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 dont use the builtin \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 its 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
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 its better than nothing. The above
126command will also enable \XML\ support.
127
128If you dont 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 "
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
186
187
188
189
190
191
192\stopsection
193
194\startsection[title=Warning]
195
196Dont turn on this feature when you dont need it. This is one of those mechanism
197that hits performance badly.
198
199Depending on needs the functionality can be improved andor extended. Of course
200you can always use the traditional \SYNCTEX\ method but dont expect it to behave
201as described here.
202
203\stopsection
204
205\startsection[title=Twoway]
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{mtxsynctex} 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 |