Source Browser ?

1% language=us
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[mag-01,abr-02]
21
22\startbuffer[abstract]
23    The (cross) reference mechanism in \CONTEXT\ is rather complex (in terms of
24    code) and provides a lot of functionality. Of course one can ask for page
25    numbers, section numbers, titles, or arbitrary text, but also control the
26    viewer, go to locations and have chains of actions. In this document we only
27    discuss some aspects of cross document referencing. This is not a complete
28    manual.
29\stopbuffer
30
31\startdocument
32  [title={Cross document referencing},
33   author=Hans Hagen,
34   affiliation=PRAGMA ADE,
35   date=September 2011,
36   number=1103 \MKIV]
37
38\subject{Other documents}
39
40A straightforward way to refer to something in an other document is by prefixing
41the reference by a document tag. Take for instance:
42
43\startscite[tex]
44\in{chapter}[other::whatever]
45\stopscite
46
47Here, \type {other} is either a tag or a filename. In the case if a tag, you also
48need a definition like:
49
50\startscite[tex]
51\useexternalfile[other][somefilename]
52\stopscite
53
54Because we load the references of the other file (when present), you can also ask
55for titles of chapters. In fact, all the following work:
56
57\startscite[tex]
58\at      {page}[other::whatever]
59\in   {chapter}[other::whatever]
60\about         [other::whatever]
61\goto{location}[other::whatever]
62\stopscite
63
64given of course that in the other file we have set a reference:
65
66\startscite[tex]
67\startchapter[reference=whatever,title={Who cares}]
68  ...
69\stopchapter
70\stopscite
71
72In \MKIV\ this mechanisms has been extended to deal with products and components.
73In order not to get clashes between references in multiple chapters, you can do
74something like this:
75
76\startscite[tex]
77\setuphead[chapter][referenceprefix=whatever]
78\stopscite
79
80This will create a namespace for this chapter. A more automated alternative is:
81
82\startscite[tex]
83\setuphead[chapter][referenceprefix=+]
84\stopscite
85
86Here the given reference (\type {whatever}) will automatically become the
87namespace for that chapter.
88
89\subject{Products and components}
90
91This is however somewhat cumbersome when we deal with a project structure. There
92we have the complication that we can process components within a product and
93although one will only do this for proofing it makes sense at least to deal with
94references in other components.
95
96In the test suite there are four files demonstrating what is possible. They can
97be recognized by the name \type {cross-*.tex}. The product file \type {cross-100}
98includes two components:
99
100\startscite[tex]
101\startproduct cross-100
102
103    \component cross-001
104    \component cross-002
105
106\stopproduct
107\stopscite
108
109In these components there are references to the other component. The cross
110reference mechanism will automatically use the component's name as namespace but
111only when you say:
112
113\startscite[tex]
114\setupreferencing[autofile=yes]
115\stopscite
116
117A component looks as follows:
118
119\startscite[tex]
120\setupreferencing[autofile=yes]
121\setupinteraction[state=start]
122
123\startcomponent cross-001
124
125\product cross-100
126
127\startchapter[title=One,reference=one]
128  ...
129\stopchapter
130
131\stopcomponent
132\stopscite
133
134When a component is processed, the references of the product are also loaded.
135Actually, some more information fetched so that for instance the chapter number
136gets set as well as the page number.
137
138Of course this will not guarantee that all referencing turns out right, but it's
139better than nothing. There are now several ways to refer to something, and as we
140have quite some fallback heuristics in place all the following will work out
141well. However, keep in mind that when multiple \type {one}'s are uses you might
142end up with the wrong one when no prefix is given.
143
144\startscite[tex]
145\at      {page}[one]
146\in   {chapter}[one]
147\about         [one]
148\goto{location}[one]
149
150\at      {page}[cross-001:one]
151\in   {chapter}[cross-001:one]
152\about         [cross-001:one]
153\goto{location}[cross-001:one]
154
155\at      {page}[cross-001::one]
156\in   {chapter}[cross-001::one]
157\about         [cross-001::one]
158\goto{location}[cross-001::one]
159
160\at      {page}[cross-001:::one]
161\in   {chapter}[cross-001:::one]
162\about         [cross-001:::one]
163\goto{location}[cross-001:::one]
164\stopscite
165
166So what do the (subtle) differences in colons mean? The \type {cross-001:} prefix
167is just a prefix. Such a prefix is not always related to a document but it
168happens that when no other match is found, an extra check takes place to see if
169it is a component namespace. This is new per September 2011.
170
171The \type {cross-001::} prefix is the official way to refer to another document
172and this is no news. However, the \type {cross-001:::} prefix is new and
173depending on how the document is run, is either a regular namespace prefix (one
174colon) or an external reference (two colons). When you use the project structure
175this might be the best way to go. The reason is that order of looking (and
176fallbacks) is better defined this way.
177
178So, given that you have a proper usage of product and components, the following
179method is to be preferred:
180
181\startscite[tex]
182\at     {page}[other:::one] in \from[other]
183\in   chapter}[other:::one] of \from[other] (\about[other:::one])
184\goto{details}[other:::one]
185\stopscite
186
187Keep in mind that in most cases a combination of components and extra prefixes
188(that is, explicitly set prefixes) work ok. The prefixing mechanism is controlled
189with:
190
191\startscite[tex]
192\setupreferencing[prefix=blabla]
193\stopscite
194
195but you will seldom need this command. In order to prevent clashes you can best
196use some redundancy:
197
198\startscite[tex]
199\placefigure[here][fig:foo]{}{}{}
200\placetable [here][tab:foo]{}{}{}
201\stopscite
202
203works out quite well.
204
205\subject{Reference commands}
206
207In \MKII\ the main reference mechanism handled not only user references but also
208stored section numbers, section titles, captions and all that made sense to refer
209to. In \MKIV\ we carry around way more information and references are stored in
210and retrieved from several data structures. Although we keep much more
211information in memory and store more information in the auxiliary file, we save
212some too because now (for instance) section titles are stored only once.
213
214The following two commands store an explicit reference, unrelated to a structural
215component. However, with the page number we also store information about the
216current section so that we can add a prefix any time we want.
217
218\startscite[tex]
219\textreference[sometag]{some text}
220\pagereference[sometag]
221\stopscite
222
223Keep in mind that these commands insert a so called node so they can best be
224attached to some content in order not to dangle around and interfere with
225spacing. The following works okay:
226
227\startscite[tex]
228\dontleavehmode\textreference[ward]{Quoting Ward}\input ward
229\stopscite
230
231A rather low level (not interactive) fetching can be done as follows:
232
233\startscite[tex]
234\ref[text][sometag]
235\ref[page][sometag]
236\stopscite
237
238We already saw some more advanced commands to retrieve reference data:
239
240\startscite[tex]
241\at      {page}[one]
242\in   {chapter}[one]
243\about         [one]
244\goto{location}[one]
245\stopscite
246
247These commands will create a hyperlink when interactivity is turned on.
248
249The \type {\at} command typesets the page number and the \type {\in} command
250typesets a number. The \type {\about} command deals with the title. In the case
251of a regular reference the last two commands do a similar thing but the last one
252adds quotes (by default). The \type {\goto} command only has a meaning in
253interactive documents. It does not add anything to the text.
254
255In interactive mode all these commands will apply a so called contrast color in
256case the reference refers to the page itself.
257
258There are two commands that relate to current location:
259
260\startscite[tex]
261\somewere{before}{current}{after}[one]
262\atpage[one]
263\stopscite
264
265The first command typesets one of the three texts, which one depends of the
266typeset and referred \type {one} being on the same page. The second command
267generates a text automatically.
268
269Although not related to the kind of references we discuss here, you can define
270symbolic references with:
271
272\startscite[tex]
273\definereference[symbolic name][real reference]
274\resetreference[symbolic name]
275\stopscite
276
277Using this only makes sense in interactive documents where we can have special
278operations with arguments and combinations of such references.
279
280\subject{Reference formats}
281
282You can control the formatting of references in detail using the setup command.
283For instance you can tweak the way sections numbers are prefixed but as this
284relates to numbering this will not be discussed here. Reference formats are
285another way to control the rendering
286
287\startscite[tex]
288\definereferenceformat[informula]  [left=(,right=),text=formula]
289\definereferenceformat[informulas] [left=(,right=),text=formulas]
290\definereferenceformat[andformula] [left=(,right=),text=and]
291\definereferenceformat[andformulas][left=(,right=),text=and]
292
293\informula [b] and \informula [for:c]
294the \informula {formulas}[b] \informula {and} [for:c]
295the \informulas {formulas}[b] \informula {and} [for:c]
296the \informulas [b] \informula {en} [for:c]
297the \informulas [b] \andformula [for:c]
298\stopscite
299
300Instead of a text, one can specify a label, which should be defined with \type
301{\setuplabeltext}.
302
303\subject{User references}
304
305You can create user references too. This is done with the following command:
306
307\startscite[tex]
308\setreference[myref][key-1=value-1,key-2=value-2]
309\stopscite
310
311You can then ask for keys using:
312
313\startscite[tex]
314\getreference[myref][key-2]
315\stopscite
316
317In principle you can add filters and rendering variants as well using \LUA\ code
318but that is rather specialized and often not needed.
319
320\stopdocument
321