Difference between revisions of "Command/goto"
(Created page with "Documentation for \goto") |
m (spelling issue) |
||
(One intermediate revision by one other user not shown) | |||
Line 1: | Line 1: | ||
<cd:commandgroup name="goto" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807"> | <cd:commandgroup name="goto" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807"> | ||
− | <cd:shortdesc> | + | <cd:shortdesc>The command <tt>\goto</tt> is used for clickable links |
− | The command <tt>\goto</tt> is used for | ||
</cd:shortdesc> | </cd:shortdesc> | ||
<cd:variants> | <cd:variants> | ||
Line 17: | Line 16: | ||
It takes two arguments, the first in curly braces is the text, the second in square braces is the label to link to. | It takes two arguments, the first in curly braces is the text, the second in square braces is the label to link to. | ||
− | You should not normally have to use this command. | + | You should not normally have to use this command for reference links inside your document. Internal links are better made using {{cmd|in}}, {{cmd|at}} or {{cmd|about}}, which are more conceptual (and lookup the section or page number as well). |
− | + | But if you want to implement some custom command for building links, this command is useful. You might also want to use the {{cmd|ref}} command for getting the raw page number, section number, section title, etc. | |
− | </cd:description> | + | Or if you want to create a clickable link to something outside of the current document. |
+ | |||
+ | {{todo|there are examples below of various possible arguments in #2, but not a proper list of options}}</cd:description> | ||
<cd:examples><cd:example title=""><context source="yes"> | <cd:examples><cd:example title=""><context source="yes"> | ||
\setupinteraction[state=start] | \setupinteraction[state=start] | ||
Line 30: | Line 31: | ||
Link to \goto{some text}[label:1]. | Link to \goto{some text}[label:1]. | ||
</context> | </context> | ||
− | (of course the wiki cannot really make a workable link)</cd:example><cd:example title=" | + | (of course the wiki cannot really make a workable link)</cd:example><cd:example title="Links to URLs"><texcode> |
\goto{Wiki}[url(http://wiki.contextgarden.net)] | \goto{Wiki}[url(http://wiki.contextgarden.net)] | ||
\goto{Email}[url(mailto:spam@example.com)] | \goto{Email}[url(mailto:spam@example.com)] | ||
− | </texcode></cd:example></cd:examples> | + | </texcode></cd:example><cd:example title="Link to a page"><texcode> |
+ | \goto{Other page}[page(3)] | ||
+ | </texcode></cd:example><cd:example title="Open a file or program"><texcode> | ||
+ | \goto{Start}[program(test.tex)] | ||
+ | </texcode> | ||
+ | |||
+ | By enclosing {{cmd|goto}}’s destination in <tt>program(#1)</tt> you | ||
+ | have some means of launching files or programs. | ||
+ | |||
+ | Of course, this is a security issue. | ||
+ | |||
+ | However, PDF readers seem to handle this inconsistently. | ||
+ | |||
+ | The following ''test.tex'' will attempt to open itself. | ||
+ | Notice that per default PDF readers stay in the current working | ||
+ | directory. | ||
+ | <texcode> | ||
+ | \setupinteraction[state=start] | ||
+ | \starttext | ||
+ | \goto{A file}[program(test.tex)]\par % case 1: destination specified | ||
+ | \goto{A command}[program(/usr/bin/kwrite test.tex)]\par % case 2: program and destination specified | ||
+ | \stoptext | ||
+ | </texcode> | ||
+ | |||
+ | ==== Behavioural study of PDF viewers ==== | ||
+ | |||
+ | This comparison was made on Linux/x86 and OSX 10.9.5 (replacing <tt>/usr/bin/kwrite test.tex</tt> with <tt>/Applications/Preview.app test.pdf</tt>). YMMV. | ||
+ | |||
+ | {|cellpadding="10" style="border:2px solid #eeeeee" | ||
+ | ! reader | ||
+ | ! version | ||
+ | ! behaviour | ||
+ | |- | ||
+ | | acroread | ||
+ | | 9.2, Linux/x86 | ||
+ | | ''Case 1'' succeeds. Runs the associated mime type application on the argument. | ||
+ | ''Case 2'' results in a file error. | ||
+ | |- | ||
+ | | Acrobat Reader DC | ||
+ | | 2017.009, OSX | ||
+ | | ''Case 1'' succeeds after asking back. Runs the default application for .tex files. | ||
+ | ''Case 2'' fails with a file not found message. | ||
+ | |- | ||
+ | | Acrobat Pro | ||
+ | | 9.5.5, OSX | ||
+ | | ''Case 1'' succeeds after asking back. Runs the default application for .tex files. | ||
+ | ''Case 2'' fails with a file not found message. | ||
+ | |- | ||
+ | | okular | ||
+ | | 0.11.2, Linux/x86 | ||
+ | | ''Case 1'' succeeds. Runs the associated mime type application on the argument. | ||
+ | ''Case 2'' fails. | ||
+ | Note that calling an executable (without the file argument) | ||
+ | will be prevented by Okular for safety reasons. | ||
+ | |- | ||
+ | | xpdf | ||
+ | | 3.02, Linux/x86 | ||
+ | | ''Case 1'' fails. | ||
+ | ''Case 2'' succeeds: Xpdf allows execution of arbitrary commands in a shell with user privileges. | ||
+ | |- | ||
+ | | Google Docs | ||
+ | | as of 2010-10-24 | ||
+ | | ''Case 1'' fails. | ||
+ | ''Case 2'' fails. | ||
+ | |- | ||
+ | | mupdf | ||
+ | | 7.2, Linux/x86 | ||
+ | | ''Case 1'' fails. | ||
+ | ''Case 2'' fails. | ||
+ | |- | ||
+ | | Preview.app | ||
+ | | 7.0, OSX | ||
+ | | ''Case 1'' fails (nothing happens). | ||
+ | ''Case 2'' fails with a file not found message. | ||
+ | |- | ||
+ | | File Viewer.app | ||
+ | | 1.4, OSX | ||
+ | | ''Case 1'' succeeds. Runs the default application for .tex files. | ||
+ | ''Case 2'' fails with a file not found message. | ||
+ | |- | ||
+ | | PDF.js | ||
+ | | Opera 49, Firefox 61, OSX | ||
+ | | Links are not active, nothing happens. | ||
+ | |}</cd:example></cd:examples> | ||
<cd:notes></cd:notes> | <cd:notes></cd:notes> | ||
<cd:seealso> | <cd:seealso> | ||
Line 40: | Line 124: | ||
<cd:commandref name="at"></cd:commandref> | <cd:commandref name="at"></cd:commandref> | ||
<cd:commandref name="in"></cd:commandref> | <cd:commandref name="in"></cd:commandref> | ||
− | <cd:commandref name="about"></cd:commandref></cd:seealso> | + | <cd:commandref name="about"></cd:commandref> |
+ | <cd:wikipage page="URL"></cd:wikipage> | ||
+ | <cd:commandref name="ref"></cd:commandref></cd:seealso> | ||
</cd:commandgroup> | </cd:commandgroup> |
Latest revision as of 19:38, 5 October 2023
Contents
\goto
Summary
Settings
Description
It takes two arguments, the first in curly braces is the text, the second in square braces is the label to link to.
You should not normally have to use this command for reference links inside your document. Internal links are better made using \in, \at or \about, which are more conceptual (and lookup the section or page number as well).
But if you want to implement some custom command for building links, this command is useful. You might also want to use the \ref command for getting the raw page number, section number, section title, etc.
Or if you want to create a clickable link to something outside of the current document.
TODO: there are examples below of various possible arguments in #2, but not a proper list of options (See: To-Do List) |
Examples
Example 1
\setupinteraction[state=start] \reference[label:1]{Some text} \page[yes] % Insert page break Link to \goto{some text}[label:1].
(of course the wiki cannot really make a workable link)
Links to URLs
\goto{Wiki}[url(http://wiki.contextgarden.net)] \goto{Email}[url(mailto:spam@example.com)]
Link to a page
\goto{Other page}[page(3)]
Open a file or program
\goto{Start}[program(test.tex)]
By enclosing \goto’s destination in program(#1) you have some means of launching files or programs.
Of course, this is a security issue.
However, PDF readers seem to handle this inconsistently.
The following test.tex will attempt to open itself. Notice that per default PDF readers stay in the current working directory.
\setupinteraction[state=start] \starttext \goto{A file}[program(test.tex)]\par % case 1: destination specified \goto{A command}[program(/usr/bin/kwrite test.tex)]\par % case 2: program and destination specified \stoptext
Behavioural study of PDF viewers
This comparison was made on Linux/x86 and OSX 10.9.5 (replacing /usr/bin/kwrite test.tex with /Applications/Preview.app test.pdf). YMMV.
reader | version | behaviour |
---|---|---|
acroread | 9.2, Linux/x86 | Case 1 succeeds. Runs the associated mime type application on the argument.
Case 2 results in a file error. |
Acrobat Reader DC | 2017.009, OSX | Case 1 succeeds after asking back. Runs the default application for .tex files.
Case 2 fails with a file not found message. |
Acrobat Pro | 9.5.5, OSX | Case 1 succeeds after asking back. Runs the default application for .tex files.
Case 2 fails with a file not found message. |
okular | 0.11.2, Linux/x86 | Case 1 succeeds. Runs the associated mime type application on the argument.
Case 2 fails. Note that calling an executable (without the file argument) will be prevented by Okular for safety reasons. |
xpdf | 3.02, Linux/x86 | Case 1 fails.
Case 2 succeeds: Xpdf allows execution of arbitrary commands in a shell with user privileges. |
Google Docs | as of 2010-10-24 | Case 1 fails.
Case 2 fails. |
mupdf | 7.2, Linux/x86 | Case 1 fails.
Case 2 fails. |
Preview.app | 7.0, OSX | Case 1 fails (nothing happens).
Case 2 fails with a file not found message. |
File Viewer.app | 1.4, OSX | Case 1 succeeds. Runs the default application for .tex files.
Case 2 fails with a file not found message. |
PDF.js | Opera 49, Firefox 61, OSX | Links are not active, nothing happens. |