1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
% language=uk
\environment interaction-style
\usemodule[references-identify]
\startcomponent interaction-actions
\startchapter[title=Actions]
The reference mechanism not only deals with the more traditional cross
references, but also takes care of navigation, launching applications (although
that is often limited by viewers), running \JAVASCRIPT, etc. By integrating these
features in one mechanism, we limit the number of commands needed for hyperlinks,
menus and buttons. Normally such actions are driven by the \type {\goto} command,
but you can also use buttons:
\starttyping
\goto[inner reference]
\goto[outer reference::]
\goto[outer reference::inner reference]
\stoptyping
The inner reference is normally a user defined one, for instance a reference to a
named location like a chapter or figure. The outer reference refers to a file or
\URL and is normally defined at the document level and is accessed by the \type
{::}. By using symbolic names updating them becomes easier.
There are also predefined references, like \type {nextpage} to go to the next
page or \type {forward} to cycle, \type {nextcontents} for the next level table
of contents in a linked list of such tables, etc. Some keywords are actually
shortcuts to actions that are delegated to the viewer. Here you need to keep in
mind that nowadays we're talking of \PDF\ viewers, but originally (\MKII) we also
supported \DVI\ viewers. A special class of references are the viewer control
ones, like \type {CloseDocument} or \type {PreviousJump}. They can be recognized
by their capitals.
When we speak of a reference, we actually refer to a whole bunch of possible
references. We already mentioned inner and outer references, but special actions
are also possible. These are actually plugins. Examples are the \JAVASCRIPT\ and
\URL\ plugins. The interface evolved a bit over a few decades but most has been
there right from the start, which is why we keep it as is. Actually, there is not
that much new functionality added in \MKIV, although the implementation was
mostly rewritten. Here is a overview of the syntax, just to give you an idea.
\starttyping
\goto[inner]
\goto[inner(foo,bar)]
\goto[inner{argument,argument}]
\goto[inner{argument}]
\goto[outer::]
\goto[outer::inner]
\goto[outer::special(operation{argument,argument})]
\goto[outer::special(operation)]
\goto[outer::special()]
\goto[outer::inner{argument}]
\goto[special(operation{argument})]
\goto[special(operation{argument,argument})]
\goto[special(operation)]
\goto[special(outer::operation)]
\goto[special(operation)]
\goto[special(operation(whatever))]
\goto[special(operation{argument,argument{whatever}})]
\goto[special(operation{argument{whatever}})]
\stoptyping
There can be multiple actions, separated by a comma, think of: go to the page
with label \quote {foo} and start video \quote {bar}.
\showsetup{goto}
Examples of operations are \type {page}, \type {program}, \type {action}, \type
{url} and \type {JS}. \footnote {There are a few more operations but not all make
sense at the user level.} The \type {page} operation accepts a pagenumber as
well as relevant keywords. One can prefix a pagenumber by a file or \URL\ tag.
The \type {program} operation starts up a program. It is an example of an old
feature that has proven to be unstable, simply because viewers change behaviour
over time.
\showsetup{definereference}
The built|-|in actions are interfaces via shortcuts with camelcase names. In most
cases the name is a good indication of what to expect:
\starttyping
\definereference [CloseDocument] [action(close)]
\definereference [ExitViewer] [action(exit)]
\definereference [FirstPage] [action(first)]
\definereference [LastPage] [action(last)]
\definereference [NextJump] [action(forward)]
\definereference [NextPage] [action(next)]
\definereference [PauseMovie] [action(pausemovie)]
\definereference [PauseSound] [action(pausesound)]
\definereference [PauseRendering] [action(pauserendering)]
\definereference [PreviousJump] [action(backward)]
\definereference [PreviousPage] [action(previous)]
\definereference [PrintDocument] [action(print)]
\definereference [SaveForm] [action(exportform)]
\definereference [LoadForm] [action(importform)]
\definereference [ResetForm] [action(resetform)]
\definereference [ResumeMovie] [action(resumemovie)]
\definereference [ResumeSound] [action(resumesound)]
\definereference [ResumeRendering] [action(resumerendering)]
\definereference [SaveDocument] [action(save)]
\definereference [SaveNamedDocument][action(savenamed)]
\definereference [OpenNamedDocument][action(opennamed)]
\definereference [SearchDocument] [action(search)]
\definereference [SearchAgain] [action(searchagain)]
\definereference [StartMovie] [action(startmovie)]
\definereference [StartSound] [action(startsound)]
\definereference [StartRendering] [action(startrendering)]
\definereference [StopMovie] [action(stopmovie)]
\definereference [StopSound] [action(stopsound)]
\definereference [StopRendering] [action(stoprendering)]
\definereference [SubmitForm] [action(submitform)]
\definereference [ToggleViewer] [action(toggle)]
\definereference [ViewerHelp] [action(help)]
\definereference [HideField] [action(hide)]
\definereference [ShowField] [action(show)]
\definereference [GotoPage] [action(gotopage)]
\definereference [Query] [action(query)]
\definereference [QueryAgain] [action(queryagain)]
\definereference [FitWidth] [action(fitwidth)]
\definereference [FitHeight] [action(fitheight)]
\definereference [ShowThumbs] [action(thumbnails)]
\definereference [ShowBookmarks] [action(bookmarks)]
\definereference [HideLayer] [action(hidelayer)]
\definereference [VideLayer] [action(videlayer)]
\definereference [ToggleLayer] [action(togglelayer)]
\stoptyping
In the \type {java-imp-*.mkiv} files you will find examples of similar shortcuts,
for instance:
\starttyping
\definereference [SetupStepper] [JS(SetupStepper{step,50})]
\definereference [ResetStepper] [JS(ResetStepper)]
\definereference [CheckStepper] [JS(CheckStepper{\StepCounter})]
\definereference [InvokeStepper] [JS(InvokeStepper)]
\stoptyping
Other examples of redefined references are:
\starttyping
\definereference [firstpage] [page(firstpage)]
\definereference [previouspage] [page(previouspage)]
\definereference [nextpage] [page(nextpage)]
\definereference [lastpage] [page(lastpage)]
\definereference [forward] [page(forward)]
\definereference [backward] [page(backward)]
\definereference [firstsubpage] [page(firstsubpage)]
\definereference [previoussubpage] [page(previoussubpage)]
\definereference [nextsubpage] [page(nextsubpage)]
\definereference [lastsubpage] [page(lastsubpage)]
\stoptyping
Some of these actions expect arguments, for instance:
\starttyping
\goto{start}[StartMovie{mymovie}]
\stoptyping
You can load the module \type {references-identify} which gives you
a command:
\startbuffer
\showreference[page(123),StartMovie{mymovie}]
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\showreference[JS(Forget_Changes),CloseDocument]
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\showreference[manual::contents]
\stopbuffer
\typebuffer \getbuffer
You should be careful with colons in references. This gives you an idea how
\CONTEXT\ interprets what you requested.
\starttabulate[|T|p|]
\NC prefix:whatever \NC The \type {prefix} creates a namespace. When references are
resolved and there is no hit a lookup without prefix
takes place. \NC \NR
\NC document::whatever \NC The \type {document} is a symbolic reference to an external
resource. This is explained elsewhere. \NC \NR
\NC component:::whatever \NC The \type {component} is a symbolic reference to a component in
a product. References defined in such a component are loaded on
demand. \NC \NR
\stoptabulate
% url(http://a,b.c)
% url(http://a,b.c)
% url(http://a.b.c)
\stopchapter
\stopcomponent
|
