summaryrefslogtreecommitdiff
path: root/tex/context/base/strc-ref.mkiv
diff options
context:
space:
mode:
Diffstat (limited to 'tex/context/base/strc-ref.mkiv')
-rw-r--r--tex/context/base/strc-ref.mkiv1851
1 files changed, 1851 insertions, 0 deletions
diff --git a/tex/context/base/strc-ref.mkiv b/tex/context/base/strc-ref.mkiv
new file mode 100644
index 000000000..8290a1b13
--- /dev/null
+++ b/tex/context/base/strc-ref.mkiv
@@ -0,0 +1,1851 @@
+%D \module
+%D [ file=strc-ref,
+%D version=2008.10.20,
+%D title=\CONTEXT\ Structure Macros,
+%D subtitle=Cross Referencing,
+%D author=Hans Hagen,
+%D date=\currentdate,
+%D copyright=PRAGMA-ADE / Hans Hagen]
+%C
+%C This module is part of the \CONTEXT\ macro||package and is
+%C therefore copyrighted by \PRAGMA. See mreadme.pdf for
+%C details.
+
+% todo: (1) configure references, (2) rendering => with presets
+%
+% \definestructureconversionset[default][Character,number,Romannumerals,Character][number]
+% \definestructureseparatorset [default][.,.,--][.]
+% \setupstructurehead[subsection][sectionstopper=),sectionsegments=4:4]
+% \setupreferencestructureprefix[default][prefixsegments=2:4]
+% \setupreferencestructureprefix[figure][default][prefixsegments=3:4]
+% \chapter {One}
+% \section {One}
+% \subsection[sec:test]{Two}
+% See \in[sec:test] and \in[fig:xx] and \in[fig:yy]
+% \placefigure[here][fig:xx]{}{}
+% \placefigure[here][fig:yy]{}{}
+
+\writestatus{loading}{ConTeXt Structure Macros / Cross Referencing}
+
+\registerctxluafile{strc-ref}{1.001}
+\registerctxluafile{node-ref}{1.001}
+
+\unprotect
+
+%D This module is a (partial) rewrite of core-ref.tex for \MKIV. As
+%D such it will be a moving target for a while.
+
+%D Later we will do a further cleanup and move much of the code to
+%D \LUA\ (i.e.\ better backend integration).
+
+\let\mainreference\gobblefivearguments
+
+% this will go when we got rid of the tuo file
+
+\let\currentfolioreference \!!zerocount % only used in xml-fo
+\let\resetreferences \relax
+\let\setreferences \relax
+\let\showcurrentreference \relax
+\let\setexecutecommandcheck\gobbletwoarguments
+
+\def\s!full{full}
+\def\s!user{user}
+\def\s!text{text}
+\def\s!page{page}
+
+% todo : unknown/illegal reference no arg
+% todo : +n pages check on 'samepage' (contrastcolor)
+% todo : multiple text in reference
+
+% Makes more sense to build action data first, especially now
+% openaction etc are supported.
+%
+% \definespecial\doexecuteactionchain w h
+% \definespecial\dosetgotolocation
+% \definespecial\dosetexecuteJScode
+% ...
+
+%D This module deals with referencing. In \CONTEXT\ referencing
+%D is one of the core features, although at a first glance
+%D probably nobody will notice. This is good, because
+%D referencing should be as hidden as possible.
+%D
+%D In paper documents, referencing comes down to cross
+%D referencing, but in their interactive counterparts, is also
+%D involves navigation. Many features implemented here are
+%D therefore closely related to navigation.
+%D
+%D Many \CONTEXT\ commands can optionally be fed with a
+%D reference. Such a reference, when called upon, returns the
+%D number of a figure, table, chapter etc, a piece of text, or
+%D a pagenumber.
+%D
+%D There are three ways of defining a reference:
+%D
+%D \starttyping
+%D \pagereference[here]
+%D \textreference[here]{some text}
+%D \stoptyping
+%D
+%D the third alternative combines them in:
+%D
+%D \starttyping
+%D \reference[here]{some text}
+%D \stoptyping
+
+\unexpanded\def\textreference {\dosingleargument\dotextreference}
+\unexpanded\def\pagereference {\dosingleargument\dopagereference}
+\unexpanded\def\reference {\dosingleargument\doreference }
+\unexpanded\def\setreference {\dodoubleargument\dosetreference }
+
+%D These are implemented in a low level form as:
+
+\def\dotextreference [#1]{\dodosetreference\s!text{#1}{}}
+\def\dopagereference [#1]{\dodosetreference\s!page{#1}{}{}}
+\def\doreference [#1]{\dodosetreference\s!full{#1}{}}
+\def\dosetreference[#1][#2]{\dodosetreference\s!user{#1}{#2}{}}
+
+%D Actually there is not much difference between a text and a
+%D full reference, but it's the concept that counts. The low
+%D level implementation is:
+
+\newcount\lastreferenceattribute
+\newcount\lastdestinationattribute
+
+\def\dofinishfullreference#1#2{\normalexpanded{\ctxlatelua{jobreferences.enhance("#1","#2")}}}
+\def\dofinishtextreference#1#2{\normalexpanded{\ctxlatelua{jobreferences.enhance("#1","#2",{})}}}
+
+\let\dofinishpagereference\dofinishfullreference
+\let\dofinishuserreference\dofinishfullreference
+
+\def\dodosetreference#1#2#3#4% kind labels userdata text -> todo: userdata
+ {\ifreferencing
+ \edef\currentreferencekind{#1}%
+ \edef\currentreferencelabels{#2}%
+ \edef\currentreferenceexpansion{\@@rfexpansion}% {\referenceparameter\c!expansion}
+ \ifx\currentreferencelabels\empty \else
+ \ifx\currentreferenceexpansion\s!xml
+ \xmlstartraw
+ \xdef\currentreferencedata{#4}% data, no text else conflict
+ \xmlstopraw
+ \globallet\currentreferencecoding\s!xml
+ \else
+ \ifx\currentreferenceexpansion\v!yes
+ \xdef\currentreferencedata{#4}%
+ \else
+ \xdef\currentreferencedata{\detokenize{#4}}%
+ \fi
+ \globallet\currentreferencecoding\s!tex
+ \fi
+ % beware, the jobreferences.set writes a
+ % \setnextinternalreference
+ \ctxlua{jobreferences.setandgetattribute("\currentreferencekind", "\referenceprefix","\currentreferencelabels",
+ {
+ references = {
+ % internal = \nextinternalreference, % no need for an internal as we have an explicit
+ block = "\currentstructureblock",
+ section = structure.sections.currentid(),
+ },
+ metadata = {
+ kind = "#1",
+ catcodes = \the\catcodetable,
+ xmlroot = \ifx\currentreferencecoding\s!xml "\xmldocument" \else nil \fi, % only useful when text
+ },
+ \ifx\currentreferencedata\empty\else
+ entries = {
+ text = \!!bs\currentreferencedata\!!es
+ },
+ \fi
+ userdata = structure.helpers.touserdata(\!!bs\detokenize{#3}\!!es)
+ },"\@@iafocus")
+ }%
+ \xdef\currentdestinationattribute{\number\lastdestinationattribute}%
+ \begingroup\attribute\destinationattribute\currentdestinationattribute\hbox{}\endgroup % todo
+ \fi
+ \fi}
+
+\def\defaultreferencepage#1{[[[#1]]]}
+\def\defaultreferencetext#1{[[[#1]]]}
+
+%D These macros depend on three other ones,
+%D \type {\makesectionformat}, that generated \type
+%D {\sectionformat}, \type {\pagenumber}. The not yet used
+%D argument \type{#1} is a tag that specifies the type of
+%D reference.
+
+%D \macros
+%D {everyreference}
+%D
+%D For rather tricky purposes, one can assign sanitizing
+%D macros to \type{\everyreference} (no longer that relevant).
+
+\newevery \everyreference \relax
+
+%D This is really needed, since for instance Polish has a
+%D different alphabet and needs accented entries in registers.
+
+\appendtoks
+ \cleanupfeatures
+\to \everyreference
+
+%D We did not yet discuss prefixing. Especially in interactive
+%D documents, it's not always easy to keep track of duplicate
+%D references. The prefix mechanism, which we will describe
+%D later on, solves this problem. By (automatically) adding a
+%D prefix one keeps references local, but the global ones in
+%D view. To enable this feature, we explictly split the prefix
+%D from the reference.
+
+\let\referenceprefix\empty
+
+%D For a long time the only way to access an external file was
+%D to use the file prefix (\type {somefile::}. However, when
+%D you split up a document, redefining the references may be
+%D such a pain, that another approach is feasible. By setting
+%D the \type {autofile} variable to \type {yes} or \type
+%D {page}, you can access the reference directly.
+%D
+%D \starttabulate[||||]
+%D \NC filename::tag \NC page(filename::pnum) \NC tag \NC\NR
+%D \NC $\star$ \NC \NC \NC\NR
+%D \NC $\star$ \NC $\star$ \NC $\star$ \NC\NR
+%D \NC \NC $\star$ \NC \NC\NR
+%D \stoptabulate
+
+\def\usereferences[#1]% not yet
+ {\writestatus\m!systems{references from other files are handled automatically}}
+
+%D As mentioned we will also use the cross reference mechanism
+%D for navigational purposes. The main reason for this is that
+%D we want to treat both categories alike:
+%D
+%D \starttyping
+%D \goto{go back}[PreviousJump]
+%D \goto{colofon}[colofon page]
+%D \stoptyping
+%D
+%D Here \type{PreviousJump} is handled by the viewer, while the
+%D \type{colofon page} reference is, apart from hyperlinking, a
+%D rather normal reference.
+%D
+%D We already saw that cross refences are written to and read
+%D from a file. The pure navigational ones don't need to be
+%D written to file, but both for fast processing and
+%D transparant integration, they are saved internally as a sort
+%D of reference. We can easily distinguish such system
+%D references from real cross reference ones by their tag.
+%D
+%D We also use the odd/even characteristic to determine the
+%D page state.
+
+\let\currentrealreference \empty
+\let\currentpagereference \empty
+\let\currenttextreference \empty
+\let\currentreferenceorder \empty
+\let\currentsubtextreference \empty
+\let\currentsubsubtextreference\empty
+
+\newcount\referencepagestate % set in backend
+\newcount\referencehastexstate % set in backend
+
+% referencepagestate:
+%
+% 0 = no page ref, 1=same page, 2=before, 3=after
+
+%D Text references can contain more than one entry and
+%D therefore we check for
+%D
+%D \starttyping
+%D {entry}
+%D \stoptyping
+%D
+%D or
+%D
+%D \starttyping
+%D {{entry}{entry}{entry}}
+%D \stoptyping
+%D
+%D and split accordingly.
+
+%D Cross references appear as numbers (figure~1.1, chapter~2)
+%D or pagenumbers (page~2, page 3--2), and are called with
+%D \type{\in} and \type{\at}. In interactive documents we also
+%D have \type{\goto}, \type{\button} and alike. These are more
+%D versatile and look like:
+%D
+%D \starttyping
+%D \goto[reference]
+%D \goto[outer reference::]
+%D \goto[outer reference::inner reference]
+%D \goto[operation(argument)]
+%D \goto[operation(action{argument,argument})]
+%D \goto[action]
+%D \goto[action{argument}]
+%D \stoptyping
+%D
+%D The first one is a normal reference, the second and third
+%D are references to a file or \URL. The brace delimited
+%D references for instance refer to a \JAVASCRIPT. The last
+%D example shows that we can pass arguments to the actions.
+%D
+%D When we split off the components of such a reference, the
+%D results are available in:
+%D
+%D \starttyping
+%D \currentreferencespecial
+%D \currentreferenceoperation
+%D \currentreferencearguments
+%D \currentinnerreference
+%D \currentouterreference
+%D \currentfullreference
+%D \stoptyping
+
+\newif\ifreferencefound
+
+% \let\currentfullreference \empty
+% \let\currentreferencespecial \empty
+% \let\currentreferenceoperation\empty
+% \let\currentreferencearguments\empty
+% \let\currentouterreference \empty
+% \let\currentinnerreference \empty
+
+%D Now we've come to the testing step. As we can see below,
+%D this macro does bit more than testing: it also resolves
+%D the reference. This means that whenever we test for the
+%D existance of a reference at an outer level, we have all the
+%D relevant properties of that reference avaliable inside the
+%D true branche~(\type{#2}).
+%D
+%D The prefix has to do with localizing references. When a
+%D prefix is set, looking for a reference comes to looking for
+%D the prefixed one, and when not found, looking for the non
+%D prefixed one. Consider for instance the prefix set to
+%D \type{sidetrack}.
+%D
+%D \starttyping
+%D \pagereference[important]
+%D \pagereference[unimportant]
+%D \setupreferencing[prefix=sidetrack]
+%D \pagereference[important]
+%D \stoptyping
+%D
+%D results in saving (writing) the references
+%D
+%D \starttyping
+%D ...{}{important}
+%D ...{}{unimportant}
+%D ...{sidetrack}{important}...
+%D \stoptyping
+%D
+%D Now when we call for \type{unimportant}, we will indeed get
+%D the pagenumber associated to this reference. But when we
+%D call for \type{important}, while the prefix is still set, we
+%D will get the pagenumber bound to the prefixed one.
+%D
+%D {\em Some day, when processing time and memory are no longer
+%D performance factors, we will introduce multi||level
+%D prefixes.}
+%D
+%D Before we start analyzing, I introduce a general
+%D definition macro. Consider:
+%D
+%D \starttyping
+%D \goto{do}[JS(My_Script{"test",123}),titlepage]
+%D \stoptyping
+%D
+%D This can also be achieved by:
+%D
+%D \starttyping
+%D \definereference[startup][JS(My_Script{"test",123}),titlepage]
+%D \goto{do}[startup]
+%D \stoptyping
+%D
+%D Now is this is a handy feature or not?
+%D
+%D \showsetup{definereference}
+%D
+%D We can trace references by setting the next switch to
+%D true.
+
+\unexpanded\def\definereference
+ {\dodoubleempty\dodefinereference}
+
+\def\dodefinereference[#1][#2]%
+ {\ctxlua{jobreferences.define("\referenceprefix","#1",\!!bs\detokenize{#2}\!!es)}}
+
+\def\resetreference[#1]%
+ {\ctxlua{jobreferences.reset("\referenceprefix","#1")}}
+
+\def\setpagereference#1#2% name, specification
+ {\ctxlua{jobreferences.define("","#1",\!!bs\v!page(\luaescapestring{#2})\!!es)}}
+
+%D Chained references are defined as:
+%D
+%D \starttyping
+%D \goto{somewhere}[JS(somescript),nextpage,JS(anotherscript)]
+%D \stoptyping
+%D
+%D Actually supporting chains is up to the special driver. Here
+%D we only provide the hooks.
+
+%D \macros
+%D {highlighthyperlinks}
+%D
+%D The next switch can be used to make user hyperlinks are
+%D not highlighted when clicked on.
+
+\newconditional\highlighthyperlinks \settrue\highlighthyperlinks
+
+%D \macros
+%D {gotonewwindow}
+%D
+%D To make the {\em goto previous jump} feature more
+%D convenient when using more than one file, it makes sense
+%D to force the viewer to open a new window for each file
+%D opened.
+
+\newconditional\gotonewwindow \setfalse\gotonewwindow
+
+\def\expandtexincurrentreference % will happen in lua some time
+ {\ifcase\referencehastexstate\else\ctxlua{jobreferences.expandcurrent()}\fi}
+
+\def\doifreferencefoundelse#1#2#3%
+ {\ctxlua{jobreferences.doifelse("\referenceprefix","#1",\luaconditional\highlighthyperlinks,\luaconditional\gotonewwindow)}%
+ {\expandtexincurrentreference#2}%
+ {#3}}
+
+%D The tester only splits the reference in components but does
+%D not look into them. The following macro does a preroll and
+%D determines for instance the current real reference pagenumber.
+%D The \type {\currentrealreference} macro does the same so unless
+%D one wants to use the pagestate the next macro seldom needs to
+%D be called.
+
+\def\analyzecurrentreference
+ {\ctxlua{jobreferences.analyse()}}
+
+%D The inner case is simple. Only two cases have to be taken
+%D care of:
+%D
+%D \starttyping
+%D \goto{some text}[reference]
+%D \goto{some text}[prefix:reference]
+%D \stoptyping
+%D
+%D References to other files however are treated strict or
+%D tolerant, depending on their loading and availability:
+%D
+%D \starttyping
+%D \useexternaldocument[somefile][filename][a nice description]
+%D
+%D \goto{checked reference}[somefile::reference]
+%D \goto{unchecked reference}[somefile::]
+%D \goto{unchecked reference}[anotherfile::reference]
+%D \stoptyping
+%D
+%D An unknown reference is reported on the screen, in the log
+%D file and, when enabled, in the left margin of the text.
+
+\def\reportreferenceerror#1#2% only once (keep track in lua)
+ {\ifinpagebody \else
+ \doifconcepttracing{\doifsomething{#2}{\inleft{\infofont\doboundtext{#2}{\dimexpr\leftmarginwidth-2em\relax}{..}->}}}%
+ \fi
+ \showmessage\m!references{#1}{[\referenceprefix][#2]}}
+
+\def\unknownreference{\reportreferenceerror1}
+\def\illegalreference{\reportreferenceerror4}
+
+%D When a reference is not found, we typeset a placeholder
+%D (two glyphs are often enough to represent the reference
+%D text).
+
+\def\dummyreference{{\tttf ??}}
+
+%D To prevent repetitive messages concerning a reference
+%D being defined, we set such an unknown reference to an empty
+%D one after the first encounter.
+
+%D Apart from cross references supplied by the user, \CONTEXT\
+%D generates cross references itself. Most of them are not
+%D saved as a reference, but stored with their source, for
+%D instance a list or an index entry. Such automatically
+%D generated, for the user invisible, references are called
+%D {\em internal references}. The user supplied ones are
+%D labeled as {\em external references}.
+%D
+%D A second important characteristic is that when we want to
+%D support different backends (viewers), we need to support
+%D named destinations as well as page numbers. I invite readers
+%D to take a glance at the special driver modules to understand
+%D the fine points of this. As a result we will deal with {\em
+%D locations} as well as {\em real page numbers}. We explictly
+%D call this pagenumber a real one, because it is independant
+%D of the page numbering scheme used in the document.
+%D
+%D One of the reasons for \CONTEXT\ being the first \TEX\ base
+%D macropackage to support sophisticated interactive \PDF\
+%D files, lays in the mere fact that real page numbers are
+%D available in most two pass data, like references, list data
+%D and index entries.
+%D
+%D We will speak of \type{thisis...} when we are marking a
+%D location, and \type{goto...} when we point to such a
+%D location. The latter one can be seen as a hyperlink to the
+%D former one. In the next macros one we use constructs like:
+%D
+%D \starttyping
+%D \dostart...
+%D \dostop...
+%D \stoptyping
+%D
+%D Such macros are used to invoke the relevant specials from
+%D the special driver modules (see \type{spec-ini}). The flag
+%D \type{\iflocation} signals if we're in interactive mode.
+
+\ifx\buttonheight\undefined \newdimen\buttonheight \fi
+\ifx\buttonwidth \undefined \newdimen\buttonwidth \fi
+
+%D Internal references can best be set using the next few
+%D macros. Setting such references to unique values is
+%D completely up to the macros that call them.
+%D
+%D \starttyping
+%D \thisissomeinternal{tag}{identifier}
+%D \gotosomeinternal {tag}{identifier}{pagenumber}{text}
+%D \stoptyping
+
+%D We could do this in lua ...
+
+\newif \iflocation
+\newcount\locationcount
+\newcount\locationorder
+\newbox \locationbox
+
+\def\nextinternalreference {\the\locationcount}
+\def\nextinternalorderreference{\the\locationorder}
+
+\def\setnextinternalreference
+ {\global\advance\locationcount\plusone}
+
+\def\setnextinternalreferences#1#2% plural
+ {\ctxlua{jobreferences.setnextinternal("#1","#2")}}
+
+\def\getinternalorderreference#1#2%
+ {\ctxlua{jobreferences.currentorder("#1","#2")}}
+
+\def\thisissomeinternal#1#2% tag reference (only for old time sake)
+ {\begingroup\attribute\destinationattribute\ctxlua{jobreferences.mark("#1:#2")}\hbox{}\endgroup}
+
+\def\gotosomeinternal#1#2#3#4%
+ {\ifinternalnamedreferences
+ \directgoto{#4}[#1:#2]%
+ \else
+ \directgoto{#4}[page(#3)]%
+ \fi}
+
+\def\gotonextinternal#1#2%
+ {\directgoto{#1}[internal(#2)]}
+
+%D In this module we define three system references: one for
+%D handling navigational, viewer specific, commands, another
+%D for jumping to special pages, like the first or last one,
+%D and a third reference for linking tree like lists, like
+%D tables of contents. The latter two adapt themselves to the
+%D current state.
+%D
+%D An example of an action is:
+%D
+%D \starttyping
+%D \goto{some action}[PreviousJump]
+%D \stoptyping
+%D
+%D as well as:
+%D
+%D \starttyping
+%D \goto{some text}[\v!action(PreviousJump]
+%D \stoptyping
+
+% compatibility hack
+
+\def\setglobalsystemreference#1#2#3{\definereference[#2][\v!action(#3)]}
+
+\newif\ifreferencing \referencingtrue
+
+%D One can also activate an automatic prefix mechanism. By
+%D setting the \type{\prefix} variable to \type{+}, the prefix
+%D is incremented, when set to \type{-} or empty, the prefix is
+%D reset. Other values become the prefix.
+
+\newcount\prefixcounter
+
+%D These settings are accomplished by:
+%D
+%D \showsetup{setupreferencing}
+%D
+%D In interactive documents verbose references don't always
+%D make sense (what is a page number in an unnumbered
+%D document). By setting the \type{interaction} variable, one
+%D can influences the way interactive references are set.
+
+\chardef\autocrossfilereferences=0
+
+\unexpanded\def\setupreferencing
+ {\dosingleargument\dosetupreferencing}
+
+\def\dosetupreferencing[#1]%
+ {\getparameters
+ [\??rf]
+ [\c!prefix=\s!unknown,#1]%
+ \processaction
+ [\@@rfstate]
+ [ \v!stop=>\referencingfalse,
+ \v!start=>\referencingtrue]%
+ \processaction
+ [\@@rfinteraction]
+ [ \v!all=>\let\dowantedreference\docompletereference,
+ \v!label=>\let\dowantedreference\dolabelonlyreference,
+ \v!text=>\let\dowantedreference\dotextonlyreference,
+ \v!symbol=>\let\dowantedreference\dosymbolreference]%
+ \chardef\autocrossfilereferences\zerocount
+ \processaction
+ [\@@rfautofile]
+ [ \v!yes=>\chardef\autocrossfilereferences\plusone,
+ \v!page=>\chardef\autocrossfilereferences\plustwo]%
+ \chardef\referencefilecase\zerocount
+ \processaction[\@@rfconvertfile]
+ [ \v!yes=>\chardef\referencefilecase\plusone,
+ \v!big=>\chardef\referencefilecase\plusone,
+ \v!small=>\chardef\referencefilecase\plustwo]%
+ \setupreferenceprefix[\@@rfprefix]%
+ \doifelse\@@rfglobal\v!yes
+ {\settrue \autoglobalfilereferences}
+ {\setfalse\autoglobalfilereferences}}
+
+% \appendtoks\ctxlua{jobreferences.export("whatever")}\to\everystoptext
+% \starttext
+% \chapter[test]{test}
+% test \in{IN}[more] and \in{IN}[test] or \at{AT}[more] and \at{AT}[test]\par
+% test \in{IN}[whatever::more] and \in{IN}[whatever::test] or \at{AT}[whatever::more] and \at{AT}[whatever::test] \page
+% reference\reference[more]{oeps}
+% \stoptext
+
+\def\exportreferences
+ {\doif\@@rfexport\v!yes{\ctxlua{jobreferences.export()}}}
+
+\appendtoks
+ \exportreferences
+\to \everygoodbye
+
+\def\incrementreferenceprefix{+}
+\def\decrementreferenceprefix{-}
+
+\unexpanded\def\setupreferenceprefix[#1]%
+ {\edef\@@rfprefix{#1}%
+ \ifx\@@rfprefix\empty
+ \let\referenceprefix\empty
+ \else\ifx\@@rfprefix\incrementreferenceprefix
+ \advance\prefixcounter \plusone % should be global
+ \edef\referenceprefix{\the\prefixcounter:}%
+ \let\@@rfprefix\s!unknown
+ \else\ifx\@@rfprefix\decrementreferenceprefix
+ \let\referenceprefix\empty
+ \let\@@rfprefix\s!unknown
+ \else\ifx\@@rfprefix\s!unknown
+ % forget about it
+ \else
+ \edef\referenceprefix{\@@rfprefix:}%
+ \fi\fi\fi\fi}
+
+%D The most straightforward way of retrieving references is
+%D using \type{\ref}. Consider the reference:
+%D
+%D \startbuffer
+%D \reference[my ref]{{Look}{Here}{I am}}
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D \getbuffer
+%D
+%D We can ask for upto five reference components:
+%D
+%D \startbuffer
+%D user page reference: \ref[p][my ref]
+%D text reference: \ref[t][my ref]
+%D real page reference: \ref[r][my ref]
+%D sub text reference: \ref[s][my ref]
+%D extra text reference: \ref[e][my ref]
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D And get back:
+%D
+%D \startlines
+%D \getbuffer
+%D \stoplines
+%D
+%D This is a cheap compatibility hack. Don't use this command
+%D as there will be more advanced access to user data.
+
+\def\ref{\dodoubleargument\doref}
+
+\def\reftypep{\currentreferencepage}
+\def\reftypet{\currentreferencetext}
+\def\reftyper{\currentreferencepage}
+\def\reftypes{\currentreferencetext}
+\def\reftypee{\currentreferencetext}
+
+\def\doref[#1][#2]%
+ {\ifsecondargument
+ \doifreferencefoundelse{#2}
+ {\executeifdefined{reftype#1}\reftypep}
+ {\unknownreference{#2}\dummyreference}%
+ \else
+ \dummyreference
+ \fi}
+
+%D We can typeset a reference using \type{\in}, \type{\at} and
+%D \type{\about} and goto specific locations using
+%D \type{\goto}. The last one does not make that much sense in
+%D a paper document. To complicate things, \PLAIN\ \TEX\ also
+%D implements an \type {\in} but fortunately that one only
+%D makes sense in math mode.
+%D
+%D Typesetting the reference is a bit more complicated than one
+%D would at first sight expect. This is due to the fact that we
+%D distinguish three (five) alternative calls:
+%D
+%D \placefigure
+%D [here][three calls]
+%D {Three alternatives reference calls.}
+%D {\startcombination[1*3]
+%D {\framed{\type{ \in }}} {a}
+%D {\framed{\type{ \at }}} {b}
+%D {\framed{\type{\goto}}} {c}
+%D \stopcombination}
+%D
+%D \startbuffer
+%D \in figure[fig:three calls]
+%D \in{figure}[fig:three calls]
+%D \in figure a[fig:three calls]
+%D \in{figure}{a}[fig:three calls]
+%D figure~\in[fig:three calls]
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D This turns up as:
+%D
+%D \startlines
+%D \getbuffer
+%D \stoplines
+%D
+%D The dual \type{{}} results in a split reference. In a
+%D document meant for paper, one is tempted to use the last
+%D (most straightforward) alternative. When a document is also
+%D meant voor electronic distribution, the former alternatives
+%D have preference, because everything between the \type{\in}
+%D and~\type{[} becomes active (and when asked for, typeset
+%D in a different color and typeface).
+
+% \unexpanded\def\in {\mathortext\donormalmathin \dospecialin}
+% \unexpanded\def\at {\mathortext\donormalmathat \dospecialat}
+% \unexpanded\def\about{\mathortext\donormalmathabout\dospecialabout}
+% \unexpanded\def\from {\mathortext\donormalmathfrom \dospecialfrom}
+% \unexpanded\def\over {\mathortext\donormalmathover \dospecialabout}
+
+% \definecommand in {\dospecialin}
+% \definecommand at {\dospecialat}
+% \definecommand about {\dospecialabout}
+% \definecommand from {\dospecialfrom}
+% \definecommand over {\dospecialabout} % needed here, else math problems
+
+\def\currentreferencenumber {\ctxlua{jobreferences.filter("number")}}
+\def\currentreferencepage {\ctxlua{jobreferences.filter("page")}}
+\def\currentreferencetitle {\ctxlua{jobreferences.filter("title")}}
+\def\currentreferencetext {\ctxlua{jobreferences.filter("text")}}
+\def\currentreferencedefault {\ctxlua{jobreferences.filter("default")}}
+\def\currentreferencerealpage{\ctxlua{jobreferences.realpage()}}
+
+\def\getreferenceentry#1{\ctxlua{jobreferences.filter("#1")}} % user entry
+
+\unexpanded\def\dospecialabout[#1]%
+ {\dontleavehmode
+ \begingroup
+ \let\crlf\space
+ \let\\\space
+ \postponenotes
+ \@@rfleft
+ \doifreferencefoundelse{#1}
+ {\goto{\limitatetext\currentreferencetitle\@@rfwidth\unknown}[#1]}% not so efficient (dup lookup)
+ {}% todo
+ \@@rfright
+ \endgroup}
+
+%D The previously discussed setup macro lets us specify the
+%D representation of references. A symbol reference does not
+%D show the specific data, like the number of a figure, but
+%D shows one of: \hbox {$^\goforwardcharacter$
+%D $^\gobackwardcharacter$ $^\gonowherecharacter$}, depending
+%D on the direction to go.
+
+% 1 = whatever
+% 2 = forward, following page
+% 3 = backward, preceding page
+% 4 = forward, same page
+% 5 = backward, same page
+
+% Yet untested:
+
+\unexpanded\def\somewhere#1#2#3[#4]% #3 gobbles space around #2 % todo
+ {\doifreferencefoundelse{#4}% kind of inefficient as \goto also analyses
+ {\goto{\analyzecurrentreference\ifcase\referencepagestate\relax#1/#2\or#2\or#1\or#2\fi}[#4]}
+ {[#1/#2]}}
+
+\unexpanded\def\atpage[#1]% todo
+ {\doifreferencefoundelse{#1}% kind of inefficient as \goto also analyses
+ {\goto{\analyzecurrentreference\ifcase\referencepagestate
+ \labeltexts\v!page\dummyreference
+ \or
+ \labeltexts\v!atpage\currentreferencepage
+ \or
+ \labeltexts\v!atpage\currentreferencepage
+ \or
+ \labeltexts\v!atpage\currentreferencepage
+ \or
+ \labeltext\v!hereafter
+ \or
+ \labeltext\v!hencefore
+ \fi}[#1]}
+ {[?]}}
+
+\unexpanded\def\referencesymbol
+ {\hbox{\strut\high
+ {\setupsymbolset[\@@iasymbolset]%
+ \symbol
+ [\ifcase\referencepagestate
+ \v!somewhere
+ \or % same
+ \v!nowhere
+ \or % before
+ \v!previous
+ \or % after
+ \v!next%
+ \fi]}}}
+
+% \def\dosymbolreference#1#2[#3]%
+% {\removeunwantedspaces
+% \goto{\setupsymbolset[\@@iasymbolset]\high{\symbol
+% [\ifcase\referencepagestate
+% \v!somewhere
+% \or % same
+% \v!nowhere
+% \or % before
+% \v!previous
+% \or % after
+% \v!next%
+% \fi]}}[#3]}
+
+\def\dosymbolreference#1#2[#3]%
+ {\removeunwantedspaces
+ \goto{\referencesymbol}[#3]}
+
+\def\symbolreference[#1]%
+ {\removeunwantedspaces
+ \goto{\referencesymbol}[#1]}
+
+
+%D The other alternatives just conform their names: only the
+%D label, only the text, or the label and the text.
+
+\def\dounknownreference#1#2[#3]%
+ {\unknownreference{#3}\dotextprefix{#2}\dummyreference}%
+
+\def\docompletereference#1#2[#3]%
+ {\goto{\dotextprefix{#2}#1}[#3]}
+
+% \def\dolabelonlyreference#1#2[#3]%
+% {\doifsomespaceelse{#2}% space?
+% {\doifsomething{#2}{\goto{#2}[#3]}}
+% {\goto{\dotextprefix{#2}}[#3]}}
+
+\def\dolabelonlyreference#1#2[#3]%
+ {\goto{\dotextprefix{#2}}[#3]}
+
+\def\dotextonlyreference#1#2[#3]%
+ {\dotextprefix{#2}\goto{#1}[#3]}
+
+\let\dowantedreference\docompletereference
+
+%D \macros
+%D {definereferenceformat}
+%D
+%D The next few macros were made for for David Arnold and Taco
+%D Hoekwater. They can be used for predefining reference
+%D texts, and thereby stimulate efficiency.
+%D
+%D [more documentation will be added]
+%D
+%D \starttyping
+%D \definereferenceformat[informula] [left=(,right=),text=formula]
+%D \definereferenceformat[informulas] [left=(,right=),text=formulas]
+%D \definereferenceformat[andformula] [left=(,right=),text=and]
+%D \definereferenceformat[andformulas][left=(,right=),text=and]
+%D
+%D \informula [b] and \informula [for:c]
+%D the \informula {formulas}[b] \informula {and} [for:c]
+%D the \informulas {formulas}[b] \informula {and} [for:c]
+%D the \informulas [b] \informula {en} [for:c]
+%D the \informulas [b] \andformula [for:c]
+%D \stoptyping
+%D
+%D Instead of a text, one can specify a label, which should
+%D be defined with \type {\setuplabeltext}.
+
+% todo: inherit; probably not yet mkiv okay
+
+\unexpanded\def\definereferenceformat
+ {\dodoubleargument\dodefinereferenceformat}
+
+\def\dodefinereferenceformat[#1][#2]%
+ {\iffirstargument
+ \getparameters[\??rf#1]
+ [\c!left=, % of the number
+ \c!right=, % of the number
+ \c!text=, % before the number
+ \c!label=, % can be {left}{right}
+ \c!command=\in,
+ #2]%
+ \setuvalue{#1}%
+ {\dontleavehmode\doexecutereferenceformat{#1}}%
+ \fi}
+
+\def\noexecutelabelreferenceformat#1%
+ {\doifvaluesomething{\??rf#1\c!text}{\gdef\textofreference{\csname\??rf#1\c!text\endcsname}}%
+ \csname\??rf#1\c!command\endcsname}
+
+\def\doexecutelabelreferenceformat#1%
+ {\csname\??rf#1\c!command\endcsname
+ {\leftlabeltext {\csname\??rf#1\c!label\endcsname}}%
+ {\rightlabeltext{\csname\??rf#1\c!label\endcsname}}}
+
+\def\doexecutereferenceformat#1%
+ {\gdef\leftofreference {\csname\??rf#1\c!left \endcsname}%
+ \gdef\rightofreference{\csname\??rf#1\c!right\endcsname}%
+ \global\let\textofreference\empty % otherwise ~ added
+ \doifelsevaluenothing{\??rf#1\c!label}\noexecutelabelreferenceformat\doexecutelabelreferenceformat{#1}}
+
+\let\leftofreference \relax
+\let\rightofreference\relax
+\let\textofreference \relax
+
+% fails on metafun {\leftofreference#1\ignorespaces#3\removeunwantedspaces\rightofreference}{#2}[#4]%
+%
+% \def\dodododoinatreference#1#2#3[#4]% no \removeunwantedspaces (fails on metafun)
+% {\ifx\next\bgroup
+% \dododododoinatreference{\leftofreference#1\ignorespaces#3\rightofreference}{#2}[#4]%
+% \else
+% \dododododoinatreference{\leftofreference#1\rightofreference}{#2#3}[#4]%
+% \fi}
+%
+% \def\dododododoinatreference#1#2[#3]%
+% {\dontleavehmode % replaces \leaveoutervmode
+% \begingroup
+% \postponenotes
+% \doifreferencefoundelse{#3}
+% {\doifelsenothing{#1}\dosymbolreference\dowantedreference{#1}{#2}[#3]}%
+% {\dounknownreference{#1}{#2}[#3]}%
+% \endgroup}
+
+% \starttext
+% \definereferenceformat[inxx] [left=(,right=),text=txt]
+% \setupinteraction[state=start]
+% \chapter[one]{xx}
+% [\goto{state}[file(mk-last-state)]]
+% [\goto{state} [file(mk-last-state)]]
+% [\at{page} [one]]
+% [\at{page}[one]]
+% [\at{page}{okay}[one]]
+% [\inxx{a}{b}[one]]
+% \stoptext
+
+\unexpanded\def\dospecialin{\let\currentreferencecontent\currentreferencedefault\doinatreference}
+\unexpanded\def\dospecialat{\let\currentreferencecontent\currentreferencepage \doinatreference}
+
+\newtoks\leftreferencetoks
+\newtoks\rightreferencetoks
+
+\def\doinatreference
+ {\futurelet\next\doinatreferenceone}
+
+\def\doinatreferenceone
+ {\ifx\next\bgroup
+ \afterassignment\doinatreferenceonetwo
+ \expandafter\leftreferencetoks
+ \else
+ \leftreferencetoks\emptytoks
+ \expandafter\dodoinatreferencenone
+ \fi}
+
+\def\doinatreferenceonetwo
+ {\futurelet\next\doinatreferencetwo}
+
+\def\doinatreferencetwo
+ {\ifx\next\bgroup
+ \afterassignment\dodoinatreferenceboth
+ \expandafter\rightreferencetoks
+ \else
+ \rightreferencetoks\emptytoks
+ \expandafter\dodoinatreferenceleft
+ \fi}
+
+\def\dodoinatreferencenone
+ {\dodoinatreferenceindeed
+ {\leftofreference\currentreferencecontent\rightofreference}
+ {}}
+
+\def\dodoinatreferenceleft
+ {\dodoinatreferenceindeed
+ {\leftofreference\currentreferencecontent\rightofreference}
+ {\the\leftreferencetoks}}
+
+\def\dodoinatreferenceboth
+ {\dodoinatreferenceindeed
+ {\leftofreference\currentreferencecontent\the\rightreferencetoks\rightofreference}
+ {\the\leftreferencetoks}}
+
+\def\dodoinatreferenceindeed#1#2#3[#4]% #3 gobbles space
+ {\dontleavehmode % replaces \leaveoutervmode
+ \begingroup
+ \postponenotes
+ \doifreferencefoundelse{#4}
+ {\doifelsenothing{#1}\dosymbolreference\dowantedreference{#1}{#2}[#4]}%
+ {\dounknownreference{#1}{#2}[#4]}%
+ \endgroup}
+
+\let\dosymbolreference\dowantedreference
+
+%D In interactive documents going to a specific location is not
+%D bound to cross references. The \type{\goto} commands can be
+%D used to let users access another part of the document. In
+%D this respect, interactive tables of contents and registers
+%D can be considered goto's. Because in fact a \type{\goto} is
+%D just a reference without reference specific data, the
+%D previous macros are implemented using the goto
+%D functionality.
+%D
+%D \showsetup{goto}
+%D
+%D One important characteristic is that the first argument of
+%D \type{\goto} (and therefore \type{\at} and \type{\in} is
+%D split at spaces. This means that, although hyphenation is
+%D prevented, long references can cross line endings.
+
+% \starttext
+% \setupinteraction[state=start]
+% [\goto{state}[file(mk-last-state)]]
+% [\goto{state} [file(mk-last-state)]]
+% \stoptext
+
+\newconditional\uselocationstrut \settrue\uselocationstrut
+
+\def\extrareferencearguments{\luaconditional\highlighthyperlinks,\luaconditional\gotonewwindow,"\currentviewerlayer"}
+
+\unexpanded\def\directgoto{\ifconditional\uselocationstrut\expandafter\dodirectgoto\else\expandafter\directgotohtdp\fi}
+\unexpanded\def\goto {\ifconditional\uselocationstrut\expandafter\dogoto \else\expandafter\gotohtdp \fi}
+
+% The unbox trick is needed in order to permit \par inside a reference. Otherwise
+% the reference attribute migrates to the outer boxes.
+
+\newbox\referencebox
+
+\def\dodirectgoto#1[#2]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.inject("\referenceprefix","#2",\number\ht\strutbox,\number\dp\strutbox,\extrareferencearguments)}%
+ \setlocationattributes\??ia
+ \setstrut % can be option
+ \attribute\referenceattribute\lastreferenceattribute
+ \fi
+ #1%
+ \endgroup}
+
+\def\dodirectgotohtdp#1[#2]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.inject("\referenceprefix","#2",\number\dimexpr\@@iaheight\relax,\number\dimexpr\@@iadepth\relax,\extrareferencearguments)}%
+ \setlocationattributes\??ia
+ \attribute\referenceattribute\lastreferenceattribute
+ \fi
+ #1%
+ \endgroup}
+
+\def\dogoto#1#2[#3]% #2 gobbles spaces after #1 so that \goto{xx} [yy] works ok
+ {\dontleavehmode
+ \begingroup
+ %\setbox\referencebox\hbox\bgroup % experiment, might change again to non \par support
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.doifelse("\referenceprefix","#3",\extrareferencearguments)}%
+ {\expandtexincurrentreference
+ \ctxlua{jobreferences.injectcurrentset(\number\ht\strutbox,\number\dp\strutbox)}%
+ \setlocationattributes\??ia
+ \setstrut % can be option
+ \attribute\referenceattribute\lastreferenceattribute}%
+ {\unknownreference{#3}}%
+ \fi
+ #1%
+ %\egroup\unhbox\referencebox}
+ \endgroup}
+
+\def\dogotohtdp#1#2[#3]% #2 gobbles spaces after #1 so that \goto{xx} [yy] works ok
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.doifelse("\referenceprefix","#3",\extrareferencearguments)}%
+ {\expandtexincurrentreference
+ \ctxlua{jobreferences.injectcurrentset(\number\dimexpr\@@iaheight\relax,\number\dimexpr\@@iadepth\relax)}%
+ \setlocationattributes\??ia
+ \attribute\referenceattribute\lastreferenceattribute}%
+ {\unknownreference{#3}}%
+ \fi
+ #1%
+ \endgroup}
+
+\unexpanded\def\directgotobox#1[#2]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.inject("\referenceprefix","#2",nil,nil,\extrareferencearguments)}%
+ \setlocationattributes\??ia
+ \hbox attr \referenceattribute \lastreferenceattribute {#1}%
+ \else
+ #1%
+ \fi
+ \endgroup}
+
+\unexpanded\def\directgotospecbox#1#2[#3]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.inject("\referenceprefix","#3",nil,nil,\extrareferencearguments)}%
+ \setlocationcolorspec{#1}% no consequence for strut
+ \hbox attr \referenceattribute \lastreferenceattribute {#2}%
+ \else
+ #2%
+ \fi
+ \endgroup}
+
+\unexpanded\def\directgotodumbbox#1[#2]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.inject("\referenceprefix","#2",nil,nil,\extrareferencearguments)}%
+ \hbox attr \referenceattribute \lastreferenceattribute {#1}%
+ \else
+ #1%
+ \fi
+ \endgroup}
+
+\unexpanded\def\gotobox#1[#2]% no test for valid references
+ {\dontleavehmode
+ \begingroup
+ \attribute\referenceattribute\attributeunsetvalue
+ \iflocation
+ \ctxlua{jobreferences.doifelse("\referenceprefix","#2",\extrareferencearguments)}%
+ {\expandtexincurrentreference
+ \ctxlua{jobreferences.injectcurrentset(nil,nil)}%
+ \setlocationattributes\??ia
+ \hbox attr \referenceattribute \lastreferenceattribute {#1}}%
+ {\unknownreference{#2}}%
+ \else
+ #1%
+ \fi
+ \endgroup}
+
+%D An reference to another document can be specified as a file
+%D or as an \URL. Both are handled by the same mechanism and
+%D can be issued by saying something like:
+%D
+%D \starttyping
+%D \goto[dictionary::the letter a]
+%D \stoptyping
+%D
+%D One can imagine that many references to such a dictionary
+%D are made, so in most cases such a document reference in an
+%D indirect one.
+%D
+%D \showsetup{useexternaldocument}
+%D
+%D For example:
+%D
+%D \starttyping
+%D \useexternaldocument
+%D [dictionary][engldict]
+%D [The Famous English Dictionary]
+%D \stoptyping
+%D
+%D The next macro implements these relations, and also take
+%D care of loading the document specific references.
+%D
+%D The \URL\ alternative takes four arguments:
+%D
+%D \showsetup{useURL}
+%D
+%D like:
+%D
+%D \starttyping
+%D \useURL
+%D [dictionary][http://www.publisher.com/public][engldict]
+%D [The Famous English Dictionary]
+%D \stoptyping
+%D
+%D Several specifications are possible:
+%D
+%D \starttyping
+%D \useURL [id] [url] [file] [description]
+%D \useURL [id] [url] [file]
+%D \useURL [id] [url]
+%D \stoptyping
+%D
+%D This time we don't load the references when no file is
+%D specified. This is logical when one keeps in mind that a
+%D valid \URL\ can also be a mail address.
+
+\unexpanded\def\usefile{\dotripleargument\dousefile} % so that they can be used in expanded arguments
+\unexpanded\def\useurl {\doquadrupleempty\douseurl } % so that they can be used in expanded arguments
+
+\let\useURL \useurl
+\let\useexternaldocument\usefile
+
+\def\douseurl[#1][#2][#3][#4]%
+ {\ctxlua{jobreferences.urls.define("#1",\!!bs\detokenize{#2}\!!es,\!!bs\detokenize{#3}\!!es,\!!bs\detokenize{#4}\!!es)}}
+
+\def\dousefile[#1][#2][#3]%
+ {\ctxlua{jobreferences.files.define("#1",\!!bs\detokenize{#2}\!!es,\!!bs\detokenize{#3}\!!es)}}
+
+\def\doifurldefinedelse #1{\ctxlua{commands.doifurldefinedelse ("#1")}}
+\def\doiffiledefinedelse#1{\ctxlua{commands.doiffiledefinedelse("#1")}}
+
+%D \macros
+%D {url,setupurl}
+%D
+%D We also have: \type{\url} for directly calling the
+%D description. So we can say:
+%D
+%D \starttyping
+%D \useURL [one] [http://www.test.nl]
+%D \useURL [two] [http://www.test.nl] [] [Some Site]
+%D
+%D \url[one] or \from[two] or \goto{Whatever Site}[URL(two)]
+%D \stoptyping
+%D
+%D An \URL\ can be set up with
+%D
+%D \showsetup{setupurl}
+
+\unexpanded\def\setupurl
+ {\dodoubleargument\getparameters[\??ur]}
+
+\unexpanded\def\url[#1]%
+ {\dontleavehmode
+ \begingroup
+ \dosetfontattribute\??ur\c!style
+ \dosetcolorattribute\??ur\c!color
+ \hyphenatedurl{\ctxlua{jobreferences.urls.get("#1","\@@uralternative","\@@urspace")}}%
+ \endgroup}
+
+% # fails
+
+%D This macro is hooked into a support macro, and thereby
+%D \URL's break ok, according to the setting of a switch,
+%D
+%D \startbuffer
+%D \useURL
+%D [test]
+%D [sentence_sentence~sentence//sentence:sentence.sentence]
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D Such an \URL\ is, depending on the settings, hyphenated as:
+%D
+%D \getbuffer
+%D
+%D \startlinecorrection
+%D \hbox to \hsize
+%D {\hss\en
+%D \setupreferencing[urlalternative=both]%
+%D \vbox{\hsize.25cm\hbox{\bf both}\prewordbreak\url[test]}%
+%D \hss
+%D \setupreferencing[urlalternative=before]%
+%D \vbox{\hsize.25cm\hbox{\bf before}\prewordbreak\url[test]}%
+%D \hss
+%D \setupreferencing[urlalternative=after]%
+%D \vbox{\hsize.25cm\hbox{\bf after}\prewordbreak\url[test]}%
+%D \hss}
+%D \stoplinecorrection
+%D
+%D By setting \type{urlspace=yes} one can get slightly better
+%D spacing when using very long \URL's.
+%D
+%D When defining the external source of information, one can
+%D also specify a suitable name (the last argument). This name
+%D can be called upon with:
+%D
+%D \showsetup{from}
+
+%D We keep this for compatibility reasons, hence the hackery.
+
+\unexpanded\def\dospecialfrom
+ {\dosingleempty\dodospecialfrom}
+
+\def\dodospecialfrom[#1]%
+ {\dontleavehmode
+ \goto{\ctxlua{jobreferences.from("#1")}}[fileorurl(#1)]}
+
+\def\dofromurldescription#1%
+ {#1}
+
+\def\dofromurlliteral#1%
+ {\dosetfontattribute \??ur\c!style
+ \dosetcolorattribute\??ur\c!color
+ \hyphenatedurl{#1}}
+
+\let\dofromfiledescription\dofromurldescription
+\let\dofromfileliteral \dofromurlliteral % maybe some day setupfile that inherits from url
+
+%D We also support:
+%D
+%D \starttyping
+%D \goto{some text}[file(identifier{location}]
+%D \stoptyping
+%D
+%D which is completely equivalent with
+%D
+%D \starttyping
+%D \goto{some text}[identifier::location]
+%D \stoptyping
+
+%D A special case of references are those to programs. These,
+%D very system dependant references are implemented by abusing
+%D some of the previous macros.
+%D
+%D \showsetup{setupprograms}
+%D \showsetup{defineprogram}
+%D \showsetup{program} % changed functionality !
+%D
+%D The latter gives access to the description of the program,
+%D being the last argument to the definition command.
+
+% also lua, like urls and files
+
+\unexpanded\def\setupprograms
+ {\dodoubleargument\getparameters[\??pr]}
+
+\unexpanded\def\defineprogram
+ {\dotripleargument\dodefineprogram}
+
+\def\dodefineprogram[#1][#2][#3]%
+ {\ctxlua{jobreferences.programs.define("#1","#2","#3")}}
+
+\def\program[#1]% incompatible, more consistent, hardy used anyway
+ {\dontleavehmode
+ \begingroup
+ \dosetfontattribute\??pr\c!style
+ \dosetcolorattribute\??pr\c!color
+ \ctxlua{jobreferences.programs.get("#1","\@@pralternative","\@@prspace")}%
+ \endgroup}
+
+%D As we can see, we directly use the special reference
+%D mechanism, which means that
+%D
+%D \starttyping
+%D \goto{some text}[program(name{args})]
+%D \stoptyping
+%D
+%D is valid.
+
+%D The next macro provides access to the actual pagenumbers.
+%D When documenting and sanitizing the original reference
+%D macros, I decided to keep the present meaning as well as to
+%D make this meaning available as a special reference method.
+%D So now one can use:
+%D
+%D \starttyping
+%D \gotopage{some text}[location]
+%D \gotopage{some text}[number]
+%D \gotopage{some text}[file::number]
+%D \stoptyping
+%D
+%D as well as:
+%D
+%D \starttyping
+%D \goto{some text}[page(location)]
+%D \goto{some text}[page(number)]
+%D \goto{some text}[file::page(number)]
+%D \stoptyping
+%D
+%D Here location is a keyword like \type{nextpage}.
+%D
+%D \showsetup{gotopage}
+
+\unexpanded\def\definepage
+ {\dodoubleargument\dodefinepage}
+
+\def\dodefinepage[#1][#2]%
+ {\definereference[#1][page(#1)]}
+
+\def\gotopage#1[#2]%
+ {\goto{#1}[\v!page(#2)]}
+
+%D The previous definitions are somewhat obsolete so we don't
+%D use it here.
+
+%D A still very rudimentary|/|experimental forward|/|backward
+%D reference mechanism is provided by the macro \type{\atpage}:
+%D
+%D \starttyping
+%D ... \somewhere{backward text}{forward text}[someref] ...
+%D ... \atpage[someref] ...
+%D \stoptyping
+%D
+%D In future versions there will be more sophisticated
+
+% 0 = no page reference
+% 1 = same page
+% 2 = preceding page
+% 3 = following page
+% 4 = backward, same page (todo)
+% 5 = forward, same page (todo)
+
+%D We can cross link documents by using:
+%D
+%D \showsetup{coupledocument}
+%D
+%D like:
+%D
+%D \starttyping
+%D \coupledocument[print][somefile][chapter,section]
+%D \stoptyping
+%D
+%D After which when applicable, we have available the
+%D references:
+%D
+%D \starttyping
+%D \goto{print version}[print::chapter]
+%D \stoptyping
+%D
+%D and alike. The title placement definition macros have a
+%D key \type{file}, which is interpreted as the file to jump
+%D to, that is, when one clicks on the title.
+
+\newif\ifautocrossdocument
+
+\def\coupledocument
+ {\doquadrupleempty\docoupledocument}
+
+\def\docoupledocument[#1][#2][#3][#4]% [name] [file] [sections] [description]
+ {\ifthirdargument
+ % this will be done differently (when it's needed)
+ \fi}
+
+%D Buttons are just what their names says: things that can be
+%D clicked (pushed) on. They are similar to \type{\goto},
+%D except that the text argument is not interpreted.
+%D Furthermore one can apply anything to them that can be done
+%D with \type{\framed}.
+%D
+%D \startbuffer
+%D \button[width=3cm,height=1.5cm]{Exit}[ExitViewer]
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D gives
+%D
+%D \getbuffer
+%D
+%D This command is formally specified as:
+%D
+%D \showsetup{button}
+%D
+%D The characteristics can be set with:
+%D
+%D \showsetup{setupbuttons}
+
+\unexpanded\def\setupbuttons
+ {\dodoubleargument\getparameters[\??bt]}
+
+\definecomplexorsimpleempty\button
+
+\def\complexbutton
+ {\docomplexbutton\??bt}
+
+\presetlocalframed[\??bt]
+
+\long\def\docomplexbutton#1[#2]#3#4% get rid of possible space before [#4]
+ {\dodocomplexbutton#1[#2]{#3}#4} % #4 == [
+
+\def\buttonframed{\dodoubleempty\localframed[\??bt]} % goodie
+
+\long\def\dodocomplexbutton#1[#2]#3[#4]% #3 can contain [] -> {#3} later
+ {\begingroup
+ \doifvalue{#1\c!state}\v!stop\locationfalse
+ \iflocation
+ \ConvertConstantAfter\doifelse{#3}\v!none\hphantom\hbox
+ {\doifelsenothing{#4}
+ {\setlocationboxnop#1[#2]{#3}[#4]}
+ {\doifreferencefoundelse{#4} % INEFFICIENT
+ {\setlocationboxyes#1[#2]{#3}[#4]}
+ {\unknownreference{#4}%
+ \setlocationboxnop#1[#2]{#3}[#4]}}}%
+ \fi
+ \endgroup}
+
+\setupbuttons
+ [\c!state=\v!start]
+
+%D Interaction buttons, in fact a row of tiny buttons, are
+%D typically only used for navigational purposed. The next
+%D macro builds such a row based on a specification list.
+%D
+%D \startbuffer
+%D \interactionbuttons
+%D [width=\hsize][page,PreviousJump,ExitViewer]
+%D \stopbuffer
+%D
+%D \typebuffer
+%D
+%D gives
+%D
+%D \getbuffer
+%D
+%D Apart from individual entries, one can use \type{page} and
+%D \type {subpage} as shortcuts to their four associated buttons.
+%D The symbols are derived from the symbols linked to the
+%D entries.
+
+% does not work well with for instance SomeRef{whatever}
+
+\def\interactionbuttons
+ {\dodoubleempty\dointeractionbuttons}
+
+\def\dointeractionbuttons[#1][#2]% er is een verdeel macro \horizontalfractions
+ {\iflocation
+ % BUG: fails when frame=off; best is to rewrite this macro
+ \bgroup
+ \doif\@@ibstate\v!stop\locationfalse
+ \iflocation
+ \ifsecondargument
+ \setupinteractionbar[#1]%
+ \checkinteractionbar{1.5em}\v!broad\!!zeropoint % brrrrr
+ \setbox2\hbox{\localframed[\??ib][\c!background=]{\symbol[\@@iasymbolset][\v!previouspage]}}%
+ \!!heighta\ht2 % needed because we default to nothing
+ \setupinteractionbar[\c!strut=\v!no]%
+ \setinteractionparameter\c!width\!!zeropoint
+ \!!counta\zerocount % new, was 1
+ \processallactionsinset
+ [#2]
+ [ \v!page=>\advance\!!counta 4,
+ \v!subpage=>\advance\!!counta 4,
+ \s!unknown=>\advance\!!counta 1]%
+ \ifdim\@@ibwidth=\zeropoint
+ \!!widtha2em
+ \advance\!!widtha \@@ibdistance % new
+ \!!widthb\!!counta\!!widtha
+ \advance\!!widthb -\@@ibdistance % new
+ \else
+ \!!widtha\@@ibwidth
+ \!!widthb\@@ibdistance % new
+ \multiply\!!widthb \!!counta % new
+ \advance\!!widthb -\@@ibdistance % new
+ \advance\!!widtha -\!!widthb % new
+ \divide\!!widtha \!!counta
+ \!!widthb\@@ibwidth
+ \fi
+ \def\xgoto##1% clash ?
+ {\setnostrut
+ \edef\localreference{##1}%
+ \normalexpanded{\noexpand\dodocomplexbutton\??ib[\c!height=\the\!!heighta,\c!width=\the\!!widtha]}%
+ {\dontleavehmode\symbol[\@@iasymbolset][\localreference]}%
+ [\localreference]%
+ \hss}%
+ \hbox to \!!widthb
+ {\processallactionsinset
+ [#2]
+ [ \v!page=>\xgoto\v!firstpage
+ \xgoto\v!nextpage
+ \xgoto\v!previouspage
+ \xgoto\v!lastpage,
+ \v!subpage=>\xgoto\v!firstsubpage
+ \xgoto\v!nextsubpage
+ \xgoto\v!previoussubpage
+ \xgoto\v!lastsubpage,
+ \s!unknown=>\xgoto\commalistelement]%
+ \unskip}%
+ \else
+ \interactionbuttons[][#1]%
+ \fi
+ \fi
+ \egroup
+ \fi}
+
+%D \macros
+%D {overlaybutton}
+%D
+%D For converience we provide:
+%D
+%D \starttyping
+%D \overlaybutton[reference]
+%D \stoptyping
+%D
+%D This command can be used to define overlays an/or can be
+%D used in the whatevertext areas, like:
+%D
+%D \starttyping
+%D \defineoverlay[PrevPage][\overlaybutton{PrevPage}]
+%D \setupbackgrounds[page][background=PrevPage]
+%D \setuptexttexts[\overlaybutton{NextPage}]
+%D \stoptyping
+%D
+%D For practical reasons, this macro accepts square brackets
+%D as well as braces.
+
+\definecomplexorsimple\overlaybutton
+
+\def\simpleoverlaybutton#1%
+ {\complexoverlaybutton[#1]}
+
+\def\complexoverlaybutton[#1]%
+ {\iflocation
+ \gotobox{\overlayfakebox}[#1]%
+ \fi}
+
+\def\overlayfakebox
+ {\hbox
+ {\setbox\scratchbox\null
+ \wd\scratchbox\overlaywidth
+ \ht\scratchbox\overlayheight
+ \box\scratchbox}}
+
+%D \macros
+%D {dotextprefix}
+%D
+%D In previous macros we used \type {\dotextprefix} to
+%D generate a space between a label and a number.
+%D
+%D \starttyping
+%D \dotextprefix{text}
+%D \stoptyping
+%D
+%D Only when \type {text} is not empty, a space is inserted.
+
+\def\dotextprefix#1%
+ {\begingroup
+ \setbox\scratchbox\hbox{#1}% to be solved some day
+ \ifdim\wd\scratchbox>\zeropoint
+ \unhbox\scratchbox
+ \doifsomething\@@rfseparator{\removeunwantedspaces\@@rfseparator}% remove is new
+ \else
+ \unhbox\scratchbox
+ \fi
+ \endgroup}
+
+%D In the next settings we see some variables that were not
+%D used here and that concern the way the pagenumbers refered
+%D to are typeset.
+
+\setupreferencing
+ [\c!state=\v!start,
+ \c!autofile=\v!no,
+ \v!part\c!number=\v!yes,
+ \v!chapter\c!number=\v!no,
+ \c!interaction=\v!all,
+ \c!convertfile=\v!no,
+ %\c!strut=\v!no, % some day an option
+ \c!prefix=,
+ \c!width=.75\makeupwidth,
+ \c!left=\quotation\bgroup,
+ \c!right=\egroup,
+ \c!global=\v!no,
+ \c!expansion=\v!no,
+ \c!separator=\nonbreakablespace,
+ \c!export=\v!no]
+
+\setupurl
+ [\c!alternative=\v!both,
+ \c!space=\v!no,
+ \c!style=\v!type,
+ \c!color=]
+
+\setupprograms
+ [\c!directory=,
+ \c!alternative=\v!both,
+ \c!space=\v!no,
+ \c!style=\v!type,
+ \c!color=]
+
+\definereference [\v!CloseDocument ] [action(close)]
+\definereference [\v!ExitViewer ] [action(exit)]
+\definereference [\v!FirstPage ] [action(first)]
+\definereference [\v!LastPage ] [action(last)]
+\definereference [\v!NextJump ] [action(forward)]
+\definereference [\v!NextPage ] [action(next)]
+\definereference [\v!PauseMovie ] [action(pausemovie)]
+\definereference [\v!PauseSound ] [action(pausesound)]
+\definereference [\v!PauseRendering ] [action(pauserendering)]
+\definereference [\v!PreviousJump ] [action(backward)]
+\definereference [\v!PreviousPage ] [action(previous)]
+\definereference [\v!PrintDocument ] [action(print)]
+\definereference [\v!SaveForm ] [action(exportform)]
+\definereference [\v!LoadForm ] [action(importform)]
+\definereference [\v!ResetForm ] [action(resetform)]
+\definereference [\v!ResumeMovie ] [action(resumemovie)]
+\definereference [\v!ResumeSound ] [action(resumesound)]
+\definereference [\v!ResumeRendering ] [action(resumerendering)]
+\definereference [\v!SaveDocument ] [action(save)]
+\definereference [\v!SaveNamedDocument] [action(savenamed)]
+\definereference [\v!OpenNamedDocument] [action(opennamed)]
+\definereference [\v!SearchDocument ] [action(search)]
+\definereference [\v!SearchAgain ] [action(searchagain)]
+\definereference [\v!StartMovie ] [action(startmovie)]
+\definereference [\v!StartSound ] [action(startsound)]
+\definereference [\v!StartRendering ] [action(startrendering)]
+\definereference [\v!StopMovie ] [action(stopmovie)]
+\definereference [\v!StopSound ] [action(stopsound)]
+\definereference [\v!StopRendering ] [action(stoprendering)]
+\definereference [\v!SubmitForm ] [action(submitform)]
+\definereference [\v!ToggleViewer ] [action(toggle)]
+\definereference [\v!ViewerHelp ] [action(help)]
+\definereference [\v!HideField ] [action(hide)]
+\definereference [\v!ShowField ] [action(show)]
+\definereference [\v!GotoPage ] [action(gotopage)]
+\definereference [\v!GotoPage ] [action(gotopage)]
+\definereference [\v!Query ] [action(query)]
+\definereference [\v!QueryAgain ] [action(queryagain)]
+\definereference [\v!FitWidth ] [action(fitwidth)]
+\definereference [\v!FitHeight ] [action(fitheight)]
+\definereference [\v!ShowThumbs ] [action(thumbnails)]
+\definereference [\v!ShowBookmarks ] [action(bookmarks)]
+
+\definereference [\v!firstpage] [page(firstpage)]
+\definereference [\v!previouspage] [page(previouspage)]
+\definereference [\v!nextpage] [page(nextpage)]
+\definereference [\v!lastpage] [page(lastpage)]
+\definereference [\v!forward] [page(forward)]
+\definereference [\v!backward] [page(backward)]
+\definereference [\v!firstsubpage] [page(firstsubpage)]
+\definereference [\v!previoussubpage] [page(previoussubpage)]
+\definereference [\v!nextsubpage] [page(nextsubpage)]
+\definereference [\v!lastsubpage] [page(lastsubpage)]
+
+% we can do this but only when later in resolve (else problems with \chapter[first]{...}
+%
+% \definereference [\v!first] [page(firstpage)]
+% \definereference [\v!previous] [page(prevpage)]
+% \definereference [\v!next] [page(nextpage)]
+% \definereference [\v!last] [page(lastpage)]
+% \definereference [\v!first\v!sub] [page(firstsubpage)]
+% \definereference [\v!previous\v!sub] [page(prevsubpage)]
+% \definereference [\v!next\v!sub] [page(nextsubpage)]
+% \definereference [\v!last\v!sub] [page(lastsubpage)]
+
+%D We cannot set up buttons (not yet, this one calls a menu macro):
+
+%D New (and experimental):
+
+% \starttext
+% \chapter{test}
+% \placefigure[here][xx:1]{}{\framed{one}} \placefigure[here][xx:2]{}{\framed{three}}
+% \placetable [here][xx:3]{}{\framed{two}} \placetable [here][xx:4]{}{\framed{four}}
+% \start
+% \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
+% \stop \blank \start
+% \setupreferencestructureprefix[default][prefix=no]
+% \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
+% \stop \blank \start
+% \setupreferencestructureprefix[float][default][prefix=no]
+% \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
+% \stop \blank \start
+% \setupreferencestructureprefix[figure][default][prefix=no]
+% \in{fig}[xx:1] and \in{fig}[xx:2] \in{tab}[xx:3] and \in{tab}[xx:4]
+% \stop \blank
+% \stoptext
+
+\unexpanded\def\setupreferencestructureprefix
+ {\dotripleargument\dosetupreferencestructureprefix}
+
+\def\getreferencestructureprefix#1#2#3%
+ {{
+ prefix = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefix",
+ separatorset = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixseparatorset",
+ conversion = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixconversion",
+ conversionset = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixconversionset",
+ set = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixset",
+ segments = "\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixsegments",
+ connector = \!!bs\referencestructureprefixparameter{#1}{#2}{#3}\c!prefixconnector\!!es,
+ }}
+
+\unexpanded\def\setupreferencestructureprefix
+ {\dotripleempty\dosetupreferencestructureprefix}
+
+\def\dosetupreferencestructureprefix[#1][#2][#3]%
+ {\ifthirdargument
+ \getparameters[\??rf:\c!prefix:#1:#2][#3]%
+ \else\ifsecondargument
+ \getparameters[\??rf:\c!prefix::#1][#2]%
+ \fi\fi}
+
+\def\referencestructureprefixparameter#1#2#3#4% kind name category parameter
+ {\ifcsname\??rf:\c!prefix:#2:#3#4\endcsname
+ \csname\??rf:\c!prefix:#2:#3#4\endcsname
+ \else\ifcsname\??rf:\c!prefix:#1:#3#4\endcsname
+ \csname\??rf:\c!prefix:#1:#3#4\endcsname
+ \else\ifcsname\??rf:\c!prefix::#3#4\endcsname
+ \csname\??rf:\c!prefix::#3#4\endcsname
+ \fi\fi\fi}
+
+% \def\getreferencestructureprefixspec#1% we can save one call by moving this to the lua end
+% {\getreferencestructureprefix
+% {\ctxlua{jobreferences.get_current_metadata("kind")}}
+% {\ctxlua{jobreferences.get_current_metadata("name")}}
+% {#1}}
+% \def\currentreferencedefault
+% {\ctxlua{jobreferences.filter("default",\getreferencestructureprefixspec\v!default)}}
+%
+% this is shortcut for:
+
+\def\currentreferencedefault
+ {\ctxlua{jobreferences.filter("default",\ctxlua{jobreferences.get_current_prefixspec("\v!default")})}}
+
+\protect \endinput
+
+% tricky:
+%
+% \enabletrackers[nodes.references]
+% \setupinteraction[state=start]
+% \def\KnuthTest{\input knuth }
+% \def\KnuthTest{\input tufte }
+% \def\TufteTest{\input tufte }
+% \defineoverlay[xxx][\overlaybutton{page(3)}]
+% \setupbackgrounds[text][background=xxx]
+% \starttext
+% test {\red \KnuthTest} test \par
+% \button{test}[page(1)] \par
+% \goto{page 2 \TeX}[page(2)] \goto{page 2 \TeX}[page(2)] \goto{\TufteTest}[page(2)] test \page
+% test \goto{page 3}[page(3)] \goto{\TufteTest\space\par\TufteTest}[page(4)] test \page
+% \goto{page 1}[page(1)] \goto{\TufteTest\space test}[page(1)] \page
+% \goto{page 1}[page(1)] \goto{\KnuthTest\space test}[page(1)] \page
+% test \goto{page 1}[page(1)] {\goto{\KnuthTest\space test}[page(1)]} test
+% \goto{page 1}[page(1)] \goto{\TufteTest}[page(1)] test \page
+% \stoptext
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-03 21:42:07 +0000