Source Browser ?

1%D \module
2%D   [       file=strc-ref,
3%D        version=2008.10.20,
4%D          title=\CONTEXT\ Structure Macros,
5%D       subtitle=Cross Referencing,
6%D         author=Hans Hagen,
7%D           date=\currentdate,
8%D      copyright={PRAGMA ADE \& \CONTEXT\ Development Team}]
9%C
10%C This module is part of the \CONTEXT\ macro||package and is
11%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
12%C details.
13
14% todo: (1) configure references, (2) rendering => with presets
15%
16% \defineconversionset[default][Character,number,Romannumerals,Character][number]
17% \defineseparatorset [default][.,.,--][.]
18% \setuphead[subsection][sectionstopper=),sectionsegments=4:4]
19% \setupreferencestructureprefix[default][prefixsegments=2:4]
20% \setupreferencestructureprefix[figure][default][prefixsegments=3:4]
21% \chapter {One}
22% \section {One}
23% \subsection[sec:test]{Two}
24% See \in[sec:test] and \in[fig:xx] and \in[fig:yy]
25% \placefigure[here][fig:xx]{}{}
26% \placefigure[here][fig:yy]{}{}
27
28\writestatus{loading}{ConTeXt Structure Macros / Cross Referencing}
29
30\registerctxluafile{strc-rsc}{}
31\registerctxluafile{strc-ref}{}
32\registerctxluafile{node-ref}{optimize}
33
34\unprotect
35
36% todo : unknown/illegal reference no arg
37% todo : +n pages check on 'samepage' (contrastcolor)
38% todo : multiple text in reference
39
40% Makes more sense to build action data first, especially now
41% openaction etc are supported.
42%
43% \definespecial\doexecuteactionchain w h
44% \definespecial\dosetgotolocation
45% \definespecial\dosetexecuteJScode
46% ...
47
48%D This module deals with referencing. In \CONTEXT\ referencing is one of the core
49%D features, although at a first glance probably nobody will notice. This is good,
50%D because referencing should be as hidden as possible.
51%D
52%D Before we start implementing functionality we provide a way to set up this
53%D mechanism.
54%D
55%D \showsetup{setupreferencing}
56%D
57%D In interactive documents verbose references don't always make sense (what is a
58%D page number in an unnumbered document). By setting the \type{interaction}
59%D variable, one can influences the way interactive references are set.
60
61\let\referenceprefix\empty
62
63\installcorenamespace{referencing}
64
65\installdirectcommandhandler \??referencing {referencing} % \??referencing
66
67\newif\ifreferencing \referencingtrue
68
69\appendtoks
70    \edef\p_state{\referencingparameter\c!state}%
71    \ifx\p_state\v!start
72      \referencingtrue
73    \else
74      \referencingfalse
75    \fi
76\to \everysetupreferencing
77
78%D In paper documents, referencing comes down to cross referencing, but in
79%D their interactive counterparts, is also involves navigation. Many features
80%D implemented here are therefore closely related to navigation.
81%D
82%D Many \CONTEXT\ commands can optionally be fed with a reference. Such a
83%D reference, when called upon, returns the number of a figure, table, chapter
84%D etc, a piece of text, or a pagenumber.
85%D
86%D There are three ways of defining a reference:
87%D
88%D \starttyping
89%D \pagereference[here]
90%D \textreference[here]{some text}
91%D \stoptyping
92%D
93%D the third alternative combines them in:
94%D
95%D \starttyping
96%D \reference[here]{some text}
97%D \stoptyping
98
99\unexpanded\def\textreference {\dosingleargument\strc_references_text_reference} % no need for \dosingle
100\unexpanded\def\pagereference {\dosingleargument\strc_references_page_reference} % as they're mandate and
101\unexpanded\def\reference     {\dosingleargument\strc_references_full_reference} % never forgotten
102\unexpanded\def\setreference  {\dodoubleargument\strc_references_set_reference } %
103
104% maybe: \let\reference\textreference
105
106\unexpanded\def\showreferences
107  {\enabletrackers[nodes.references.show,nodes.destinations.show]}
108
109%D These are implemented in a low level form as:
110
111\unexpanded\def\strc_references_text_reference          [#labels]{\strc_references_set_named_reference\s!text{#labels}{}}
112\unexpanded\def\strc_references_page_reference          [#labels]{\strc_references_set_named_reference\s!page{#labels}{}{}}
113\unexpanded\def\strc_references_full_reference          [#labels]{\strc_references_set_named_reference\s!full{#labels}{}}
114\unexpanded\def\strc_references_set_reference[#labels][#settings]{\strc_references_set_named_reference\s!user{#labels}{#settings}{}}
115
116\unexpanded\def\dosetdirectpagereference#1{\strc_references_set_named_reference\s!page{#1}{}{}} % low level, maybe use _
117
118\unexpanded\def\usereferenceparameter#1% faster local variant
119  {\edef\m_strc_references_asked{#1\c!reference}%
120   \ifx\m_strc_references_asked\empty\else
121     \dosetdirectpagereference\m_strc_references_asked
122   \fi}
123
124%D Actually there is not much difference between a text and a full reference, but
125%D it's the concept that counts. The low level implementation is:
126
127\newcount\lastreferenceattribute
128\newcount\lastdestinationattribute
129
130\def\strc_references_finish#prefix#reference#internal%
131  {\normalexpanded{\clf_deferredenhancereference{#prefix}{#reference}}}
132
133\let\dofinishreference\strc_references_finish % used at lua end
134
135%D This is somewhat tricky: we want to keep the reference with the following word but
136%D that word should also hyphenate. We need to find a better way.
137
138% 0 = nothing
139% 1 = bind to following word
140
141\setnewconstant\c_strc_references_bind_state\plusone
142
143\def\strc_references_inject_before
144  {}
145
146\def\strc_references_inject_after
147  {\ifcase\c_strc_references_bind_state
148     % nothing
149   \or
150     \prewordbreak % to be tested: \removeunwantedspaces\permithyphenation
151   \fi}
152
153
154\unexpanded\def\strc_references_set_named_reference
155  {\ifreferencing
156      \expandafter\strc_references_set_named_reference_indeed
157   \else
158      \expandafter\gobblefourarguments
159   \fi}
160
161\newbox\b_strc_destination_nodes
162
163\unexpanded\def\strc_references_flush_destination_nodes
164  {\ifvoid\b_strc_destination_nodes \else
165     \unhbox\b_strc_destination_nodes
166   \fi}
167
168\def\strc_references_placeholder
169  {\ifx\dotaggedplaceholder\empty\else
170     \c_attr_destination\lastdestinationattribute
171     \dotaggedplaceholder
172   \fi}
173
174\unexpanded\def\strc_references_destination_point_yes
175  {\strc_references_inject_before % new
176   \dostarttagged\t!reference\empty
177   \dontleavehmode\hbox attr \destinationattribute\lastdestinationattribute\bgroup
178     \strc_references_flush_destination_nodes
179     \strc_references_placeholder
180     \egroup
181   \dostoptagged
182   \strc_references_inject_after}
183
184\unexpanded\def\strc_references_destination_point_nop
185  {\strc_references_inject_before % new
186   \dostarttagged\t!reference\empty
187   \dontleavehmode\hbox \bgroup
188     \strc_references_flush_destination_nodes
189     \strc_references_placeholder
190   \egroup
191   \dostoptagged
192   \strc_references_inject_after}
193
194\unexpanded\def\strc_references_start_destination_nodes % messy but we need the delay
195  {\setbox\b_strc_destination_nodes\hbox\bgroup}        % also sets lastdestinationattribute
196
197\unexpanded\def\strc_references_stop_destination_nodes
198  {\normalexpanded{\egroup\lastdestinationattribute\the\lastdestinationattribute\relax}}
199
200\unexpanded\def\strc_references_set_named_reference_indeed#kind#labels#userdata#text% labels userdata text -> todo: userdata
201  {\ifreferencing
202     % we could have a more efficient one for page references but for the moment
203     % we don't care too much
204     \edef\currentreferencekind     {#kind}%
205     \edef\currentreferencelabels   {#labels}%
206     \edef\currentreferenceuserdata {#userdata}%
207     \edef\currentreferenceexpansion{\referencingparameter\c!expansion}% {\referenceparameter\c!expansion}
208     \ifx\currentreferencelabels\empty
209       \lastdestinationattribute\attributeunsetvalue
210     \else
211       \ifx\currentreferenceexpansion\s!xml
212         \xmlstartraw
213           \xdef\currentreferencedata{#text}% data, no text else conflict
214         \xmlstopraw
215         \glet\currentreferencecoding\s!xml
216       \else
217         \ifx\currentreferenceexpansion\v!yes
218           \xdef\currentreferencedata{#text}%
219         \else
220           \xdef\currentreferencedata{\detokenize{#text}}%
221         \fi
222         \glet\currentreferencecoding\s!tex
223       \fi
224       % beware, the structures.references.set writes a
225       \setnextinternalreference
226       \strc_references_start_destination_nodes
227       \clf_setdestinationattribute
228            {%
229                references {%
230                    internal  \locationcount
231                  % block     {\currentsectionblock}%
232                    view      {\interactionparameter\c!focus}%
233                \ifx\referenceprefix\empty\else
234                    prefix    {\referenceprefix}%
235                \fi
236                    reference {\currentreferencelabels}%
237                }%
238                metadata {%
239                    kind     {\currentreferencekind}%
240            \ifx\currentreferencekind\s!page\else
241                \ifx\currentreferencecoding\s!xml
242                    xmlroot  {\xmldocument}%
243                \fi
244                    catcodes \catcodetable
245            \fi
246                }%
247            \ifx\currentreferencedata\empty\else
248                entries {%
249                    text {\currentreferencedata}%
250                }%
251            \fi
252            \ifx\currentreferenceuserdata\empty\else
253                userdata {\detokenize{#userdata}}%
254            \fi
255            }%
256       \relax
257       \strc_references_stop_destination_nodes
258     \fi
259   \else
260     \setbox\b_strc_destination_nodes\emptyhbox
261     \lastdestinationattribute\attributeunsetvalue
262   \fi
263   % will become obsolete:
264   \xdef\currentdestinationattribute{\number\lastdestinationattribute}%
265   % will become an option:
266   \ifnum\lastdestinationattribute>\zerocount
267     \strc_references_destination_point_yes
268   \else\ifvoid\b_strc_destination_nodes\else
269     \strc_references_destination_point_nop
270   \fi\fi}
271
272\def\strc_references_set_page_only_destination_attribute#labels% could in fact be fully expandable
273  {\ifreferencing
274     \edef\currentreferencelabels{#labels}%
275     \ifx\currentreferencelabels\empty
276       \setbox\b_strc_destination_nodes\emptyhbox
277       \lastdestinationattribute\attributeunsetvalue
278     \else
279       \strc_references_start_destination_nodes
280       \setnextinternalreference
281       \clf_setdestinationattribute
282            {%
283                references {%
284                    internal  \locationcount
285                 %  block     {\currentsectionblock}%
286                    view      {\interactionparameter\c!focus}%
287                \ifx\referenceprefix\empty\else
288                    prefix    {\referenceprefix}%
289                \fi
290                    reference {\currentreferencelabels}%
291                }%
292                metadata {%
293                    kind {page}%
294                }%
295            }%
296       \relax
297       \strc_references_stop_destination_nodes
298     \fi
299   \else
300     \setbox\b_strc_destination_nodes\emptyhbox
301     \lastdestinationattribute\attributeunsetvalue
302   \fi}
303
304\unexpanded\def\strc_references_direct_full_user#user#labels#text%
305  {\ifreferencing
306     \strc_references_start_destination_nodes
307     \setnextinternalreference
308     \edef\m_strc_references_user{#user}%
309     \edef\m_strc_references_text{#text}%
310     \clf_setdestinationattribute
311        {%
312            references {%
313                internal  \locationcount
314              % block     {\currentsectionblock}%
315                view      {\interactionparameter\c!focus}%
316            \ifx\referenceprefix\empty\else
317                prefix    {\referenceprefix}%
318            \fi
319                reference {#labels}%
320            }%
321            metadata {%
322                kind {\s!full}%
323            }%
324        \ifx\m_strc_references_text\empty \else
325            entries {%
326                text {\m_strc_references_text}%
327            }%
328        \fi
329        \ifx\m_strc_references_user\empty \else
330            userdata {\m_strc_references_user}% \detokenize\expandafter{\normalexpanded{...}}
331        \fi
332        }%
333     \relax
334     \strc_references_stop_destination_nodes
335   \else
336     \setbox\b_strc_destination_nodes\emptyhbox
337     \lastdestinationattribute\attributeunsetvalue
338   \fi
339   % will become obsolete:
340   \xdef\currentdestinationattribute{\number\lastdestinationattribute}%
341   % will become an option:
342   \ifnum\lastdestinationattribute>\zerocount
343     \strc_references_destination_point_yes
344   \else\ifvoid\b_strc_destination_nodes\else
345     \strc_references_destination_point_nop
346   \fi\fi}
347
348\unexpanded\def\strc_references_direct_full
349  {\strc_references_direct_full_user\empty}
350
351\let\dodirectfullreference\strc_references_direct_full % for at lua end (no longer)
352
353\def\strc_references_set_page_only_destination_box_attribute#cs#labels%
354  {\strc_references_set_page_only_destination_attribute{#labels}%
355   \ifnum\lastdestinationattribute>\zerocount
356     \edef#cs{attr \destinationattribute\number\lastdestinationattribute}%
357   \else
358     \let#cs\empty
359   \fi}
360
361%D It's about time to clean up references .. stable enough now.
362
363\unexpanded\def\boxreference[#1]%
364  {\begingroup
365   \dowithnextbox
366    {\strc_references_set_page_only_destination_attribute{#1}%
367     \hpack % \hbox
368       \ifnum\lastdestinationattribute=\attributeunsetvalue\else attr \destinationattribute \lastdestinationattribute \fi
369       {\box\b_strc_destination_nodes\box\nextbox}%
370     \endgroup}}
371
372\unexpanded\def\hboxreference[#1]{\boxreference[#1]\hbox}
373\unexpanded\def\vboxreference[#1]{\boxreference[#1]\vbox}
374
375% \ifx\currentdestinationattribute\empty
376%   \begingroup\c_attr_destination\currentdestinationattribute\emptyhbox\endgroup % todo
377% \fi
378
379\def\defaultreferencepage#text{[[[#text]]]}
380\def\defaultreferencetext#text{[[[#text]]]}
381
382%D For internal usage:
383
384\def\strc_references_set_simple_reference#label%
385  {\iflocation
386     \strc_references_start_destination_nodes
387     \setnextinternalreference
388     \clf_setdestinationattribute
389        {%
390            references {%
391                view      {\interactionparameter\c!focus}%
392            \ifx\referenceprefix\empty\else
393                prefix    {\referenceprefix}%
394            \fi
395                reference {#label}%
396                internal  \locationcount
397            }%
398            metadata {%
399                kind {\s!page}%
400            }%
401        }%
402     \relax
403     \strc_references_stop_destination_nodes
404     \xdef\currentdestinationattribute{\number\lastdestinationattribute}%
405   \else
406     \setbox\b_strc_destination_nodes\emptyhbox
407     \xdef\currentdestinationattribute{\number\attributeunsetvalue}%
408   \fi}
409
410\def\strc_references_set_simple_internal_reference#label% no prefix
411  {\iflocation
412     \strc_references_start_destination_nodes
413     \setnextinternalreference
414     \clf_setdestinationattribute
415        {%
416            references {%
417                view      {\interactionparameter\c!focus}%
418                reference {#label}%
419                internal  \locationcount
420            }%
421            metadata {%
422                kind {\s!page}%
423            }%
424        }%
425     \relax
426     \strc_references_stop_destination_nodes
427     \xdef\currentdestinationattribute{\number\lastdestinationattribute}%
428   \else
429     \setbox\b_strc_destination_nodes\emptyhbox
430     \xdef\currentdestinationattribute{\number\attributeunsetvalue}%
431   \fi}
432
433\def\strc_references_get_simple_reference#label%
434  {\iflocation
435     \clf_injectreference
436        {\referenceprefix}%
437        {#label}%
438        {%
439            height \ht\strutbox
440            depth  \dp\strutbox
441            \extrareferencearguments
442        }%
443     \relax
444     \xdef\currentreferenceattribute{\number\lastreferenceattribute}%
445   \else
446     \xdef\currentreferenceattribute{\number\attributeunsetvalue}%
447   \fi}
448
449%D \macros
450%D   {contentreference}
451%D
452%D \starttyping
453%D \setupinteraction
454%D   [state=start,
455%D    focus=standard]
456%D
457%D \setupheader
458%D   [state=stop]
459%D
460%D  See page \goto{page 2}[page2] \page
461%D
462%D  \contentreference
463%D    [page2]
464%D    [offset=1cm,toffset=2cm,frame=on]
465%D    {\externalfigure[cow.pdf][factor=fit]}
466%D
467%D \stoptyping
468
469\unexpanded\def\contentreference
470  {\hbox\bgroup
471   \dodoubleempty\strc_references_content_pickup}
472
473\def\strc_references_content_pickup
474  {\ifsecondargument
475     \expandafter\strc_references_content_pickup_yes
476   \else
477     \expandafter\strc_references_content_pickup_nop
478   \fi}
479
480\def\strc_references_content_pickup_yes[#1][#2]%
481 {\dowithnextbox{\strc_references_content_yes_finish{#1}{#2}}\hbox}
482
483\def\strc_references_content_pickup_nop[#1][#2]%
484 {\dowithnextbox{\strc_references_content_nop_finish{#1}{#2}}\hbox}
485
486\def\strc_references_content_yes_finish#1#2%
487  {\scratchwidth \wd\nextbox
488   \scratchheight\ht\nextbox
489   \scratchdepth \dp\nextbox
490   \setbox\nextbox\hpack
491     {\framed[\c!frame=\v!off,#2]{\box\nextbox}}%
492   \strc_references_set_simple_reference{#1}%
493   \setbox\nextbox\hpack attr \destinationattribute \currentdestinationattribute % \hpack ?
494     {\strc_references_flush_destination_nodes
495      \box\nextbox}%
496   \setbox\nextbox\hpack{\box\nextbox}%
497   \wd\nextbox\scratchwidth
498   \ht\nextbox\scratchheight
499   \dp\nextbox\scratchdepth
500   \box\nextbox
501   \egroup}
502
503\def\strc_references_content_nop_finish#1#2%
504  {\strc_references_set_simple_reference{#1}%
505   \hpack attr \destinationattribute \currentdestinationattribute % \hpack ?
506     {\strc_references_flush_destination_nodes
507      \box\nextbox}%
508   \egroup}
509
510%D \macros
511%D   {everyreference}
512%D
513%D For rather tricky purposes, one can assign sanitizing macros to \type
514%D {\everyreference} (no longer that relevant).
515
516\newevery \everyreference \relax
517
518%D This is really needed, since for instance Polish has a different alphabet and
519%D needs accented entries in registers.
520
521\appendtoks
522    \cleanupfeatures
523\to \everyreference
524
525%D We did not yet discuss prefixing. Especially in interactive documents, it's not
526%D always easy to keep track of duplicate references. The prefix mechanism, which we
527%D will describe later on, solves this problem. By (automatically) adding a prefix
528%D one keeps references local, but the global ones in view. To enable this feature,
529%D we explictly split the prefix from the reference.
530
531\let\referenceprefix\empty
532
533%D For a long time the only way to access an external file was to use the file
534%D prefix (\type {somefile::}. However, when you split up a document, redefining the
535%D references may be such a pain, that another approach is feasible. By setting the
536%D \type {autofile} variable to \type {yes} or \type {page}, you can access the
537%D reference directly.
538%D
539%D \starttabulate[||||]
540%D \NC filename::tag \NC page(filename::pnum) \NC tag     \NC\NR
541%D \NC   $\star$     \NC                      \NC         \NC\NR
542%D \NC   $\star$     \NC $\star$              \NC $\star$ \NC\NR
543%D \NC               \NC $\star$              \NC         \NC\NR
544%D \stoptabulate
545
546\unexpanded\def\usereferences[#filename]{} % obsolete
547
548%D As mentioned we will also use the cross reference mechanism for navigational
549%D purposes. The main reason for this is that we want to treat both categories
550%D alike:
551%D
552%D \starttyping
553%D \goto{go back}[PreviousJump]
554%D \goto{colofon}[colofon page]
555%D \stoptyping
556%D
557%D Here \type{PreviousJump} is handled by the viewer, while the
558%D \type{colofon page} reference is, apart from hyperlinking, a
559%D rather normal reference.
560%D
561%D We already saw that cross refences are written to and read from a file. The pure
562%D navigational ones don't need to be written to file, but both for fast processing
563%D and transparant integration, they are saved internally as a sort of reference. We
564%D can easily distinguish such system references from real cross reference ones by
565%D their tag.
566%D
567%D We also use the odd/even characteristic to determine the page state.
568
569\let\currentrealreference      \empty
570\let\currentpagereference      \empty
571\let\currenttextreference      \empty
572\let\currentreferenceorder     \empty
573\let\currentsubtextreference   \empty
574\let\currentsubsubtextreference\empty
575
576\newcount\referencehastexstate % set in backend
577
578% referencepagestate:
579%
580% 0 = no page ref, 1=same page, 2=before, 3=after
581
582%D Cross references appear as numbers (figure~1.1, chapter~2) or pagenumbers
583%D (page~2, page 3--2), and are called with \type {\in} and \type {\at}. In
584%D interactive documents we also have \type {\goto}, \type {\button} and alike.
585%D These are more versatile and look like:
586%D
587%D \starttyping
588%D \goto[reference]
589%D \goto[outer reference::]
590%D \goto[outer reference::inner reference]
591%D \goto[operation(argument)]
592%D \goto[operation(action{argument,argument})]
593%D \goto[action]
594%D \goto[action{argument}]
595%D \stoptyping
596%D
597%D The first one is a normal reference, the second and third are references to a
598%D file or \URL. The brace delimited references for instance refer to a \JAVASCRIPT.
599%D The last example shows that we can pass arguments to the actions.
600%D
601%D Now we've come to the testing step. As we can see below, this macro does bit more
602%D than testing: it also resolves the reference. This means that whenever we test
603%D for the existance of a reference at an outer level, we have all the relevant
604%D properties of that reference avaliable inside the true branche~(\type {#2}).
605%D
606%D The prefix has to do with localizing references. When a prefix is set, looking
607%D for a reference comes to looking for the prefixed one, and when not found,
608%D looking for the non prefixed one. Consider for instance the prefix set to \type
609%D {sidetrack}.
610%D
611%D \starttyping
612%D \pagereference[important]
613%D \pagereference[unimportant]
614%D \setupreferencing[prefix=sidetrack]
615%D \pagereference[important]
616%D \stoptyping
617%D
618%D results in saving (writing) the references
619%D
620%D \starttyping
621%D ...{}{important}
622%D ...{}{unimportant}
623%D ...{sidetrack}{important}...
624%D \stoptyping
625%D
626%D Now when we call for \type{unimportant}, we will indeed get the pagenumber
627%D associated to this reference. But when we call for \type{important}, while the
628%D prefix is still set, we will get the pagenumber bound to the prefixed one.
629%D
630%D {\em Some day, when processing time and memory are no longer
631%D performance factors, we will introduce multi||level
632%D prefixes.}
633%D
634%D Before we start analyzing, I introduce a general definition macro. Consider:
635%D
636%D \starttyping
637%D \goto{do}[JS(My_Script{"test",123}),titlepage]
638%D \stoptyping
639%D
640%D This can also be achieved by:
641%D
642%D \starttyping
643%D \definereference[startup][JS(My_Script{"test",123}),titlepage]
644%D \goto{do}[startup]
645%D \stoptyping
646%D
647%D Now is this is a handy feature or not?
648%D
649%D \showsetup{definereference}
650%D
651%D We can trace references by setting the next switch to true.
652
653\unexpanded\def\definereference
654  {\dodoubleempty\strc_references_define_reference}
655
656\def\strc_references_define_reference[#name][#specification]%
657  {\clf_definereference{\referenceprefix}{#name}{\detokenize{#specification}}}
658
659\unexpanded\def\resetreference[#name]%
660  {\clf_resetreference{\referenceprefix}{#name}}
661
662\def\setpagereference#name#specification% hm,. low level ?
663  {\clf_definereference{}{#name}{\v!page(\detokenize{#specification}}} % is detokenize needed here?
664
665%D Chained references are defined as:
666%D
667%D \starttyping
668%D \goto{somewhere}[JS(somescript),nextpage,JS(anotherscript)]
669%D \stoptyping
670%D
671%D Actually supporting chains is up to the special driver. Here we only provide the
672%D hooks.
673
674%D \macros
675%D   {highlighthyperlinks}
676%D
677%D The next switch can be used to make user hyperlinks are not highlighted when
678%D clicked on.
679
680\newconditional\highlighthyperlinks \settrue\highlighthyperlinks
681
682%D \macros
683%D   {gotonewwindow}
684%D
685%D To make the {\em goto previous jump} feature more convenient when using more than
686%D one file, it makes sense to force the viewer to open a new window for each file
687%D opened.
688
689\newconditional\gotonewwindow \setfalse\gotonewwindow
690
691\def\expandtexincurrentreference % will happen in lua some time
692  {\ifcase\referencehastexstate\else\clf_expandcurrentreference\fi}
693
694\def\expandreferenceoperation#tag#content{\clf_setreferenceoperation#tag{#content}}
695\def\expandreferencearguments#tag#content{\clf_setreferencearguments#tag{#content}}
696
697\def\doifelsereferencefound#label#yes#nop%
698  {\clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
699     {\expandtexincurrentreference
700      #yes}%
701     {#nop}}
702
703\let\doifreferencefoundelse \doifelsereferencefound
704
705%D The tester only splits the reference in components but does not look into them.
706%D The following macro does a preroll and determines for instance the current real
707%D reference pagenumber. The \type {\currentrealreference} macro does the same so
708%D unless one wants to use the pagestate the next macro seldom needs to be called.
709%D
710%D The inner case is simple. Only two cases have to be taken
711%D care of:
712%D
713%D \starttyping
714%D \goto{some text}[reference]
715%D \goto{some text}[prefix:reference]
716%D \stoptyping
717%D
718%D References to other files however are treated strict or tolerant, depending on
719%D their loading and availability:
720%D
721%D \starttyping
722%D \useexternaldocument[somefile][filename][a nice description]
723%D
724%D \goto{checked   reference}[somefile::reference]
725%D \goto{unchecked reference}[somefile::]
726%D \goto{unchecked reference}[anotherfile::reference]
727%D \stoptyping
728%D
729%D An unknown reference is reported on the screen, in the log file and, when
730%D enabled, in the left margin of the text.
731
732\let\unknownreference\gobbleoneargument
733
734%D When a reference is not found, we typeset a placeholder (two glyphs are often
735%D enough to represent the reference text).
736
737\def\dummyreference{{\tttf ??}}
738\def\emptyreference{{\tttf !!}}
739
740\installtextracker
741  {structures.referencing.show}
742  {\let\strc_references_dummy\strc_references_dummy_yes}
743  {\let\strc_references_dummy\strc_references_dummy_nop}
744
745\def\strc_references_dummy_nop
746  {\dummyreference}
747
748\def\strc_references_dummy_yes
749  {\dummyreference
750   \margindata
751     [\referencingparameter\c!labelalternative]% alternative?
752     [\c!style=\referencingparameter\c!labelstyle,
753      \c!color=\referencingparameter\c!labelcolor]
754     {\askedreference}}
755
756\let\strc_references_dummy\strc_references_dummy_nop
757
758\setupreferencing
759  [\c!labelalternative=\v!inleft,
760         \c!labelcolor=darkred,
761         \c!labelstyle=\smallinfofont]
762
763%D To prevent repetitive messages concerning a reference being defined, we set such
764%D an unknown reference to an empty one after the first encounter.
765%D
766%D Apart from cross references supplied by the user, \CONTEXT\ generates cross
767%D references itself. Most of them are not saved as a reference, but stored with
768%D their source, for instance a list or an index entry. Such automatically
769%D generated, for the user invisible, references are called {\em internal
770%D references}. The user supplied ones are labeled as {\em external references}.
771%D
772%D A second important characteristic is that when we want to support different
773%D backends (viewers), we need to support named destinations as well as page
774%D numbers. I invite readers to take a glance at the special driver modules to
775%D understand the fine points of this. As a result we will deal with {\em locations}
776%D as well as {\em real page numbers}. We explictly call this pagenumber a real one,
777%D because it is independant of the page numbering scheme used in the document.
778%D
779%D One of the reasons for \CONTEXT\ being the first \TEX\ base macropackage to
780%D support sophisticated interactive \PDF\ files, lays in the mere fact that real
781%D page numbers are available in most two pass data, like references, list data and
782%D index entries.
783%D
784%D We will speak of \type {thisis...} when we are marking a location, and
785%D \type {goto...} when we point to such a location. The latter one can be seen as a
786%D hyperlink to the former one. In the next macros one we use constructs like:
787%D
788%D \starttyping
789%D \dostart...
790%D \dostop...
791%D \stoptyping
792%D
793%D The flag \type {\iflocation} signals if we're in interactive mode.
794
795\ifdefined\buttonheight \else \newdimen\buttonheight \fi
796\ifdefined\buttonwidth  \else \newdimen\buttonwidth  \fi
797
798%D Internal references can best be set using the next few macros. Setting such
799%D references to unique values is completely up to the macros that call them.
800%D
801%D \starttyping
802%D \thisissomeinternal{tag}{identifier}
803%D \gotosomeinternal  {tag}{identifier}{pagenumber}{text}
804%D \stoptyping
805%D
806%D We could do this in \LUA\ \unknown
807
808\newif   \iflocation
809\newcount\locationcount
810\newcount\locationorder
811\newbox  \locationbox
812
813\def\nextinternalreference     {\the\locationcount}
814\def\nextinternalorderreference{\the\locationorder}
815
816\def\setnextinternalreference
817  {\global\advance\locationcount\plusone}
818
819\def\setnextinternalreferences#kind#name% plural
820  {\clf_setnextinternalreference{#kind}{#name}}
821
822\def\getinternalorderreference#kind#name%
823  {\clf_currentreferenceorder{#kind}{#name}}
824
825\def\thisissomeinternal#kind#name% only for old time sake, will go away
826  {\begingroup
827   \clf_setinternalreference
828     reference {#kind:#name}% no view
829   \relax
830   \hpack attr \destinationattribute\lastdestinationattribute{}%
831   \endgroup}
832
833\installcorenamespace{savedinternalreference}
834
835\letvalue{\??savedinternalreference\s!default}\!!zerocount
836
837\unexpanded\def\storeinternalreference#1#2%
838  {\setxvalue{\??savedinternalreference\currentstructurename}{\number#2}}
839
840\newconditional\preferpagereferences
841
842\def\gotosomeinternal#kind#name#target#text%
843  {\ifconditional\preferpagereferences
844     \directgoto{#text}[page(#target)]%
845   \else
846     \directgoto{#text}[#kind:#name]%
847   \fi}
848
849\def\gotonextinternal#text#target%
850  {\directgoto{#text}[internal(#target)]}
851
852%D In this module we define three system references: one for handling navigational,
853%D viewer specific, commands, another for jumping to special pages, like the first
854%D or last one, and a third reference for linking tree like lists, like tables of
855%D contents. The latter two adapt themselves to the current state.
856%D
857%D An example of an action is:
858%D
859%D \starttyping
860%D \goto{some action}[PreviousJump]
861%D \stoptyping
862%D
863%D as well as:
864%D
865%D \starttyping
866%D \goto{some text}[\v!action(PreviousJump]
867%D \stoptyping
868%D
869%D One can also activate an automatic prefix mechanism. By setting the
870%D \type {\prefix} variable to \type {+}, the prefix is incremented, when set to
871%D \type {-} or empty, the prefix is reset. Other values become the prefix.
872
873\newcount\prefixcounter
874
875\newconditional\autocrossfilereferences
876
877\appendtoks
878    \edef\p_autofile{\referencingparameter\c!autofile}%
879    \ifx\p_autofile\v!yes
880      \settrue \autocrossfilereferences
881    \else
882      \setfalse\autocrossfilereferences
883    \fi
884\to \everysetupreferencing
885
886\appendtoks
887    \edef\p_export{\referencingparameter\c!export}%
888    \ifx\p_export\v!yes
889      \clf_exportreferences
890    \fi
891\to \everygoodbye
892
893\unexpanded\def\setupglobalreferenceprefix[#prefix]%
894  {\xdef\referenceprefix{#prefix}}
895
896\unexpanded\def\globalpushreferenceprefix#prefix%
897  {\xdef\referenceprefix{\clf_pushreferenceprefix{#prefix}}}
898
899\unexpanded\def\globalpopreferenceprefix
900  {\xdef\referenceprefix{\clf_popreferenceprefix}}
901
902\unexpanded\def\pushreferenceprefix#prefix%
903  {\edef\referenceprefix{\clf_pushreferenceprefix{#prefix}}}
904
905\unexpanded\def\popreferenceprefix
906  {\edef\referenceprefix{\clf_popreferenceprefix}}
907
908\def\m_strc_references_prefix_yes{+}
909\def\m_strc_references_prefix_nop{-}
910
911\unexpanded\def\setupreferenceprefix[#prefix]%
912  {\edef\p_prefix{#prefix}%
913   \ifx\p_prefix\empty
914     \let\referenceprefix\empty
915   \else\ifx\p_prefix\m_strc_references_prefix_yes
916     \letreferencingparameter\c!prefix\s!unknown
917     \global\advance\prefixcounter\plusone
918     \edef\referenceprefix{\the\prefixcounter}%
919   \else\ifx\p_prefix\m_strc_references_prefix_nop
920     \letreferencingparameter\c!prefix\s!unknown
921     \let\referenceprefix\empty
922   \else\ifx\p_prefix\s!unknown
923     % forget about it
924   \else
925     \let\referenceprefix\p_prefix
926   \fi\fi\fi\fi}
927
928\appendtoks
929    \setupreferenceprefix[\referencingparameter\c!prefix]
930\to \everysetupreferencing
931
932%D We can typeset a reference using \type {\in}, \type {\at} and \type {\about} and
933%D goto specific locations using \type {\goto}. The last one does not make that much
934%D sense in a paper document. To complicate things, \PLAIN\ \TEX\ also implements an
935%D \type {\in} but fortunately that one only makes sense in math mode.
936%D
937%D Typesetting the reference is a bit more complicated than one would at first sight
938%D expect. This is due to the fact that we distinguish three (five) alternative
939%D calls:
940%D
941%D \placefigure
942%D   [here][three calls]
943%D   {Three alternatives reference calls.}
944%D   {\startcombination[1*3]
945%D      {\framed{\type{ \in }}} {a}
946%D      {\framed{\type{ \at }}} {b}
947%D      {\framed{\type{\goto}}} {c}
948%D    \stopcombination}
949%D
950%D \startbuffer
951%D \in figure[fig:three calls]
952%D \in{figure}[fig:three calls]
953%D \in figure a[fig:three calls]
954%D \in{figure}{a}[fig:three calls]
955%D figure~\in[fig:three calls]
956%D \stopbuffer
957%D
958%D \typebuffer
959%D
960%D This turns up as:
961%D
962%D \startlines
963%D \getbuffer
964%D \stoplines
965%D
966%D The dual \type {{}} results in a split reference. In a document meant for paper,
967%D one is tempted to use the last (most straightforward) alternative. When a
968%D document is also meant voor electronic distribution, the former alternatives have
969%D preference, because everything between the \type {\in} and~\type {[} becomes
970%D active (and when asked for, typeset in a different color and typeface).
971
972\appendtoks
    \ifdefined\in    \let\normalmathin   \in    \unexpanded\def\in   {\mathortext\normalmathin   \strc_references_in   } \else \let\in   \strc_references_in    \fi
    \ifdefined\at    \let\normalmathat   \at    \unexpanded\def\at   {\mathortext\normalmathat   \strc_references_at   } \else \let\at   \strc_references_at    \fi
    \ifdefined\about \let\normalmathabout\about \unexpanded\def\about{\mathortext\normalmathabout\strc_references_about} \else \let\about\strc_references_about \fi
    \ifdefined\from  \let\normalmathfrom \from  \unexpanded\def\from {\mathortext\normalmathfrom \strc_references_from } \else \let\from \strc_references_from  \fi
    \ifdefined\over  \let\normalmathover \over  \unexpanded\def\over {\mathortext\normalmathover \strc_references_about} \else \let\over \strc_references_about \fi
978\to \everydump
979
980           \def\filterreference  #key{\clf_filterreference{#key}} % no checking, expanded
981\unexpanded\def\getreferenceentry#key{\clf_filterreference{#key}} % no checking, unexpanded
982
983\def\currentreferencenumber  {\clf_filterreference{number}}
984\def\currentreferencepage    {\clf_filterreference{page}}
985\def\currentreferencetitle   {\clf_filterreference{title}}
986\def\currentreferencetext    {\clf_filterreference{text}}
987\def\currentreferencedefault {\clf_filterreference{default}}
988\def\currentreferencerealpage{\clf_filterreference{realpage}}
989
990%D The most straightforward way of retrieving references is using \type {\ref}.
991
992\unexpanded\def\getreference % checking, unexpanded
993  {\dodoubleargument\strc_references_get_reference}
994
995\def\strc_references_get_reference[#key][#label]% #key = number page title text default realpage ...
996  {\ifsecondargument
997     \doifelsereferencefound{#label}{\clf_filterreference{#key}}\strc_references_dummy
998   \else
999     \strc_references_dummy
1000   \fi}
1001
1002\let\ref\getreference
1003
1004%D Special cases:
1005
1006\unexpanded\def\strc_references_about[#label]%
1007  {\dontleavehmode
1008   \begingroup
1009   \enforced\let\crlf\space
1010   \enforced\let\\\space
1011   \postponenotes % might go
1012   \referencingparameter\c!left
1013   \doifelsereferencefound{#label}
1014     {\goto{\limitatetext\currentreferencetitle{\referencingparameter\c!width}\unknown}[#label]}% not so efficient (dup lookup)
1015     {}% todo
1016   \flushnotes % might go
1017   \referencingparameter\c!right
1018   \endgroup}
1019
1020%D The previously discussed setup macro lets us specify the representation of
1021%D references. A symbol reference does not show the specific data, like the number
1022%D of a figure, but shows one of: \hbox {$^\goforwardcharacter$
1023%D $^\gobackwardcharacter$ $^\gonowherecharacter$}, depending on the direction to
1024%D go.
1025%D
1026%D \starttyping
1027%D ... \somewhere{backward text}{forward text}[someref] ...
1028%D ... \atpage[someref] ...
1029%D \stoptyping
1030
1031% standard      detail
1032%
1033% 0 = unknown   unknown
1034% 1 = same      on same page
1035% 2 = before    preceding page
1036% 3 = after     following page
1037%
1038% 4 = above     above on same page
1039% 5 = below     below on same page
1040
1041% todo: optimize for use in pagebody
1042% todo: maybe make it optional
1043
1044% \setuppagenumbering[alternative=doublesided]
1045% \setupreferencing  [doublesided=no] % yes is default
1046%
1047% \somewhere{backward}{foreward}[label]
1048% \someplace{preceding}{backward}{current}{foreward}{following}[label]
1049% \atpage[#label]
1050% \doifcheckedpagestate{label}{preceding}{backward}{current}{foreward}{following}{otherwise}
1051%
1052% \dorecurse {20} {
1053%     \placefigure[here][fig:#1]{}{\externalfigure[dummy]}
1054%     \dorecurse {20} {
1055%         ##1: \atpage[fig:##1] /
1056%         \doifcheckedpagestate
1057%             {fig:##1}
1058%             {preceding}{backward}{current}{foreward}{following}
1059%             {otherwise}
1060%     }
1061% }
1062
1063\newcount      \nofreferencestates
1064\newconditional\pagestatespread
1065
1066\appendtoks
1067    \doifelse{\referencingparameter\c!doublesided}\v!yes\settrue\setfalse\pagestatespread
1068\to \everysetupreferencing
1069
1070\setupreferencing
1071  [\c!doublesided=\v!yes]
1072
1073\def\referencepagestate
1074  {\numexpr\clf_referencepagestate
1075     {rst::\number\nofreferencestates}%
1076   \relax}
1077
1078\def\referencepagedetail
1079   {\numexpr\clf_referencepagedetail
1080      {rst::\number\nofreferencestates}%
1081      true %
1082      \ifconditional\pagestatespread false\ifdoublesided true\else false\fi\fi
1083    \relax}
1084
1085\def\referencerealpage
1086  {\clf_referencerealpage}
1087
1088\def\referencecolumnnumber
1089  {\clf_referencecolumn}
1090
1091% So we need : instead of \ but that's only lmtx:
1092%
1093% \def\referencecolumnnumber
1094%   {\numexpr\dimexpr\clf_referenceposx-\cutspace\relax:\dimexpr\makeupwidth/\nofcolumns\relax+\plusone\relax}
1095%
1096% Tacos patch of the older one, kept here as illustration
1097%
1098% \def\referencecolumnnumber
1099%   {\numexpr
1100%       \dimexpr\clf_referenceposx-\cutspace-\makeupwidth/(2*\nofcolumns)\relax
1101%      /\dimexpr                             \makeupwidth/   \nofcolumns \relax
1102%      +\plusone
1103%    \relax}
1104
1105
1106\unexpanded\def\tracedpagestate
1107  {{\blue\tttf(\ifcase\referencepagedetail unknown\or same\or previous\or next\or above\or below\else unknown\fi)}}
1108
1109\unexpanded\def\markreferencepage
1110  {\dontleavehmode\begingroup
1111   \iftrialtypesetting
1112     % issue warning that not stable
1113   \else
1114     % needs checking ... but probably never in trialmode
1115     \global\advance\nofreferencestates\plusone
1116     \xypos{rst::\number\nofreferencestates}%
1117     % \tracedpagestate
1118   \fi
1119   \endgroup}
1120
1121\unexpanded\def\doifcheckedpagestate#label% #preceding#backward#current#foreward#following#otherwise%
1122  {\doifelsereferencefound{#label}\strc_references_handle_page_state_yes\strc_references_handle_page_state_nop}
1123
1124\let\strc_references_handle_page_state_nop\sixthofsixarguments
1125
1126\def\strc_references_handle_page_state_yes
1127  {\markreferencepage
1128   \ifcase\referencepagedetail\relax
1129     \expandafter\sixthofsixarguments \or
1130     \expandafter\thirdofsixarguments \or
1131     \expandafter\firstofsixarguments \or
1132     \expandafter\fifthofsixarguments \or
1133     \expandafter\secondofsixarguments\or
1134     \expandafter\fourthofsixarguments\else
1135     \expandafter\sixthofsixarguments \fi}
1136
1137\unexpanded\def\referencesymbol
1138  {\hpack\bgroup
1139     \strut
1140     \markreferencepage
1141     \high
1142       {\setupsymbolset[\interactionparameter\c!symbolset]%
1143        \symbol[\ifcase\referencepagedetail\v!somewhere\or\v!nowhere\or\v!previous\or\v!next\or\v!previous\or\v!next\else\v!somewhere\fi]}%
1144   \egroup}
1145
1146%D Hereafter the \type {\ignorespaces} binds the state node to next character (more likely
1147%D than a preceding one) and one can always add an explicit space.
1148
1149\unexpanded\def\somewhere#backward#foreward#dummy[#label]% #dummy gobbles space around #foreward
1150  {\doifcheckedpagestate{#label}%
1151     {\goto{#backward}[#label]}%
1152     {\goto{#backward}[#label]}%
1153     {\ignorespaces}%
1154     {\goto{#foreward}[#label]}%
1155     {\goto{#foreward}[#label]}%
1156     {#label}}%
1157
1158\unexpanded\def\someplace#preceding#backward#current#foreward#following#dummy[#label]% #dummy gobbles space around #foreward
1159  {\doifcheckedpagestate{#label}%
1160     {\doifelsenothing{#preceding}{\goto{#preceding}[#label]}\ignorespaces}%
1161     {\doifelsenothing {#backward}{\goto {#backward}[#label]}\ignorespaces}%
1162     {\doifelsenothing  {#current}{\goto  {#current}[#label]}\ignorespaces}%
1163     {\doifelsenothing {#foreward}{\goto {#foreward}[#label]}\ignorespaces}%
1164     {\doifelsenothing{#following}{\goto{#following}[#label]}\ignorespaces}%
1165     {#label}}
1166
1167\unexpanded\def\atpage[#label]% todo
1168  {\doifcheckedpagestate{#label}%
1169     {\goto{\labeltext\v!precedingpage}[#label]}%
1170     {\goto{\labeltext\v!hencefore}[#label]}%
1171     {\ignorespaces}%
1172     {\goto{\labeltext\v!hereafter}[#label]}%
1173     {\goto{\labeltext\v!followingpage}[#label]}%
1174     {\goto{\labeltexts\v!page\strc_references_dummy}[#label]}}
1175
1176% Someone requested this but in retrospect didn't need it so we keep it as example.
1177% Beware: a node is injected which is why we add ignorespaces!
1178%
1179% \unexpanded\def\strc_references_conditional#action#text[#condition]#dummy[#label]%
1180%   {\doifcheckedpagestate{#label}%
1181%      {\doifelse{#condition}\v!precedingpage{#action{#text}[#label]}\ignorespaces}%
1182%      {\doifelse{#condition}\v!hencefore    {#action{#text}[#label]}\ignorespaces}%
1183%      {\doifelse{#condition}\v!current      {#action{#text}[#label]}\ignorespaces}%
1184%      {\doifelse{#condition}\v!hereafter    {#action{#text}[#label]}\ignorespaces}%
1185%      {\doifelse{#condition}\v!followingpage{#action{#text}[#label]}\ignorespaces}%
1186%      {#label}}
1187%
1188% \unexpanded\def\conditionalat   {\strc_references_conditional\at}
1189% \unexpanded\def\conditionalin   {\strc_references_conditional\in}
1190% \unexpanded\def\conditionalabout{\strc_references_conditional\about}
1191
1192%D The other alternatives just conform their names: only the label, only the text, or the
1193%D label and the text.
1194
1195% \dounknownreference -> \dummyreference
1196
1197\def\symbolreference[#label]% for old times sake
1198  {\goto{\referencesymbol}[#label]}
1199
1200% \referencecontentmode 0=all 1=label 2=text 3=symbol
1201
1202\newtoks\leftreferencetoks
1203\newtoks\rightreferencetoks
1204\newtoks\defaultleftreferencetoks
1205\newtoks\defaultrightreferencetoks
1206
1207%def\leftofreferencecontent {\nobreakspace} % we cannot do \definereferenceformat[at] .. so we need this
1208\let\rightofreferencecontent \empty
1209\let\leftofreference         \empty
1210\let\rightofreference        \empty
1211
1212\unexpanded\def\leftofreferencecontent
1213  {\removeunwantedspaces
1214   \nonbreakablespace
1215   \ignorespaces}
1216
1217\installcorenamespace{referencinginteraction}
1218
1219\def\strc_references_interaction_all
1220  {\the\leftreferencetoks
1221   \doifelsesometoks\leftreferencetoks \leftofreferencecontent \donothing
1222   \leftofreference
1223   \doifelsesometoks\leftreferencetoks\onlynonbreakablespace\relax % new, replace space by nonbreakable if present
1224   \currentreferencecontent
1225   \rightofreference
1226   \doifelsesometoks\rightreferencetoks\rightofreferencecontent\donothing
1227   \the\rightreferencetoks}
1228
1229\letvalue{\??referencinginteraction\v!all}\strc_references_interaction_all
1230
1231\setvalue{\??referencinginteraction\v!label}%
1232  {\leftofreference
1233   \the\leftreferencetoks
1234   \the\rightreferencetoks
1235   \rightofreference}
1236
1237\setvalue{\??referencinginteraction\v!text}%
1238  {\leftofreference
1239   \currentreferencecontent
1240   \rightofreference}
1241
1242\setvalue{\??referencinginteraction\v!symbol}%
1243  {\referencesymbol}
1244
1245\def\referencesequence
1246  {\ifcsname\??referencinginteraction\referencingparameter\c!interaction\endcsname
1247     \expandafter\lastnamedcs
1248   \else
1249     \expandafter\strc_references_interaction_all
1250   \fi}
1251
1252\newtoks\everyresetinatreference
1253
1254\appendtoks
1255    \glet\leftofreference \relax
1256    \glet\rightofreference\relax
1257\to \everyresetinatreference
1258
1259\def\strc_references_start_goto
1260  {\dontleavehmode
1261   \begingroup}
1262
1263\def\strc_references_stop_goto
1264  {\the\everyresetinatreference
1265   \endgroup}
1266
1267\def\strc_references_pickup_goto
1268  {\dodoublegroupempty\strc_references_pickup_goto_indeed}
1269
1270\def\strc_references_pickup_goto_indeed#left#right#dummy[#label]% #dummy gobbles spaces (really needed)
1271  {\leftreferencetoks
1272     \iffirstargument
1273       {#left}%
1274     \else
1275       \defaultleftreferencetoks
1276       \let\leftofreferencecontent\empty
1277     \fi
1278   \rightreferencetoks
1279     \ifsecondargument
1280       {#right}%
1281     \else
1282       \defaultrightreferencetoks
1283       \let\rightofreferencecontent\empty
1284     \fi
1285   % inefficient: double resolve
1286   \doifelsereferencefound{#label} % we need to resolve the text
1287     {\goto{\referencesequence}[#label]}
1288     {\let\currentreferencecontent\strc_references_dummy
1289      \goto{\referencesequence}[#label]}%
1290   \strc_references_stop_goto}
1291
1292\unexpanded\def\strc_references_in
1293  {\strc_references_start_goto
1294   \let\currentreferencecontent\currentreferencedefault
1295   \strc_references_pickup_goto}
1296
1297\unexpanded\def\strc_references_at
1298  {\strc_references_start_goto
1299   \let\currentreferencecontent\currentreferencepage
1300   \strc_references_pickup_goto}
1301
1302%D \macros
1303%D   {definereferenceformat}
1304%D
1305%D The next few macros were made for for David Arnold and Taco Hoekwater. They can
1306%D be used for predefining reference texts, and thereby stimulate efficiency.
1307%D
1308%D \starttyping
1309%D \definereferenceformat[informula]  [left=(,right=),text=formula]
1310%D \definereferenceformat[informulas] [left=(,right=),text=formulas]
1311%D \definereferenceformat[andformula] [left=(,right=),text=and]
1312%D \definereferenceformat[andformulas][left=(,right=),text=and]
1313%D
1314%D \informula [b] and \informula [for:c]
1315%D the \informula {formulas}[b] \informula {and} [for:c]
1316%D the \informulas {formulas}[b] \informula {and} [for:c]
1317%D the \informulas [b] \informula {en} [for:c]
1318%D the \informulas [b] \andformula [for:c]
1319%D \stoptyping
1320%D
1321%D Instead of a text, one can specify a label, which should be defined with \type
1322%D {\setuplabeltext}.
1323%D
1324%D Watch out: the second argument is somewhat special and mostly meant for a suffix
1325%D to a number:
1326%D
1327%D \startbuffer
1328%D \definereferenceformat [intesta] [left=(,right=),text=Whatever~]
1329%D \definereferenceformat [intestb] [left=(,right=),label=figure]
1330%D
1331%D \placeformula[x]\startformula a \stopformula
1332%D
1333%D \starttabulate[|||||]
1334%D \NC \in     [x] \NC \in     {left}[x] \NC \in     {}{right}[x] \NC \in     {left}{right}[x] \NC \NR
1335%D \NC \intesta[x] \NC \intesta{left}[x] \NC \intesta{}{right}[x] \NC \intesta{left}{right}[x] \NC \NR
1336%D \NC \intestb[x] \NC \intestb{left}[x] \NC \intestb{}{right}[x] \NC \intestb{left}{right}[x] \NC \NR
1337%D \stoptabulate
1338%D \stopbuffer
1339%D
1340%D \typebuffer \getbuffer
1341
1342% to be done: interfaced
1343
1344\installcorenamespace{referenceformat}
1345
1346\installcommandhandler \??referenceformat {referenceformat} \??referenceformat
1347
1348\appendtoks
1349    \setuevalue\currentreferenceformat{\strc_references_apply_format{\currentreferenceformat}}%
1350\to \everydefinereferenceformat
1351
1352\setupreferenceformat
1353  [\c!left=,
1354   \c!right=,
1355   \c!text=,
1356   \c!label=,
1357   \c!autocase=\v!no,
1358   \c!style=,
1359   \c!type=default, % to be done: interfaced
1360   \c!setups=,
1361   \c!color=]
1362
1363\unexpanded\def\strc_references_apply_format#name%
1364  {\strc_references_start_goto
1365   \edef\currentreferenceformat{#name}%
1366   \gdef\leftofreference               {\referenceformatparameter\c!left    }%
1367   \gdef\rightofreference              {\referenceformatparameter\c!right   }%
1368   \edef\currentreferenceformatlabel   {\referenceformatparameter\c!label   }%
1369   \edef\currentreferenceformattype    {\referenceformatparameter\c!type    }%
1370   \edef\currentreferenceformatsetups  {\referenceformatparameter\c!setups  }%
1371   \edef\currentreferenceformatautocase{\referenceformatparameter\c!autocase}%
1372   \usereferenceformatstyleandcolor\c!style\c!color
1373   \ifx\currentstyleparameter\empty \else
1374     \resetinteractionparameter\c!style
1375   \fi
1376   \ifx\currentcolorparameter\empty \else
1377     \resetinteractionparameter\c!contrastcolor
1378     \resetinteractionparameter\c!color
1379   \fi
1380   \ifx\currentreferenceformatlabel\autoreferencelabeltextflag
1381      \def\currentreferenceformatlabel{\autoreferencelabeltext}%
1382   \fi
1383   \ifx\currentreferenceformatautocase\v!yes
1384     \setcharactercleaning[1]%
1385   \fi
1386   \ifx\currentreferenceformatlabel\empty
1387     \defaultleftreferencetoks {\referenceformatparameter\c!text}%
1388     \defaultrightreferencetoks\emptytoks
1389   \else
1390     \defaultleftreferencetoks {\leftlabeltext \currentreferenceformatlabel}%
1391     \defaultrightreferencetoks{\rightlabeltext\currentreferenceformatlabel}%
1392   \fi
1393   \ifx\currentreferenceformattype\empty
1394     \def\currentreferenceformattype{default}%
1395   \fi
1396   %
1397   \ifx\currentreferenceformatsetups\empty
1398     \def\currentreferencecontent{\filterreference\currentreferenceformattype}%
1399   \else
1400     \def\currentreferencecontent{\directsetup\currentreferenceformatsetups}%
1401   \fi
1402   %
1403   \let\leftofreferencecontent \empty
1404   \let\rightofreferencecontent\empty
1405   \strc_references_pickup_goto}
1406
1407\def\autoreferencelabeltextflag{*} % a proper key like 'auto' or 'name' can clash with a label key
1408
1409\def\autoreferencelabeltext
1410%   {\clf_getcurrentreferencemetadata{name}}
1411  {\clf_getcurrentreferencelabel}
1412
1413% \starttext
1414%     \definereferenceformat[inxx]  [left=(,right=),text=txt]
1415%     \setupinteraction[state=start]
1416%     \chapter[one]{xx}
1417%     [\goto{state}[file(mk-last-state)]]
1418%     [\goto{state} [file(mk-last-state)]]
1419%     [\at{page} [one]]
1420%     [\at{page}[one]]
1421%     [\at{page}{okay}[one]]
1422%     [\inxx{a}{b}[one]]
1423% \stoptext
1424
1425% \startsetups referenceformat:numberplustext
1426%     \filterreference{number}, \filterreference{title}
1427% \stopsetups
1428%
1429% \definereferenceformat[hellup][text=Hellup ,setups=referenceformat:numberplustext]
1430
1431%D In interactive documents going to a specific location is not bound to cross
1432%D references. The \type {\goto} commands can be used to let users access another
1433%D part of the document. In this respect, interactive tables of contents and
1434%D registers can be considered goto's. Because in fact a \type {\goto} is just a
1435%D reference without reference specific data, the previous macros are implemented
1436%D using the goto functionality.
1437%D
1438%D \showsetup{goto}
1439%D
1440%D One important characteristic is that the first argument of \type {\goto} (and
1441%D therefore \type {\at} and \type {\in} is split at spaces. This means that,
1442%D although hyphenation is prevented, long references can cross line endings.
1443
1444% \starttext
1445%     \setupinteraction[state=start]
1446%     [\goto{state}[file(mk-last-state)]]
1447%     [\goto{state} [file(mk-last-state)]]
1448% \stoptext
1449
1450\newconditional\uselocationstrut \settrue\uselocationstrut
1451
1452\def\extrareferencearguments
1453  {highlight \luaconditional\highlighthyperlinks\space
1454   newwindow \luaconditional\gotonewwindow\space
1455   layer     {\currentviewerlayer}}
1456
1457\unexpanded\def\directgoto
1458  {\ifconditional\uselocationstrut
1459     \expandafter\strc_references_direct_goto
1460   \else
1461     \expandafter\strc_references_direct_goto_htdp
1462   \fi}
1463
1464\unexpanded\def\goto
1465  {\ifconditional\uselocationstrut
1466     \expandafter\strc_references_goto
1467   \else
1468     \expandafter\strc_references_goto_htdp
1469   \fi}
1470
1471% The unbox trick is needed in order to permit \par inside a reference. Otherwise
1472% the reference attribute migrates to the outer boxes.
1473
1474\newcount\lastsavedreferenceattribute
1475
1476\newbox\referencebox
1477
1478\def\revivesavedreferenceattribute % sometimes handy as no test etc needed
1479  {\c_attr_reference\lastsavedreferenceattribute}
1480
1481\def\strc_references_direct_goto#content[#label]% no test for valid references
1482  {\dontleavehmode
1483   \begingroup
1484   \c_attr_reference\attributeunsetvalue
1485   \global\lastsavedreferenceattribute\attributeunsetvalue
1486   \iflocation
1487     \clf_injectreference
1488        {\referenceprefix}%
1489        {#label}%
1490        {%
1491            height \ht\strutbox
1492            depth  \dp\strutbox
1493            \extrareferencearguments
1494        }%
1495     \relax
1496     \setlocationattributes
1497     \setstrut % can be option
1498     \global\lastsavedreferenceattribute\lastreferenceattribute
1499     \c_attr_reference\lastreferenceattribute
1500     \dostarttagged\t!link\empty % not here
1501     #content%
1502     \dostoptagged
1503   \else
1504     #content%
1505   \fi
1506   \endgroup}
1507
1508\def\strc_references_direct_goto_htdp#content[#label]% no test for valid references
1509  {\dontleavehmode
1510   \begingroup
1511   \global\lastsavedreferenceattribute\attributeunsetvalue
1512   \c_attr_reference\attributeunsetvalue
1513   \iflocation
1514     \clf_injectreference
1515        {\referenceprefix}%
1516        {#label}%
1517        {%
1518            height \dimexpr\interactionparameter\c!height\relax
1519            depth  \dimexpr\interactionparameter\c!depth \relax
1520            \extrareferencearguments
1521        }%
1522     \relax
1523     \setlocationattributes
1524     \c_attr_reference\lastreferenceattribute
1525     \global\lastsavedreferenceattribute\lastreferenceattribute
1526     \dostarttagged\t!link\empty
1527     #content%
1528     \dostoptagged
1529   \else
1530     #content%
1531   \fi
1532   \endgroup}
1533
1534\def\strc_references_goto#content#dummy[#label]% #dummy gobbles spaces
1535  {\dontleavehmode
1536   \begingroup
1537  %\setbox\referencebox\hbox\bgroup % experiment, might change again to non \par support
1538   \global\lastsavedreferenceattribute\attributeunsetvalue
1539   \c_attr_reference\attributeunsetvalue
1540   \iflocation
1541     \clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
1542       {\expandtexincurrentreference
1543        \clf_injectcurrentreferencehtdp
1544          \ht\strutbox
1545          \dp\strutbox
1546        \relax
1547        \setlocationattributes
1548        \setstrut % can be option
1549        \global\lastsavedreferenceattribute\lastreferenceattribute
1550        \c_attr_reference\lastreferenceattribute
1551        \dostarttagged\t!link\empty
1552        #content%
1553        \dostoptagged}%
1554       {#content}%
1555   \else
1556     #content%
1557   \fi
1558  %\egroup\unhbox\referencebox}
1559   \endgroup}
1560
1561\def\strc_references_goto_internal#content#dummy[#internal]% #dummy gobbles spaces
1562  {\dontleavehmode
1563   \begingroup
1564   \global\lastsavedreferenceattribute\attributeunsetvalue
1565   \c_attr_reference\attributeunsetvalue
1566   \iflocation
1567     \setstrut % can be option
1568     \strc_references_get_simple_reference{#internal}%
1569     \global\lastsavedreferenceattribute\currentreferenceattribute
1570     \c_attr_reference\currentreferenceattribute
1571     \setlocationattributes
1572     \dostarttagged\t!link\empty
1573     #content%
1574     \dostoptagged
1575   \else
1576     #content%
1577   \fi
1578   \endgroup}
1579
1580\unexpanded\def\startgoto[#label]%
1581  {\dontleavehmode
1582   \begingroup
1583   \iflocation
1584     \clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
1585       {\expandafter\strc_references_start_goto_yes}%
1586       {\expandafter\strc_references_start_goto_nop}%
1587   \else
1588     \expandafter\strc_references_start_goto_nop
1589   \fi}
1590
1591\unexpanded\def\strc_references_start_goto_nop
1592  {\let\stopgoto\strc_references_stop_goto_nop}
1593
1594\unexpanded\def\strc_references_stop_goto_nop
1595  {\endgroup}
1596
1597\unexpanded\def\strc_references_start_goto_yes
1598  {\expandtexincurrentreference
1599   \clf_injectcurrentreferencehtdp
1600     \ht\strutbox
1601     \dp\strutbox
1602   \relax
1603   \setlocationattributes
1604   \setstrut % can be option
1605   \global\lastsavedreferenceattribute\lastreferenceattribute
1606   \c_attr_reference\lastreferenceattribute
1607   \dostarttagged\t!link\empty
1608   \let\stopgoto\strc_references_stop_goto_yes}
1609
1610\unexpanded\def\strc_references_stop_goto_yes
1611  {\dostoptagged
1612   \endgroup}
1613
1614\def\strc_references_goto_htdp#content#dummy[#label]% dummy gobbles spaces
1615  {\dontleavehmode
1616   \begingroup
1617   \global\lastsavedreferenceattribute\attributeunsetvalue
1618   \c_attr_reference\attributeunsetvalue
1619   \iflocation
1620     \clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
1621       {\expandtexincurrentreference
1622        \clf_injectcurrentreferencehtdp
1623          \dimexpr\interactionparameter\c!height\relax
1624          \dimexpr\interactionparameter\c!depth \relax
1625        \relax
1626        \setlocationattributes
1627        \global\lastsavedreferenceattribute\lastreferenceattribute
1628        \c_attr_reference\lastreferenceattribute
1629        \dostarttagged\t!link\empty
1630        #content%
1631        \dostoptagged}%
1632       {#content}%
1633   \else
1634     #content%
1635   \fi
1636   \endgroup}
1637
1638\unexpanded\def\directgotobox#content[#label]% no test for valid references
1639  {\dontleavehmode
1640   \begingroup
1641   \global\lastsavedreferenceattribute\attributeunsetvalue
1642   \c_attr_reference\attributeunsetvalue
1643   \iflocation
1644     \clf_injectreference
1645       {\referenceprefix}%
1646       {#label}%
1647       {\extrareferencearguments}%
1648     \relax
1649     \setlocationattributes
1650     \global\lastsavedreferenceattribute\lastreferenceattribute
1651     \dostarttagged\t!link\empty
1652     \hbox attr \referenceattribute \lastreferenceattribute {#content}%
1653     \dostoptagged
1654   \else
1655     #content%
1656   \fi
1657   \endgroup}
1658
1659\unexpanded\def\directgotospecbox#resolver#content[#label]% no test for valid references
1660  {\dontleavehmode
1661   \begingroup
1662   \global\lastsavedreferenceattribute\attributeunsetvalue
1663   \c_attr_reference\attributeunsetvalue
1664   \iflocation
1665     \clf_injectreference
1666       {\referenceprefix}%
1667       {#label}%
1668       {\extrareferencearguments}%
1669     \relax
1670     \setlocationcolorspec{#resolver}% no consequence for strut
1671     \global\lastsavedreferenceattribute\lastreferenceattribute
1672     \dostarttagged\t!link\empty
1673     \hbox attr \referenceattribute \lastreferenceattribute {#content}%
1674     \dostoptagged
1675   \else
1676     #content%
1677   \fi
1678   \endgroup}
1679
1680\unexpanded\def\directgotodumbbox#content[#label]% no test for valid references
1681  {\dontleavehmode
1682   \begingroup
1683   \global\lastsavedreferenceattribute\attributeunsetvalue
1684   \c_attr_reference\attributeunsetvalue
1685   \iflocation
1686     \clf_injectreference
1687       {\referenceprefix}%
1688       {#label}%
1689       {\extrareferencearguments}%
1690     \relax
1691     \global\lastsavedreferenceattribute\lastreferenceattribute
1692     \dostarttagged\t!link\empty
1693     \hbox attr \referenceattribute \lastreferenceattribute {#content}%
1694     \dostoptagged
1695   \else
1696     #content%
1697   \fi
1698   \endgroup}
1699
1700\unexpanded\def\gotobox#content[#label]%
1701  {\dontleavehmode
1702   \begingroup
1703   \global\lastsavedreferenceattribute\attributeunsetvalue
1704   \c_attr_reference\attributeunsetvalue
1705   \iflocation
1706     \clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
1707       {\expandtexincurrentreference
1708        \clf_injectcurrentreference
1709        \setlocationattributes
1710        \global\lastsavedreferenceattribute\lastreferenceattribute
1711        \dostarttagged\t!link\empty
1712        \hbox attr \referenceattribute \lastreferenceattribute {#content}%
1713        \dostoptagged}%
1714       {#content}%
1715   \else
1716     #content%
1717   \fi
1718   \endgroup}
1719
1720\unexpanded\def\gotowdhtbox#width#height[#label]% fast variant for overlays
1721  {\dontleavehmode
1722   \begingroup
1723   \setbox\scratchbox\emptyhbox
1724   \wd\scratchbox#width%
1725   \ht\scratchbox#height%
1726   \global\lastsavedreferenceattribute\attributeunsetvalue
1727   \c_attr_reference\attributeunsetvalue
1728   \clf_doifelsereference{\referenceprefix}{#label}{\extrareferencearguments}%
1729     {\clf_injectcurrentreference
1730      \global\lastsavedreferenceattribute\lastreferenceattribute
1731      \hpack attr \referenceattribute \lastreferenceattribute {\box\scratchbox}}
1732     {\box\scratchbox}%
1733   \endgroup}
1734
1735%D An reference to another document can be specified as a file or as an \URL. Both
1736%D are handled by the same mechanism and can be issued by saying something like:
1737%D
1738%D \starttyping
1739%D \goto[dictionary::the letter a]
1740%D \stoptyping
1741%D
1742%D One can imagine that many references to such a dictionary are made, so in most
1743%D cases such a document reference in an indirect one.
1744%D
1745%D \showsetup{useexternaldocument}
1746%D
1747%D For example:
1748%D
1749%D \starttyping
1750%D \useexternaldocument
1751%D   [dictionary][engldict]
1752%D   [The Famous English Dictionary]
1753%D \stoptyping
1754%D
1755%D The next macro implements these relations, and also take care of loading the
1756%D document specific references.
1757%D
1758%D The \URL\ alternative takes four arguments:
1759%D
1760%D \showsetup{useURL}
1761%D
1762%D like:
1763%D
1764%D \starttyping
1765%D \useURL
1766%D   [dictionary][http://www.publisher.com/public][engldict]
1767%D   [The Famous English Dictionary]
1768%D \stoptyping
1769%D
1770%D Several specifications are possible:
1771%D
1772%D \starttyping
1773%D \useURL [id] [url] [file] [description]
1774%D \useURL [id] [url] [file]
1775%D \useURL [id] [url]
1776%D \stoptyping
1777%D
1778%D This time we don't load the references when no file is specified. This is logical
1779%D when one keeps in mind that a valid \URL\ can also be a mail address.
1780
1781\unexpanded\def\useurl {\doquadrupleempty\strc_references_use_url }  % so that they can be used in expanded arguments
1782\unexpanded\def\usefile{\dotripleargument\strc_references_use_file}  % so that they can be used in expanded arguments
1783
1784\let\useURL             \useurl
1785\let\useexternaldocument\usefile
1786
1787\def\strc_references_use_url[#label][#url][#file][#description]%
1788  {\clf_useurl{#label}{\detokenize{#url}}{\detokenize{#file}}{\detokenize{#description}}}
1789
1790\def\strc_references_use_file[#label][#file][#description]%
1791  {\clf_usefile{#label}{\detokenize{#file}}{\detokenize{#description}}}
1792
1793\def\doifelseurldefined #label{\clf_doifelseurldefined {#label}}
1794\def\doifelsefiledefined#label{\clf_doifelsefiledefined{#label}}
1795
1796\let\doifurldefinedelse \doifelseurldefined
1797\let\doiffiledefinedelse\doifelsefiledefined
1798
1799%D \macros
1800%D   {url,setupurl}
1801%D
1802%D We also have: \type {\url} for directly calling the description. So we can say:
1803%D
1804%D \starttyping
1805%D \useURL [one] [http://www.test.nl]
1806%D \useURL [two] [http://www.test.nl] [] [Some Site]
1807%D
1808%D \url[one] or \from[two] or \goto{Whatever Site}[URL(two)]
1809%D \stoptyping
1810%D
1811%D An \URL\ can be set up with
1812%D
1813%D \showsetup{setupurl}
1814
1815\installcorenamespace{url}
1816
1817\installdirectcommandhandler \??url {url}
1818
1819\setupurl
1820  [\c!style=\v!type,
1821   \c!color=]
1822
1823\unexpanded\def\url[#label]% move \hyphenatedurl to lua end (is already lua)
1824  {\dontleavehmode
1825   \begingroup
1826   \useurlstyleandcolor\c!style\c!color
1827   \hyphenatedurl{\clf_geturl{#label}}%
1828   \endgroup}
1829
1830%D This macro is hooked into a support macro, and thereby \URL's break ok, according
1831%D to the setting of a switch,
1832%D
1833%D \startbuffer
1834%D \useURL
1835%D   [test]
1836%D   [sentence_sentence~sentence//sentence:sentence.sentence]
1837%D \stopbuffer
1838%D
1839%D \typebuffer
1840%D
1841%D Such an \URL\ is, depending on the settings, hyphenated as:
1842%D
1843%D \getbuffer
1844
1845%D When defining the external source of information, one can also specify a suitable
1846%D name (the last argument). This name can be called upon with:
1847%D
1848%D \showsetup{from}
1849%D
1850%D We keep this for compatibility reasons, hence the hackery.
1851
1852\unexpanded\def\strc_references_from
1853  {\dosingleempty\strc_references_do_special_from}
1854
1855\def\strc_references_do_special_from[#label]%
1856  {\dontleavehmode
1857   \goto{\clf_from{#label}}[fileorurl(#label)]}
1858
1859\def\dofromurldescription#content% called at the lua end
1860  {#content}
1861
1862\def\dofromurlliteral#content% called at the lua end
1863  {\useurlstyleandcolor\c!style\c!color
1864   \hyphenatedurl{#content}}
1865
1866\let\dofromfiledescription\dofromurldescription
1867\let\dofromfileliteral    \dofromurlliteral     % maybe some day setupfile that inherits from url
1868
1869%D We also support:
1870%D
1871%D \starttyping
1872%D \goto{some text}[file(identifier{location}]
1873%D \stoptyping
1874%D
1875%D which is completely equivalent with
1876%D
1877%D \starttyping
1878%D \goto{some text}[identifier::location]
1879%D \stoptyping
1880
1881%D A special case of references are those to programs. These, very system dependant
1882%D references are implemented by abusing some of the previous macros.
1883%D
1884%D \showsetup{setupprograms}
1885%D \showsetup{defineprogram}
1886%D \showsetup{program} % changed functionality !
1887%D
1888%D The latter gives access to the description of the program,
1889%D being the last argument to the definition command.
1890
1891% also lua, like urls and files
1892
1893\installcorenamespace{programs}
1894
1895\installdirectcommandhandler \??programs {programs}
1896
1897\unexpanded\def\defineprogram
1898  {\dotripleargument\strc_references_define_program}
1899
1900\def\strc_references_define_program[#name][#program][#description]%
1901  {\clf_defineprogram{#name}{#program}{#description}}
1902
1903\unexpanded\def\program[#name]% incompatible, more consistent, hardy used anyway
1904  {\dontleavehmode
1905   \begingroup
1906   \useprogramsstyleandcolor\c!style\c!color
1907   \clf_getprogram{#name}%
1908   \endgroup}
1909
1910%D As we can see, we directly use the special reference mechanism, which means that
1911%D
1912%D \starttyping
1913%D \goto{some text}[program(name{args})]
1914%D \stoptyping
1915%D
1916%D is valid.
1917
1918%D The next macro provides access to the actual pagenumbers. When documenting and
1919%D sanitizing the original reference macros, I decided to keep the present meaning
1920%D as well as to make this meaning available as a special reference method. So now
1921%D one can use:
1922%D
1923%D \starttyping
1924%D \gotopage{some text}[location]
1925%D \gotopage{some text}[number]
1926%D \gotopage{some text}[file::number]
1927%D \stoptyping
1928%D
1929%D as well as:
1930%D
1931%D \starttyping
1932%D \goto{some text}[page(location)]
1933%D \goto{some text}[page(number)]
1934%D \goto{some text}[file::page(number)]
1935%D \stoptyping
1936%D
1937%D Here location is a keyword like \type{nextpage}.
1938%D
1939%D \showsetup{gotopage}
1940
1941\unexpanded\def\definepage
1942  {\dodoubleargument\strc_references_define_page}
1943
1944\def\strc_references_define_page[#name][#target]%
1945  {\definereference[#name][page(#target)]}
1946
1947\def\gotopage#text[#target]%
1948  {\goto{#text}[\v!page(#target)]}
1949
1950%D The previous definitions are somewhat obsolete so we don't use it here.
1951
1952%D We can cross link documents by using:
1953%D
1954%D \showsetup{coupledocument}
1955%D
1956%D like:
1957%D
1958%D \starttyping
1959%D \coupledocument[print][somefile][chapter,section]
1960%D \stoptyping
1961%D
1962%D After which when applicable, we have available the references:
1963%D
1964%D \starttyping
1965%D \goto{print version}[print::chapter]
1966%D \stoptyping
1967%D
1968%D and alike. The title placement definition macros have a key \type {file}, which
1969%D is interpreted as the file to jump to, that is, when one clicks on the title.
1970
1971\def\coupledocument
1972  {\doquadrupleempty\strc_references_couple_document}
1973
1974\def\strc_references_couple_document[#name][#file][#sections][#description]%
1975  {\ifthirdargument
1976     % this will be done differently (when it's needed)
1977   \fi}
1978
1979%D \macros
1980%D   {dotextprefix}
1981%D
1982%D In previous macros we used \type {\dotextprefix} to generate a space between
1983%D a label and a number.
1984%D
1985%D \starttyping
1986%D \dotextprefix{text}
1987%D \stoptyping
1988%D
1989%D Only when \type {text} is not empty, a space is inserted.
1990
1991\unexpanded\def\dotextprefix#text%
1992  {\begingroup
1993   \setbox\scratchbox\hbox{#text}% to be solved some day
1994   \ifdim\wd\scratchbox>\zeropoint
1995     \unhbox\scratchbox
1996     \edef\p_separator{\referencingparameter\c!separator}%
1997     \ifx\p_separator\empty \else
1998        \removeunwantedspaces % remove is new
1999        \p_separator
2000     \fi
2001   \else
2002     \unhbox\scratchbox
2003   \fi
2004   \endgroup}
2005
2006%D In the next settings we see some variables that were not used here and that
2007%D concern the way the pagenumbers refered to are typeset.
2008
2009\setupreferencing
2010  [\c!state=\v!start,
2011   \c!autofile=\v!no,
2012   \v!part\c!number=\v!yes,
2013   \v!chapter\c!number=\v!no,
2014   \c!interaction=\v!all,
2015   \c!convertfile=\v!no,
2016  %\c!strut=\v!no, % some day an option
2017   \c!prefix=,
2018   \c!width=.75\makeupwidth,
2019   \c!left=\quotation\bgroup,
2020   \c!right=\egroup,
2021   \c!global=\v!no,
2022   \c!expansion=\v!no,
2023   \c!separator=\nonbreakablespace,
2024   \c!export=\v!no]
2025
2026\setupprograms
2027  [\c!directory=,
2028   \c!style=\v!type,
2029   \c!color=]
2030
2031\definereference [\v!CloseDocument    ] [action(close)]
2032\definereference [\v!ExitViewer       ] [action(exit)]
2033\definereference [\v!FirstPage        ] [action(first)]
2034\definereference [\v!LastPage         ] [action(last)]
2035\definereference [\v!NextJump         ] [action(forward)]
2036\definereference [\v!NextPage         ] [action(next)]
2037\definereference [\v!PauseMovie       ] [action(pausemovie)]
2038\definereference [\v!PauseSound       ] [action(pausesound)]
2039\definereference [\v!PauseRendering   ] [action(pauserendering)]
2040\definereference [\v!PreviousJump     ] [action(backward)]
2041\definereference [\v!PreviousPage     ] [action(previous)]
2042\definereference [\v!PrintDocument    ] [action(print)]
2043\definereference [\v!SaveForm         ] [action(exportform)]
2044\definereference [\v!LoadForm         ] [action(importform)]
2045\definereference [\v!ResetForm        ] [action(resetform)]
2046\definereference [\v!ResumeMovie      ] [action(resumemovie)]
2047\definereference [\v!ResumeSound      ] [action(resumesound)]
2048\definereference [\v!ResumeRendering  ] [action(resumerendering)]
2049\definereference [\v!SaveDocument     ] [action(save)]
2050\definereference [\v!SaveNamedDocument] [action(savenamed)]
2051\definereference [\v!OpenNamedDocument] [action(opennamed)]
2052\definereference [\v!SearchDocument   ] [action(search)]
2053\definereference [\v!SearchAgain      ] [action(searchagain)]
2054\definereference [\v!StartMovie       ] [action(startmovie)]
2055\definereference [\v!StartSound       ] [action(startsound)]
2056\definereference [\v!StartRendering   ] [action(startrendering)]
2057\definereference [\v!StopMovie        ] [action(stopmovie)]
2058\definereference [\v!StopSound        ] [action(stopsound)]
2059\definereference [\v!StopRendering    ] [action(stoprendering)]
2060\definereference [\v!SubmitForm       ] [action(submitform)]
2061\definereference [\v!ToggleViewer     ] [action(toggle)]
2062\definereference [\v!ViewerHelp       ] [action(help)]
2063\definereference [\v!HideField        ] [action(hide)]
2064\definereference [\v!ShowField        ] [action(show)]
2065\definereference [\v!GotoPage         ] [action(gotopage)]
2066\definereference [\v!Query            ] [action(query)]
2067\definereference [\v!QueryAgain       ] [action(queryagain)]
2068\definereference [\v!FitWidth         ] [action(fitwidth)]
2069\definereference [\v!FitHeight        ] [action(fitheight)]
2070\definereference [\v!ShowThumbs       ] [action(thumbnails)]
2071\definereference [\v!ShowBookmarks    ] [action(bookmarks)]
2072
2073\definereference [\v!HideLayer        ] [action(hidelayer)]
2074\definereference [\v!VideLayer        ] [action(videlayer)]
2075\definereference [\v!ToggleLayer      ] [action(togglelayer)]
2076
2077\definereference [\v!firstpage]       [page(firstpage)]
2078\definereference [\v!previouspage]    [page(previouspage)]
2079\definereference [\v!nextpage]        [page(nextpage)]
2080\definereference [\v!lastpage]        [page(lastpage)]
2081\definereference [\v!forward]         [page(forward)]
2082\definereference [\v!backward]        [page(backward)]
2083\definereference [\v!firstsubpage]    [page(firstsubpage)]
2084\definereference [\v!previoussubpage] [page(previoussubpage)]
2085\definereference [\v!nextsubpage]     [page(nextsubpage)]
2086\definereference [\v!lastsubpage]     [page(lastsubpage)]
2087
2088% we can do this but only when later in resolve (else problems with \chapter[first]{...}
2089%
2090% \definereference [\v!first]           [page(firstpage)]
2091% \definereference [\v!previous]        [page(prevpage)]
2092% \definereference [\v!next]            [page(nextpage)]
2093% \definereference [\v!last]            [page(lastpage)]
2094% \definereference [\v!first\v!sub]     [page(firstsubpage)]
2095% \definereference [\v!previous\v!sub]  [page(prevsubpage)]
2096% \definereference [\v!next\v!sub]      [page(nextsubpage)]
2097% \definereference [\v!last\v!sub]      [page(lastsubpage)]
2098
2099%D We cannot set up buttons (not yet, this one calls a menu macro):
2100
2101%D New (and experimental):
2102
2103% \starttext
2104%     \chapter{test}
2105%     \placefigure[here][xx:1]{}{\framed{one}} \placefigure[here][xx:2]{}{\framed{three}}
2106%     \placetable [here][xx:3]{}{\framed{two}} \placetable [here][xx:4]{}{\framed{four}}
2107%     \start
2108%         \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
2109%     \stop \blank \start
2110%         \setupreferencestructureprefix[default][prefix=no]
2111%         \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
2112%     \stop \blank \start
2113%         \setupreferencestructureprefix[float][default][prefix=no]
2114%         \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
2115%     \stop \blank \start
2116%         \setupreferencestructureprefix[figure][default][prefix=no]
2117%         \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
2118%     \stop \blank
2119% \stoptext
2120
2121% todo: parameterhandler
2122
2123\installcorenamespace{referencingprefix}
2124
2125\def\getreferencestructureprefix#kind#name#category% name will change
2126  {{%
2127        prefix        {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefix}%
2128        separatorset  {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixseparatorset}%
2129        conversion    {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixconversion}%
2130        conversionset {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixconversionset}%
2131        starter       {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixstarter}%
2132        stopper       {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixstopper}%
2133        set           {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixset}%
2134        segments      {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixsegments}%
2135        connector     {\referencestructureprefixparameter{#kind}{#name}{#category}\c!prefixconnector}%
2136  }%
2137  {%
2138        separatorset  {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numberseparatorset}%
2139        conversion    {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numberconversion}%
2140        conversionset {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numberconversionset}%
2141        starter       {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numberstarter}%
2142        stopper       {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numberstopper}%
2143        segments      {\referencestructureprefixparameter{#kind}{#name}{#category}\c!numbersegments}%
2144  }}
2145
2146\unexpanded\def\setupreferencestructureprefix
2147  {\dotripleempty\strc_references_setup_reference_structure_prefix}
2148
2149\def\strc_references_setup_reference_structure_prefix[#kind][#category][#settings]%
2150  {\ifthirdargument
2151     \getparameters[\??referencingprefix#kind:#category][#settings]%
2152   \else\ifsecondargument
2153     \getparameters[\??referencingprefix:#kind][#category]%
2154   \fi\fi}
2155
2156\def\referencestructureprefixparameter#kind#name#category#parameter%
2157  {\ifcsname\??referencingprefix#name:#category#parameter\endcsname
2158     \lastnamedcs
2159   \else\ifcsname\??referencingprefix#kind:#category#parameter\endcsname
2160     \lastnamedcs
2161   \else\ifcsname\??referencingprefix:#category#parameter\endcsname
2162     \lastnamedcs
2163   \fi\fi\fi}
2164
2165\def\currentreferencedefault % for some reason we need to explicitly expand
2166  {\normalexpanded{\noexpand\clf_filterdefaultreference
2167     {\s!default}%
2168     \noexpand\getreferencestructureprefix\clf_getcurrentprefixspec{\s!default}% returns #kind#name#category
2169   \relax}}
2170
2171%D Not all support is visible by looking at the \TEX\ code; here is one of those:^
2172%D
2173%D \starttyping
2174%D \startinteractionmenu[right]
2175%D   \startbut [section(first   {chapter})]    first chapter \stopbut
2176%D   \startbut [section(previous{chapter})] previous chapter \stopbut
2177%D   \startbut [section(next    {chapter})]     next chapter \stopbut
2178%D   \startbut [section(last    {chapter})]     last chapter \stopbut
2179%D   \blank[2*big]
2180%D   \startbut [section(first   {section})]    first section \stopbut
2181%D   \startbut [section(previous{section})] previous section \stopbut
2182%D   \startbut [section(next    {section})]     next section \stopbut
2183%D   \startbut [section(last    {section})]     last section \stopbut
2184%D \stopinteractionmenu
2185%D \stoptyping
2186
2187%D Relatively new:
2188%D
2189%D \starttyping
2190%D \chapter{The never ending story}
2191%D
2192%D \section{An ending story}
2193%D
2194%D \in{chapter}[match(complex bibliographies)]
2195%D \in{chapter}[match(never ending)]
2196%D \in{chapter}[match(ending)]
2197%D \in{chapter}[match(chapter:never ending)]
2198%D \in{chapter}[match(chapter:ending)]
2199%D \in{section}[match(section:ending)]
2200%D \in{figure}[match(float:mess)]
2201%D \in{figure}[match(figure:mess)]
2202%D \in{figure (not found)}[match(section:mess)]
2203%D \in{figure (not found)}[match(section:xxxx)]
2204%D \in{figure}[match(mess)]
2205%D
2206%D \placefigure{What a mess}{}
2207%D
2208%D \chapter{About complex bibliographies}
2209%D
2210%D \in{chapter}[match(complex bibliographies)]
2211%D \in{chapter}[match(never ending)]
2212%D \in{figure}[match(mess)]
2213%D \stoptyping
2214
2215\protect \endinput
2216
2217% tricky:
2218%
2219% \enabletrackers[nodes.references]
2220% \setupinteraction[state=start]
2221% \def\KnuthTest{\input knuth }
2222% \def\KnuthTest{\input tufte }
2223% \def\TufteTest{\input tufte }
2224% \defineoverlay[xxx][\overlaybutton{page(3)}]
2225% \setupbackgrounds[text][background=xxx]
2226% \starttext
2227% test {\red \KnuthTest} test \par
2228% \button{test}[page(1)] \par
2229% \goto{page 2 \TeX}[page(2)] \goto{page 2 \TeX}[page(2)] \goto{\TufteTest}[page(2)] test \page
2230% test \goto{page 3}[page(3)] \goto{\TufteTest\space\par\TufteTest}[page(4)] test \page
2231% \goto{page 1}[page(1)] \goto{\TufteTest\space test}[page(1)] \page
2232% \goto{page 1}[page(1)] \goto{\KnuthTest\space test}[page(1)] \page
2233% test \goto{page 1}[page(1)] {\goto{\KnuthTest\space test}[page(1)]} test
2234% \goto{page 1}[page(1)] \goto{\TufteTest}[page(1)] test \page
2235% \stoptext
2236