summaryrefslogtreecommitdiff
path: root/macros/generic/navigator
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/navigator
Initial commit
Diffstat (limited to 'macros/generic/navigator')
-rw-r--r--macros/generic/navigator/README27
-rw-r--r--macros/generic/navigator/navigator-doc.pdfbin0 -> 131223 bytes
-rw-r--r--macros/generic/navigator/navigator-doc.tex914
-rw-r--r--macros/generic/navigator/navigator.sty15
-rw-r--r--macros/generic/navigator/navigator.tex776
-rw-r--r--macros/generic/navigator/t-navigator.tex33
6 files changed, 1765 insertions, 0 deletions
diff --git a/macros/generic/navigator/README b/macros/generic/navigator/README
new file mode 100644
index 0000000000..a0a565eff2
--- /dev/null
+++ b/macros/generic/navigator/README
@@ -0,0 +1,27 @@
+This is the README file for the navigator package.
+Author: Paul Isambert.
+E-mail: zappathustra AT free DOT fr
+Comments and suggestions are welcome.
+Date: May 2016.
+Version: 1.1.
+
+Navigator offers access to PDF features such as:
+anchors, outlines (bookmarks), links and actions, embedded files, and raw PDF
+code. It works with all formats (some limitations in ConTeXt), and with
+pdfTeX, LuaTeX and XeTeX (i.e. xdvipdfmx), trying to implement a similar
+behavior between those drivers.
+
+It requires texapi and YaX, both v.1.03.
+
+Relevant information can be found in navigator-doc.pdf.
+
+
+The files in this distribution are:
+
+navigator.tex The bulk of the code.
+navigator.sty A wrapper file for LaTeX.
+t-navigator.tex A wrapper file for ConTeXt.
+navigator-doc.pdf The manual.
+navigator-doc.tex The source of the manual.
+
+Licensing of this package is covered by LPPL.
diff --git a/macros/generic/navigator/navigator-doc.pdf b/macros/generic/navigator/navigator-doc.pdf
new file mode 100644
index 0000000000..07f9a005d8
--- /dev/null
+++ b/macros/generic/navigator/navigator-doc.pdf
Binary files differ
diff --git a/macros/generic/navigator/navigator-doc.tex b/macros/generic/navigator/navigator-doc.tex
new file mode 100644
index 0000000000..b8c09bbbb4
--- /dev/null
+++ b/macros/generic/navigator/navigator-doc.tex
@@ -0,0 +1,914 @@
+\input pitex
+\input navigator
+
+\setparameter page:
+ left = 5cm
+ top = 3cm
+ hsize = 27pc
+ width = "\dimexpr 10cm + 27pc\relax"
+ baselineskip = 14pt
+
+\setparameter navigator:
+ author = "Paul Isambert"
+ title = "Navigator's documentation"
+ mode = bookmarks
+ layout = onecolumn
+ pre = "\longcolor{.8 .2 .2}"
+ post = \endlongcolor
+
+\def\longcolor#1#2\endlongcolor{%
+ \color{#1}{#2}%
+ }
+
+\setparameter font:
+ command = \mainfont
+ type = ttf
+ name = lucidastd
+ roman = ""
+ italic = i
+ bold = b
+ big = 15pt
+
+\setparameter font:
+ command = \codefont
+ type = ttf
+ name = lucon
+ roman = ""
+ features = ""
+
+\setparameter section:
+ font = "\sc\bf"
+ number = none
+ color = \comcolor
+
+\setparameter describebookmark:
+ meta = navigator
+ left = 12em
+
+\def\beforedescribe{%
+ \vskip-\lastskip
+ \vskip\baselineskip
+ \iflines1{}{\clearpage}%
+ \noindent
+ \bgroup\codefont
+ \hfuzz=\maxdimen}
+\def\afterdescribe{\par\egroup\noindent\ignorespaces}
+
+\def\desclap#1{\llap{#1\kern.25em}}
+
+\def\comcolor{.75 0 0}
+\def\attrcolor{.3 .3 .3}
+
+\def\describe#1#2.{%
+ \beforedescribe
+ \outline[meta = describebookmark]{3}[\commandtoname#1]{\noexpand#1}%
+ \desclap{\color{\comcolor}{\string#1}}#2%
+ \ifemptystring{#2}{\egroup\ignorespaces}{\afterdescribe}%
+ }
+
+\def\jumpcom#1{\jumplink{\commandtoname#1}{\com#1}\antigobblespace}
+
+\def\name{\arg{name}\antigobblespace}
+\def\code{\arg{code}\antigobblespace}
+
+\freedef\param#1{{\codefont#1}}
+\freedef\attr#1{{\codefont\color{\attrcolor}{#1}}}
+\freedef\value#1{{\codefont#1}}
+
+\def\describeattr#1#2(#3).{%
+ \beforedescribe
+ \outline[meta = describebookmark, italic]{4}{#1}%
+ \desclap{\attr{#1}}<\valueloop{}{#2 }> (\ifemptystring{#3}{No default}{Default: #3}.)%
+ \afterdescribe
+ }
+
+\newfornoempty\valueloop{1}#2 {%
+ \ifemptystring{#1}
+ {#2\passarguments{x}}
+ {\kern1pt\char"007C\kern1pt#2}%
+ }
+
+\newverbatim\verbatim
+ {\vskip\baselineskip
+ \codefont
+ \hfuzz=\maxdimen
+ \parindent=0pt\relax}
+ {\printverbatim
+ \vskip\baselineskip\removenextindent}
+
+\newblock*\description
+ {\it\rightskip=0pt plus 1fil\relax}{\par}
+
+\newblock*\values
+ {\parindent=0pt
+ \everypar{\getvalue}%
+ \getleftskip
+ }{\par}
+
+\def\getleftskip[#1]{\leftskip=#1\relax}
+\def\getvalue#1 {\llap{\value"#1"\kern.6em}}
+
+
+\gates def {headers}{%
+ \setbox255=\vbox to \dimexpr\outputsize+4\baselineskip{%
+ \box255
+ \vfil
+ \hbox to \hsize{\it\normalsize\hfil \the\pageno \hfil}}%
+ }
+
+
+\urlaction{pdf}{http://www.adobe.com/content/dam/Adobe/en/devnet/pdf/pdfs/PDF32000_2008.pdf}
+
+\def\tex{\TeX\antigobblespace}
+\def\pdftex{\scap{pdf}\tex}
+\def\luatex{Lua\kern-1pt\tex}
+\def\xetex{Xe\kern-1pt\tex}
+\def\navigator{\emph{Navigator}\antigobblespace}
+\pdfdef\navigator{Navigator}
+
+
+\bgroup
+
+\vbox to 4\baselineskip{%
+ \leftskip=0pt plus 1fil
+ \parfillskip=0pt \parindent=0pt
+ \vfil\obeylines
+ {\big\color{\comcolor}{\navigator}}\hfill Paul Isambert
+ \verb"zappathustra@free.fr"
+ 01/25/2010
+ }
+
+\egroup
+
+
+
+
+
+\section"Introduction"
+
+\navigator offers access to PDF features such as outlines (bookmarks), links,
+actions and embedded files; it differs from other existing packages on two
+main points: first, it doesn't depend on any format and can be used with plain
+\tex, La\tex, ConTeXt (with some limitations, see \jumplink{files}{here} and
+\jumplink{features}{here}), and anywhere else; second, it defines commands
+to create PDF objects, and can be used as a base to produce raw PDF
+code across \pdftex, \luatex and \xetex.
+
+Note that PDF is a description language, and that not all PDF viewers render
+it completely (not even Adobe Acrobat, actually); thus, some of the features
+in \navigator might seem to produce nothing when the file is read with a
+reader which doesn't fully support PDF. Fortunately, the most common and
+useful features, such as links and outlines, are generally supported.
+
+
+
+
+
+
+
+
+\section"Using \navigator"
+
+\navigator is loaded in the usual fashion, depending on the format:
+\verb"\usepackage{navigator}" in La\tex, \verb"\usemodule[navigator]" in
+Con\tex{}t, and \verb"\input navigator" anywhere else.
+
+\describe\finishpdffile.
+Some of \navigator's operations can take place only at the end of the file.
+These include producing the outline's hierarchy, sorting embedded files, and
+writing some information about the document. However, there are exceptions:
+first in La\tex and Con\tex{}t, this is done automatically (and for Con\tex{}t
+anyway file embedding document settings aren't properly supported; you can
+do what \navigator does with the Con\tex{}t core, though); second, even
+if you don't use La\tex or Con\tex t, in \xetex the outline hierarchy is
+built at once, so this command isn't needed unless you embed files or
+want to write some infos to the document's properties. Anyway the command
+can also be systematically issued harmlessly.
+
+
+
+
+
+
+\section"Anchors"[anchors]
+
+\description
+Anchors are positions used as the targets of links for navigation
+within a PDF file (they are called \emph"destinations" in PDF parlance).
+They are to be used in association with the \jumpcom\jumplink command
+or with \jumplink{outlines}{outlines}.
+\description/
+
+\describe\anchor\oarg{options}\name.
+This defines \name as an anchor. In vertical mode, the destination is were the
+command is issued; in horizontal mode, it also depends on the \attr"up" and \attr"left"
+attributes below. In both cases, however, the value of \attr"fit" might make a difference.
+The options that follow are also used in the \jumpcom\outline command
+when it defines an implicit anchor.
+
+\describeattr{up} dimension (\com\baselineskip).
+In horizontal mode, anchors are placed on the baseline; it means they send
+below the intended line (more precisely: with the intended line's baseline
+at the top of the screen). This attribute makes a vertical correction, so
+the intended line is shown.
+
+\describeattr{left} dimension (0pt).
+Similar to \attr"up", but in the horizontal direction (moving leftward).
+
+\describeattr{fit} xyz fit fith fitv fitb fitbh fitbv fitr (xyz).
+All anchors target the page where they appear (fortunately), but when
+jumping to an anchor how the page is displayed depends on this parameter.
+The values have the following effect:
+
+\values[4em]
+xyz
+The page is displayed so that the anchor is positioned at the
+upper-left corner of the window. Also, if \attr"zoom" is specified, it
+is enforced.
+
+fit
+The page is displayed so that it fits entirely in the window.
+
+fith
+Same as \value"fit", but only horizontally.
+
+fitv
+Same as \value"fit", vertically.
+
+fitb
+The page is displayed so that its bounding box fits entirely
+in the window. A page's bounding box is the smallest rectancle enclosing
+its contents (including headers and footers or marginal material, if any).
+
+fitbh
+Same as \value"fith" for the bounding box.
+
+fitbv
+Same as \value"fitv" for the bounding box.
+
+fitr
+Displays the page so that the box where the anchor appears
+fits entirely in the window. This is disabled with \xetex, and subtler
+things might be possible in the future.
+\values/
+
+\describeattr{zoom} number ().
+Sets the viewer's zoom when jumping to a destination. The number provided
+should be 1000 times the intended zoom (like magnification in \tex); hence
+\verb"zoom = 1000" is the normal magnification, i.e. a 100\%~zoom. The use
+of this attribute, as well as any value but \value"xyz" for the previous
+one, might be extremely annoying for the reader, because s/he might need
+to reset his or her zoom after each jump. (Most viewers implement \value"xyz"
+so that it performs its operation as best as possible without zooming; hence,
+unless the reader already uses a powerful zoom, the way the page is displayed
+is predictable.)
+
+\describe\anchorname\name.
+To avoid possible conflicts, \navigator tweaks the names you give it
+for anchors; if you ever need it, this command returns the real PDF
+names of the anchor you call \name.
+
+
+
+
+\section"Outlines (aka bookmarks)"[outlines]
+
+\description
+Don't hold it against me if I use the words \emph"outline" and
+\emph"bookmarks" alternatively. They are the same things, even
+though the command is \com\outline. There is no need for a second
+run to get bookmarks right.
+\description/
+
+\describe\outline\oarg{options}\arg{level}\oarg{name}\arg{title}.
+This creates a bookmark with title \arg{title}. In \luatex, \arg{title}
+is converted to UTF\nobreak-16 (in octal form, so \luatex doesn't
+complain), so you can use any character of Unicode (although the
+font used by your reader is very unlikely to display anything besides
+the basic plane). \xetex seems to spot the right encoding sometimes.
+As for \pdftex, no conversion is performed, so Latin-1 at best may
+succeed (the string is escaped nonetheless for characters with special
+meanings in PDF).
+
+The \arg{level} defines how the bookmark fits in the hierarchy. It
+is a number, and the smaller it is, the higher the bookmark. A bookmark
+is a child to the nearest preceding bookmark with a smaller \arg{level}.
+The following example illustrates that (hopefully):
+
+\verbatim
+\outline{1}{A chapter}
+ \outline{2}{A section}
+ \outline{3}{A subsection}
+ \outline{2}{Another section}
+\verbatim/
+
+Now, there is a difference between \pdftex and \luatex on the one hand
+and \xetex on the other. First, when using \xetex, \arg{level} should be an
+integer; no such restriction applies with the other engines. That means
+that if you suddenly want to insert a bookmark halfway between a chapter
+and a section in the hierarchy, you don't need to renumber everything:
+just assign a decimal number to it, for instance \verb"1.5" in the previous
+example. That is impossible with \xetex (which will ignore the decimal part,
+so it is also harmless). Second, with the latter engine, it is also impossible
+to skip levels, i.e. the following example isn't allowed:
+
+\verbatim
+\outline{1}{A chapter}
+ \outline{3}{A subsection}
+\verbatim/
+
+In that case, \xetex (i.e. \verb"xdvipdfmx") will insert an intermediate
+bookmark, called \verb"<No Title>", in red and italics (so you definitely
+can't miss it). With \pdftex and \luatex, since levels are a continuum,
+skipping a level doesn't make sense and the previous example is perfectly
+legitimate (however, if a section follows the subsection, its bookmark
+will appear at the same level as the subsection's). Finally, with all
+engines, \arg{level} can be zero or negative.
+
+Among the \arg{options}, those pertaining to a bookmark's appearance are:
+
+\describeattr{open} true false (false).
+If set to \verb"true", the bookmark diplays its immediate children.
+(You don't need to type `\verb"open = true"'; as with all other boolean
+attributes, `\verb"open"' suffices.)
+
+\describeattr{bold} true false (false).
+If \verb"true", the bookmark is displayed in a bold font.
+
+\describeattr{italic} true false (false).
+If \verb"true", the bookmark is displayed in an italic font (this is
+not incompatible with the previous attribute).
+
+\describeattr{color} {red green blue} (0 0 0, i.e. black).
+A triplet of numbers between between \verb"0" and \verb"1" setting
+the bookmark's color.
+
+\describeattr{outlinecolor} {red green blue} (0 0 0, i.e. black).
+Alias for \attr"color". (This name should be used when setting
+attributes globally in the \param"navigator" parameter or elsewhere.)
+
+\vskip\baselineskip
+By default, a bookmark creates an anchor, and clicking it jumps to the
+position thus defined. If the optional \arg{name} is present, then you
+can refer to that anchor and reuse it, as if you'd issued the \jumpcom\anchor
+command. Such an anchor, named or not, can take the same options
+as seen above for the \jumpcom\anchor command, for instance:
+
+\verbatim
+\outline[zoom = fith]{1}{A chapter}
+...
+ \outline[left = 2em]{2}[mysection]{A section}
+\verbatim/
+
+Two other options can modify a bookmark's behavior:
+
+\describeattr{anchor} name ().
+As just said, a bookmark creates an anchor. However, this is not true if
+this attribute is set; in this case, when clicked the bookmark sends
+to the anchor called \name, which need not be already defined,
+of course. The attributes pertaining to anchor settings, if any, are
+ignored, as is the optional name in the \com\outline command. In
+other words, the following two bookmarks are equivalent:
+
+\verbatim
+\outline[anchor = mydest, fit = fitv]{1}[aname]{A title}
+\outline[anchor = mydest]{1}{A title}
+\verbatim/
+
+\describeattr{action} name ().
+Like \attr"anchor", except the bookmark executes action \name
+(and doesn't send you anywhere). If both \attr"anchor" and \attr"action"
+are given, the former wins. See the section on \jumplink{actions}{actions}.
+
+\describe\pdfdef<command><parameter text>\string{replacement text\string}.
+Most of the commands used in \tex will yield nothing good in a bookmark's
+title. However, you may want to reuse the same text to set that title and,
+say, a section heading. When redefined with \com\pdfdef, \arg{command} will
+expand to \arg{replacement text}, but only in a bookmark's title. For
+instance, after:
+
+\verbatim
+\pdfdef\TeX{TeX}
+\pdfdef\emph#1{#1}
+\pdfdef\whatever{\noexpand\whatever}
+\verbatim/
+
+\com\TeX will produce ``\verb"TeX"'' in a bookmark, \com\emph will simply
+return its argument, and \com\whatever will represent itself. Note that
+unexpandable commands and \com\protected commands don't require any special
+treatment to represent themselves.
+
+
+
+
+\section"Links"[links]
+
+\description
+Links (and annotations more generally) are clickable zones of a PDF document,
+which trigger actions. \navigator offers a few types of links and actions,
+and also allows you to create your own with raw \jumplink{objects}{PDF objects}.
+The \arg{options} that appear in the commands below are described at
+\jumplink{options}{the end of this section}.
+\description/
+
+\describe\jumplink\oarg{options}\name\arg{text}.
+This prints \arg{text} and defines it as a clickable zone that sends to
+the anchor called \name (defined either with \jumpcom\anchor or \jumpcom\outline,
+although the anchor need not be already defined for the link to work,
+obviously). For instance, clicking \com\anchor or \com\outline in the
+previous parenthesis sends you to the page where those commands are defined.
+
+\describe\urllink\oarg{options}\arg{url}\arg{text}.
+This is the same thing as \com\jumplink,
+except the link sends to an internet resource (any URI works, actually).
+For instance:
+
+\verbatim
+\urllink[border = 1, color = 1 0 0, dash = 3 2]
+ {http://www.tug.org}{Go to TUG!}
+\verbatim/
+
+produces: \doverbatim\ If the \jumplink{uri}{uri} or
+\jumplink{base}{base} attributes in the \param"navigator"
+parameter are set, then \arg{url} can be relative.
+
+\describe\javascriptlink\oarg{options}\arg{JavaScript code}\arg{text}.
+A link which executes some JavaScript code (if the viewer can do that).
+For instance:
+
+\verbatim
+\javascriptlink[highlight = push]
+ {app.alert("Hello!")}{Say hello!}
+\verbatim/
+
+produces: \doverbatim
+
+\describe\actionlink\oarg{options}\name\arg{text}.
+This executes the action called \name. A named action is an action that is
+defined elsewhere in the document (not necessarily before) and given a name to
+refer to it. The \jumplink{actions}{next section} introduces two simple
+commands to create URL and JavaScript actions; however, an action is just a
+PDF object; hence, \name can be any valid PDF object (of the right type,
+obviously), and you can define such objects with the commands introduced in
+\jumplink{objects}{the last section} of this document. \navigator already
+defines four actions, namely: \actionlink{firstpage}{firstpage},
+\actionlink{lastpage}{lastpage}, \actionlink{prevpage}{prevpage} and
+\actionlink{nextpage}{nextpage}. The meaning should be obvious, but if you
+have any doubt, just click!
+
+\describe\rawactionlink\oarg{options}\arg{PDF code}\arg{text}.
+This is the same as \com\actionlink, except the action is defined
+not in an external action but in \arg{PDF code}, which should be
+an action dictionary (without the enclosing \verb"<<" and \verb">>",
+exactly as with \jumpcom\pdfdictobject).
+
+
+\vskip\baselineskip
+\noindent\anchor{options}%
+In the commands above, the \arg{options} are used to set the appearance
+of the links. Here are the ones you can set:
+
+\describeattr{border} number (0).
+The width (in PostScript points) of the border drawn around the link.
+Default \verb"0" means no border. (In \pdftex and \luatex, you can use
+the \com\pdflinkmargin primitive to set the distance between the link's
+border and its content, even if the border isn't drawn -- it makes
+the clickable zone larger.)
+
+\describeattr{color} {red green blue} (0 0 0, i.e. black).
+The color of the link's border, if any.
+
+\describeattr{linkcolor} {red green blue} (0 0 0, i.e. black).
+Alias for \attr"color". (This name should be used when setting
+attributes globally in the \param"navigator" parameter or elsewhere.)
+
+\describeattr{dash} numbers ().
+The dash pattern of the link's border, can you believe it? The
+\arg{numbers} should be \verb"a1 b1 a2 b2..." where \verb"a"'s
+specify visible parts of the border in PostScript points and
+\verb"b"'s specify hidden parts. Then the pattern repeats itself.
+More or less. (Set \attr"dash" to \verb"1"\nobreak\ \verb"0" if you want to
+override a default dash pattern.)
+
+\describeattr{highlight} none invert outline push (invert).
+This defines how the link flashes when clicked: \value"none" does
+nothing, \value"invert" inverts its colors, \value"outline" inverts
+its border's colors if any, and \value"push" gives the amazing illusion
+that the link is pushed below the surface of the page (says the
+author of the \ital{PDF reference}, except s/he didn't mention any
+amazing illusion).
+
+\describeattr{pre} code ().
+\tex code to be appended before \arg{text}.
+
+\describeattr{post} code ().
+\tex code to be appended after \arg{text}. This and \attr"pre"
+allows you to achieve coherent formatting of links. For instance:
+
+\verbatim
+\def\weblink{\urllink[pre = \bgroup\bf, post = \egroup]}
+Go to \weblink{http://www.tug.org}{TUG} and
+upload to \weblink{http://ctan.org}{CTAN}.
+\verbatim/
+
+produces:\doverbatim
+
+\describeattr{raw} {PDF code} ().
+Raw PDF code to be inserted in the link's dictionary.
+
+\describe\annotation\oarg{options}\arg{PDF code}\arg{text}.
+This creates an annotation tied to \arg{text}. \arg{PDF code} goes
+into the annotation's dictionary; note that the annotation thus created
+doesn't even have a \verb"Subtype" entry (a link, as described in this
+section, is one of the many subtypes of annotation). Depending on the
+\arg{options}, the \verb"Border" entry, the \verb"C" entry (for \attr"color")
+and the \verb"H" (for \attr"highlight") might be specified.
+
+\vskip\baselineskip
+\noindent
+There is one more type of action link, \jumpcom\openfilelink; it takes
+the same options as the commands described here, but it is introduced
+in the section on \jumplink{files}{embedded files}, because it is
+related to them.
+
+
+
+
+
+\section"Actions"[actions]
+
+\description
+The commands in this section allow you to create actions and
+refer to it somewhere else in your document. That is a convenient
+approach for actions that are used repeatedly. Note that the PDF
+file itself is also improved, because in it too actions thus defined
+appear only once.
+
+You might think that not much types of actions can be designed:
+only internet addresses and JavaScript. But those are only predefined
+patterns to be used even when one doesn't know anything about PDF.
+Other types of actions require that you write real PDF code, more precisely
+so-called action dictionaries; these are but dictionary objects,
+and \navigator allows you to create them with \jumpcom\pdfdictobject.
+Then the name you give to that object is a valid action name and can
+be used with \jumpcom\actionlink.
+
+In other words, there is no \com\whateveraction command, because
+that's what \jumpcom\pdfdictobject does.
+\description/
+
+\describe\urlaction\name\arg{url}.
+Defines \name as an action which sends to the address \arg{url} on
+the internet. (Actually, any URI can be used, not only URLs.)
+As with \jumpcom\urllink,
+if the \jumplink{uri}{uri} or \jumplink{base}{base} attributes
+in the \param"navigator" parameter are set, then \arg{url} can be relative.
+
+\describe\javascriptaction\name\arg{JavaScript code}.
+Defines \name as an action which executes \arg{JavaScript code}
+(if the viewer can do that).
+
+Thus the following are equivalent to the previous two examples
+with \com\urllink and \com\javascriptlink:
+
+\verbatim
+\urlaction {tug}{http://www.tug.org}
+\actionlink{tug}{Go to TUG!}
+
+\javascriptaction{hello}{app.alert("Hello!")}
+\actionlink{hello}{Say hello!}
+\verbatim/
+
+
+
+
+
+
+\section"Embedded files"[files]
+
+\description
+\navigator provides a simple command to embed files in a PDF document.
+Embedded file can also be opened with an action link, but only if they
+are PDF files. However, no proper support is offered for file embedding
+in Con\tex{}t.
+\description/
+
+\describe\embeddedfile\oarg{description}\arg{object name}\oarg{alternate filename}\arg{file}.
+This embeds \arg{file} in the current document; the name displayed by the viewer
+will be \arg{file} or \arg{alternate filename}, if used (do not forget the
+file's extension in that alternate name). The use of an alternate name
+is useful if \arg{file} contains a path.
+The viewer might also display an
+optional \arg{description}. (The command name \com\embeddedfile, cumbersome
+when compared to the more obvious \com\embedfile, is meant to avoid a possible
+conflict with Heiko Oberdiek's \verb"embedfile".)
+
+The command creates a \jumplink{objects}{PDF object} called \arg{object name}; its
+\verb"Type" is \verb"Filespec", and it points to another object of type
+\verb"EmbeddedFile" (containing the actual file). That object isn't used anywhere
+in \navigator for the moment, but it is available in case you need it, for instance
+when writing raw PDF.
+
+\describe\openfilelink\oarg{options}\arg{file}\oarg{page}\arg{text}.
+This is an action link, so see the description of the \jumplink{options}{\arg{options}}
+above. When clicked, it opens \arg{file} on page \arg{page}
+(first page if \arg{page} is omitted). That file should be embedded elsewhere
+in the document with \jumpcom\embeddedfile, and it should be a PDF file;
+\arg{file} should match the \arg{file} argument in \com\embeddedfile,
+or \arg{alternate filename} if given.
+
+
+
+
+
+
+\section{Settings}[settings]
+
+\description
+Many of the commands introduced in the previous sections can take options.
+If an option is not given, its default value is used instead; you may
+want to set those default values, and to do so you have to change the
+attributes of the \param"navigator" parameter:
+\description/
+
+\verbatim
+\setparameter navigator:
+ <attribute> = <value>
+ <attribute> = <value>
+...
+\par
+\verbatim/
+
+This is the \urllink{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=yax}{YaX}
+syntax , it is a little bit special, and if you don't want to learn it the
+traditional comma-separated list is also possible:
+
+\verbatim
+\setparameterlist{navigator}
+ {<attribute> = <value>,
+ <attribute> = <value>...}
+\verbatim/
+
+(If a \arg{value} is \verb"true" it can be omitted.)
+Learning YaX might still be a good idea, though, since then you can
+use the \verb"meta" attribute, which wasn't shown when the options for
+the commands above were explained, because it can be used anywhere.
+For instance:
+
+\verbatim
+\setparameterlist{mylink1}
+ {meta = navigator,
+ color = 1 0 0}
+\setparameterlist{mylink2}
+ {meta = navigator,
+ color = 0 1 0}
+...
+\actionlink[meta = mylink1]{...}{...}
+\actionlink[meta = mylink2]{...}{...}
+\verbatim/
+
+There you define two types of links, and you can change their settings
+at once by changing the parameters \param"mylink1" and \param"mylink2"
+instead of the links themselves (which might be numerous). Note how
+\param"mylink1" and \param"mylink2" define \param"navigator" as the
+meta-parameter. That is not necessary, but the action links wouldn't inherit
+your global default settings otherwise (unless the meta-parameter of
+\param"mylink1" and \param"mylink2" itself had \param"navigator" as its
+meta-parameter, or a meta-parameter which... got it?). The \verb"navigator"
+parameter itself can have a meta-attribute too.
+
+\vskip\baselineskip
+\noindent
+At last, here are the attributes that can be set (some make sense in individual
+commands only, and not in the \param"navigator" parameter, but
+you can still set them):
+
+\vskip\baselineskip
+\noindent
+\attr"up", \attr"left", \attr"fit", \attr"zoom":
+see the \jumplink{anchors}{section on anchors} (note that they also
+affect \jumplink{outlines}{outlines} when outlines create implicit anchors).
+
+\vskip\baselineskip
+\noindent
+\attr"outlinecolor", \attr"open", \attr"bold", \attr"italic", \attr"action", \attr"anchor":
+those are options for \jumplink{outlines}{outlines}. (In a given outline, one
+can use the \attr"color" attribute instead of \attr"outlinecolor"; in the \param"navigator"
+parameter, however, one should use only the latter.)
+
+\vskip\baselineskip
+\noindent
+\attr"border", \attr"linkcolor", \attr"highlight", \attr"dash", \attr"raw", \attr"pre", \attr"post":
+those affect \jumplink{links}{action links}. (The remark on \attr"outlinecolor"
+above holds for \attr"linkcolor" here.)
+
+\vskip\baselineskip
+\noindent\anchor{features}%
+And here are attributes that aren't associated with commands, but instead
+specify options and pieces of information for the entire document.
+Note that they do not work in Con\tex{}t, but that can be done easily
+without \navigator.
+
+\describeattr{author} string ().
+The author of the document. This shows up in the document's properties.
+The string is dealt with as described for an \jumpcom\outline's title.
+
+\describeattr{title} string ().
+Same as \attr"author", with the document's title.
+
+\describeattr{keywords} string ().
+Same thing again, with keywords.
+
+\describeattr{subject} string ().
+One more time for the world, this time with the subject addressed by your document.
+
+\describeattr{date} date (current date).
+The creation date; the date should be formatted as explained in the \actionlink{pdf}{\ital"PDF Reference"},
+so have fun. Anyway that is set automatically by \tex (and can't be set with \xetex).
+
+\describeattr{moddate} date (current date).
+Same as \attr"date", for the modification date.
+
+\describeattr{creator} string (TeX).
+The software that produced the document's original format.
+
+\describeattr{producer} string (\pdftex, \luatex or \xetex).
+The software that turned the original document into PDF (cannot be set with \xetex).
+
+\describeattr{rawinfo} {PDF code} ().
+Entries you want to add by yourself to the document's \verb"Info" dictionary.
+
+\describeattr{layout} onepage onecolumn twopage twocolumn twopage* twocolumn* ().
+This sets how the document should be displayed when opened:
+
+\values[6em]
+onepage
+The window displays only one page, with no continuous transition to the next one.
+
+onecolumn
+The window displays only one page, with a continuous transition to the next.
+
+twopage
+The window displays two pages, odd-numbered pages on the right,
+without a continuous transition.
+
+twocolumn
+Same as \value"twopage" with a continuous transition.
+
+twopage*
+Same as \value"twopage" with odd-numbered pages on the left.
+
+twocolumn*
+Same as \value"twopage*" with a continuous transition.
+\values/
+
+\describeattr{mode} outlines bookmarks thumbnails thumbs attachments files oc ().
+This sets what panel the reader should display when the document is
+opened:
+
+\values[6em]
+outlines
+The reader shows the document's outlines.
+
+bookmarks
+Same as \value"outlines".
+
+thumbnails
+Thumbnail images are shown.
+
+thumbs
+Same as \value"thumbnails".
+
+attachments
+Show the attached files.
+
+files
+Same as \value"attachments".
+
+oc
+The Optional Content Group panel is displayed; quite useless
+if you don't have any OCG's (\navigator might offer support one day).
+\values/
+
+\describeattr{uri} address ().
+\anchor[up = 2\baselineskip]{uri}%
+The base address that will be used with relative references.
+See \jumpcom\urllink and \jumpcom\urlaction.
+
+\describeattr{base} address ().
+\anchor[up = 2\baselineskip]{base}%
+Alias for \attr"uri".
+
+\describeattr{openaction} name ().
+The \name of the \jumplink{actions}{action} to be performed
+when the document is opened.
+
+\describeattr{rawcatalog} {PDF code} ().
+Raw PDF code to be added to the document's catalog.
+
+
+
+
+
+
+
+
+\section"PDF objects"[objects]
+
+\description
+Here are commands that let you create and use PDF objects (and which
+\navigator actually uses internally). Of course they are useless unless
+you know how PDF works (if you do, then you might note that what I call
+here \emph"objects" actually are \emph"indirect objects").
+
+Named actions used with \jumpcom\actionlink being objects, they
+behave as any other object with the commands below; for one thing, they
+respond positively to \jumpcom\ifpdfobject, and you can't create an object
+with the same name.
+\description/
+
+\describe\pdfobject\name\code.
+Creates a raw PDF object with name \name. There shouldn't already exist an
+object with the same name (unless it is just reserved).
+
+\describe\pdfdictobject\name\code.
+Same as \com\pdfobject, except a dictionary object is created. This
+command is totally equivalent to the previous one with \code enclosed between
+\verb"<<" and \verb">>". With this you can write custom named actions,
+i.e. \name can be used with \jumpcom\actionlink.
+
+\describe\pdfstreamobject\oarg{raw code}\name\arg{stream}.
+Creates a PDF stream object, with optional \arg{raw code} added to the
+dictionary.
+
+\describe\pdffileobject\oarg{raw code}\name\arg{file}.
+Same as \com\pdfstreamobject, except the stream is the contents of
+\arg{file}.
+
+\describe\pdfreserveobject\name.
+Reserves an object with name \name. That is totally useless (but harmless too)
+with \xetex. In \pdftex and \luatex, it is needed to refer to an object that
+isn't created yet.
+
+\describe\pdfensureobject\name.
+If \name isn't an object (reserved or created), this command reserves it.
+Otherwise it does nothing.
+
+\describe\pdfobjectnumber\name.
+Returns the number of object \name (which must be reserved at least). In \xetex,
+it actually returns nothing, because you can't use object numbers there,
+but fortunately in \pdftex and \luatex it isn't very useful either; the next
+command is much more interesting. (If \name doesn't exist, this command returns
+\verb"0"; an object can't have number \verb"0" in PDF, but that makes more
+sense than returning an error message, which would never make it to the terminal
+and spoil the PDF file instead.)
+
+\describe\pdfrefobject\name.
+Makes an indirect reference to object \name. For instance:
+
+\verbatim
+\urlaction{tug}{http://www.tug.org}
+\verbatim/
+
+and then somewhere while writing PDF code:
+
+\verbatim
+/A \pdfrefobject{myobj}
+\verbatim/
+
+(As with \com\pdfobjectnumber, if \name doesn't exist, i.e. it hasn't been
+reserved or created, this command returns \verb"0 0 R", an impossible object
+that is better than an error message. With \xetex, though, the reference is
+made anyway.)
+
+\describe\pdfobjectstatus\name.
+Returns \verb"0" if \name isn't an object, \verb"1" if it is a reserved object and
+\verb"2" if the object has been created.
+
+\describe\ifpdfobject\name\arg{true}\arg{false}.
+Executes \arg{true} if \name is an object (reserved or created) and \arg{false}
+otherwise.
+
+\describe\pdfstring\arg{string}.
+This transforms \arg{string} into a valid PDF string: in \xetex this
+actually does nothing, whereas in \pdftex the string is escaped, and
+in \luatex it is converted to UTF-16 in octal form. Note that this operation
+is already performed in a bookmark's title, in the description of an
+embedded file, in \jumpcom\javascriptaction and in various attributes
+of the \param"navigator" parameter,
+so you shouldn't use it there; it might be otherwise useful when writing raw PDF code.
+
+
+\vskip0pt plus 1filll
+
+\bgroup
+\leftskip=0pt plus 1fill
+\it\obeylines
+Typeset with LuaTeX v.0.66
+in Lucida and Lucida Console
+(Charles Bigelow and Kris Holmes)
+\egroup
+
+
+\finishpdffile
+\bye
diff --git a/macros/generic/navigator/navigator.sty b/macros/generic/navigator/navigator.sty
new file mode 100644
index 0000000000..3045208d8a
--- /dev/null
+++ b/macros/generic/navigator/navigator.sty
@@ -0,0 +1,15 @@
+% This is navigator.sty, a style file to load
+% the Navigator package in LaTeX. Useful information
+% can be found in navigator-doc.pdf
+%
+% Author: Paul Isambert.
+% E-mail: zappathustra AT free DOT fr
+% Comments and suggestions are welcome.
+% Date: May 2016.
+
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{navigator}[2016/22/05 v.1.1 PDF links, outlines, etc.]
+\chardef\formatnumber=4
+\input navigator.tex
+\AtEndDocument{\finishpdffile}
+\endinput
diff --git a/macros/generic/navigator/navigator.tex b/macros/generic/navigator/navigator.tex
new file mode 100644
index 0000000000..67064606e9
--- /dev/null
+++ b/macros/generic/navigator/navigator.tex
@@ -0,0 +1,776 @@
+% This is the Navigator package.
+% Relevant information can be found in navigator-doc.pdf
+%
+% Author: Paul Isambert.
+% E-mail: zappathustra AT free DOT fr
+% Comments and suggestions are welcome.
+% Date: January 2011.
+
+\ifdefined\NavigatorHasAlreadyBeenLoadedMyDear
+ \expandafter\endinput
+\fi
+\let\NavigatorHasAlreadyBeenLoadedMyDear\relax
+
+\input yax
+\ifdim\yaxversion pt<1.03pt
+ \senderror{Navigator}{YaX should be at least version 1.03. I quit}%
+ \expandafter\endinput
+\fi
+
+\ifnum\texenginenumber>1
+ \lettocs\ifpdforluatex{iftrue}
+\else
+ \letcstocs{ifpdforluatex}{iffalse}
+\fi
+\newsyntax#1:#2;{nav@}
+\setcatcodes{_@=11}
+\def\nav@error#1{\senderror{Navigator}{#1}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%% Strings %%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\ifcase\texenginenumber
+\or
+% XeTeX: we do nothing. Under some circumstances,
+% xdvipdfmx writes a good UTF-16 string.
+\let\pdfstring\unbrace
+
+\or
+% PDFTeX: we escape the string.
+\let\pdfstring\pdfescapestring
+
+\or
+% LuaTeX: the string is converted from UTF-8 to
+% UTF-16, and expressed in octal form (otherwise LuaTeX
+% would complain about non-UTF-8 characters). Hexadecimal
+% strings may be better, but \pdfoutline encloses the title
+% between braces, whereas hexadecimal strings should be
+% enclosed between "<" and ">".
+%
+% The UTF-16 conversion covers the entire Unicode range,
+% because one has the right to use Linear-B or musical notations
+% in a bookmark, but the viewer is very unlikely to display
+% anything beside the basic plane (unless one can change
+% the UI's font).
+
+% One could use a catcode table for this, but I don't think
+% it's worth it.
+{\catcode`\_=0
+\catcode`\\=12
+_gdef_navbackslash{\}}
+
+\bgroup
+\catcode`\%=12
+\directlua{
+local function to8 (...)
+ local arg, str = {...}, ""
+ for _, num in ipairs(arg) do
+ str = str .. string.format("\noexpand\\navbackslash%.3o", num)
+ end
+ return str
+end
+function toutf16(str)
+ local result = ""
+ for c in string.utfvalues(str) do
+ if c < 0x10000 then
+ result = result .. to8(c / 256, c % 256)
+ else
+ c = c - 0x10000
+ local a, b = c / 1024 + 0xD800, c % 1024 + 0xDC00
+ result = result .. to8(a / 256, a % 256, b / 256, b % 256)
+ end
+ end
+ tex.print([[\noexpand\navbackslash376\noexpand\navbackslash377]] .. result)
+end
+}
+\egroup
+
+\long\def\pdfstring#1{%
+ \directlua{toutf16("\luaescapestring{#1}")}%
+ }
+
+\fi
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%% Object creation %%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def\pdfobjectstatus#1{%
+ \ifcs{nav@pdfobject:#1}
+ {\ifcs{nav@pdfobject_used:#1}{2}{1}}
+ {0}%
+ }
+
+\def\ifpdfobject#1{%
+ \ifcs{nav@pdfobject:#1}%
+ }
+
+\def\pdfobject#1#2{%
+ \nav@pdfobject{}{}[]{#1}{#2}%
+ }
+
+\def\pdfdictobject#1#2{%
+ \nav@pdfobject{}{}[]{#1}{<< #2 >>}%
+ }
+
+\def\pdfstreamobject{%
+ \ifnext[
+ {\nav@pdfobject{stream}{}}
+ {\nav@pdfobject{stream}{}[]}%
+ }
+
+\def\pdffileobject{%
+ \ifnext[
+ {\nav@pdfobject{stream}{file}}
+ {\nav@pdfobject{stream}{file}[]}%
+ }
+
+\ifpdforluatex
+
+\def\nav@pdfobject#1#2[#3]#4#5{%
+ \ifnum\pdfobjectstatus{#4}=2
+ \nav@error{There already exists an object named `#4'}%
+ \else
+ \immediate\pdfobj
+ \ifnum\pdfobjectstatus{#4}=1 useobjnum \pdfobjectnumber{#4}\fi
+ #1 % "stream" or nothing.
+ \reverse\iffemptystring{#3}{attr {#3} }% "attr {...}" or nothing.
+ #2 % "file" or nothing.
+ {#5}% Contents.
+ \ifnum\pdfobjectstatus{#2}=0
+ \xdefcs{nav@pdfobject:#4}{\the\pdflastobj}%
+ \fi
+ \global\letcs{nav@pdfobject_used:#4}\relax
+ \fi
+ }
+
+\def\pdfreserveobject#1{%
+ \ifcase\pdfobjectstatus{#1}
+ \pdfobj reserveobjnum
+ \xdefcs{nav@pdfobject:#1}{\the\pdflastobj}%
+ \or
+ \nav@error{Object `#1' is already reserved}%
+ \or
+ \nav@error{Object `#1' is already in use}%
+ \fi
+ }
+
+% An error message here wouldn't reach the terminal
+% but would spoil the PDF file instead; therefore
+% I prefer to return an unexisting (and impossible)
+% object with number 0.
+
+\def\pdfobjectnumber#1{%
+ \ifcs{nav@pdfobject:#1}
+ {\usecs{nav@pdfobject:#1}}
+ {0}%
+ }
+
+\def\pdfrefobject#1{%
+ \ifcs{nav@pdfobject:#1}
+ {\usecs{nav@pdfobject:#1} 0 R}
+ {0 0 R}%
+ }
+
+\else
+
+\def\nav@pdfobject#1#2[#3]#4#5{%
+ \ifnum\pdfobjectstatus{#4}=2
+ \nav@error{There already exists an object named `#4'}%
+ \else
+ \special{pdf:
+ \ifemptystring{#1}
+ % No matter whether the object has been reserved,
+ % it doesn't mean anything with xdvipdfmx.
+ {obj \pdfrefobject{#4} #5}
+ {\ifemptystring{#2}{stream}{fstream}
+ \pdfrefobject{#4} (#5)
+ \reverse\iffemptystring{#3}{<< #3 >>}}}%
+ % Useless. But so the same behavior can be expected
+ % no matter the driver.
+ \global\defcs{nav@pdfobject:#4}{@nav_#4}%
+ \global\letcs{nav@pdfobject_used:#4}\relax
+ \fi
+ }
+
+\def\pdfreserveobject#1{%
+ \ifcase\pdfobjectstatus{#1}
+ % We do absolutely nothing except register the object
+ % as ``reserved''.
+ \xdefcs{nav@pdfobject:#1}{@nav_#1}%
+ \or
+ % Stupid, but then the same behavior can be expected
+ % across engines.
+ \nav@error{Object `#1' is already reserved}%
+ \or
+ \nav@error{Object `#1' is already in use}%
+ \fi
+ }
+
+% We can't do anything meaningful here, so we do nothing.
+\def\pdfobjectnumber#1{}
+
+% With XeTeX, referencing of unreserved
+% object is allowed, because reserving objects is
+% dummy behavior anyway. Thus, rather than returning
+% an unexisting 0 object, at least there exists the
+% possibility that the object will be created later,
+% even if it hasn't been reserved yet.
+\def\pdfrefobject#1{@nav_#1}
+
+\fi
+
+\def\pdfensureobject#1{%
+ \ifpdfobject{#1}{}{\pdfreserveobject{#1}}%
+ }
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%% Anchors %%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% REMARK
+%
+% Here and elsewhere, \usevalueor (or similar) is used (with a default
+% value as the or-part), because the user might do something like:
+%
+% \setparameter param:
+% up = 12pt
+%
+% \anchor[meta = param]{foo}
+%
+% Then there is no value for the "left" attribute, since "param"
+% doesn't have "navigator" (which holds the user's default values)
+% as a meta-parameter.
+% If no meta is detected, "navigator" is assigned to meta.
+
+\def\nav@prepare_options#1#2{%
+ \setparameterlist{nav@temp}[#1]{#2}%
+ \nav@ifattribute nav@temp:meta;
+ {}{\nav@setattribute nav@temp:meta; = navigator }%
+ }
+
+\def\anchor{%
+ \ifnext[
+ {\nav@anchor}
+ {\nav@anchor[]}%
+ }
+
+\def\nav@anchor[#1]#2{%
+ \ifcs{nav@pdfanchor:#2}
+ {\nav@error{Anchor `#2' already exists}}
+ {\global\letcs{nav@pdfanchor:#2}\relax
+ \nav@prepare_options{\gobbleone}{#1}%
+ \nav@anchor_position{#2}%
+ \deleteparameter nav@temp:}%
+ }
+
+\def\nav@anchor_position#1{%
+ \ifvmode
+ \nav@passvalueand{\nav@anchor_pass{nav@pdfanchor:#1}}nav@temp:fit;{{\nav@usevalue nav@temp:zoom;}}
+ {\nav@anchor_pass{nav@pdfanchor:#1}{xyz}{}}%
+ \else
+ \vbox to 0pt{\vss
+ \vbox to \nav@usevalueor nav@temp:up;{\baselineskip}{%
+ \hbox to 0pt{%
+ \kern-\nav@usevalueor nav@temp:left;{0pt}%
+ \nav@passvalueand{\nav@anchor_pass{nav@pdfanchor:#1}}nav@temp:fit;{{\nav@usevalue nav@temp:zoom;}}
+ {\nav@anchor_pass{nav@pdfanchor:#1}{xyz}{}}\hss}\vss}}%
+ \fi
+ }
+
+\def\nav@anchor_pass#1#2#3{%
+ \lowercase{\nav@anchor_create{#2}}{#1}{#3}%
+ }
+
+\ifpdforluatex
+
+\def\nav@anchor_xyz #1{xyz zoom 0#1}
+\def\nav@anchor_fit #1{fit}
+\def\nav@anchor_fith #1{fith}
+\def\nav@anchor_fitv #1{fitv}
+\def\nav@anchor_fitb #1{fitb}
+\def\nav@anchor_fitbh #1{fitbh}
+\def\nav@anchor_fitbv #1{fitbv}
+\def\nav@anchor_fitr #1{fitr}
+
+\def\nav@anchor_create#1#2#3{%
+ \pdfdest name {#2} \ifcs{nav@anchor_#1}{\usecs{nav@anchor_#1}{#3}}{xyz}%
+ }
+
+\else
+
+% FitR is quite unusable with xdvipdfm.
+{\setcatcodes{pt=12}\gdef\noPT#1pt{#1}}
+\def\nav@anchor_xyz #1{XYZ @xpos @ypos \expandafter\noPT\the\dimexpr0#1pt/1000\relax}
+\def\nav@anchor_fit #1{Fit}
+\def\nav@anchor_fith #1{FitH @ypos}
+\def\nav@anchor_fitv #1{FitV @xpos}
+\def\nav@anchor_fitb #1{FitB}
+\def\nav@anchor_fitbh #1{FitBH @ypos}
+\def\nav@anchor_fitbv #1{FitBV @xpos}
+
+\def\nav@anchor_create#1#2#3{%
+ \special{pdf: dest (#2)
+ [ @thispage /\ifcs{nav@anchor_#1}{\usecs{nav@anchor_#1}{#3}}{XYZ} ]
+ }%
+ }
+
+\fi
+
+\def\anchorname#1{%
+ nav@pdfanchor:#1%
+ }
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%% Outlines %%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def\nav@pdfdef_list{}
+\def\pdfdef#1{%
+ \global\addright\nav@pdfdef_list{#1}%
+ \gdefcs{nav@pdfdef:\commandtoname#1}%
+ }
+
+\newfor\nav@pdfdef_loop#1{%
+ \lettocs#1{nav@pdfdef:\commandtoname#1}%
+ }
+
+\def\outline{%
+ \ifnext[
+ {\nav@outline}
+ {\nav@outline[]}%
+ }
+
+\def\nav@outline[#1]#2{%
+ \ifnext[
+ {\nav@outline_do{#1}{#2}}
+ {\nav@outline_do{#1}{#2}[]}%
+ }
+
+\newcount\nav@outline_count
+\ifpdforluatex
+
+\def\nav@outline_do#1#2[#3]#4{%
+ \global\advance\nav@outline_count 1
+ \gdefcs{nav@outline_\the\nav@outline_count:specs}{#1,}%
+ \gdefcs{nav@outline_\the\nav@outline_count:level}{#2}%
+ \gdefcs{nav@outline_\the\nav@outline_count:title}{#4}%
+ \nav@prepare_options{\gobbleone}{#1}%
+ \nav@outline_getaction{#1}{#3}%
+ % It'd be simpler to create one action object anyway and let \nav@outline_n:action
+ % refer to it; but then I'd have to use the /NoAction trick (in \nav@outline_getaction), which not all
+ % viewers understand; at least here outlines with destinations work.
+ \global\xdefcs{nav@outline_\the\nav@outline_count:action}{<< \nav@temp >>}%
+ \deleteparameter nav@temp:%
+ }
+
+\def\nav@processoutlines{%
+ \bgroup
+ \passexpanded\nav@pdfdef_loop\nav@pdfdef_list
+ \nav@processoutlines_loop{1}%
+ \egroup
+ }
+
+\newwhile\nav@processoutlines_loop1{#1+1}
+ {\straightenif{ifnum}{\numexpr#1>\nav@outline_count}
+ {\breakwhile{}}
+ {\nav@processoutlines_subloop{#1+1}{#1}{}{0}}%
+ }
+
+\newwhile\nav@processoutlines_subloop4{#1+1}{#2}{#3}{#4}
+ {\straightenif{ifnum}{\numexpr#1>\nav@outline_count}
+ {\breakwhile{\nav@processoutlines_create{#2}{#4}}}
+ {\straightenif{ifdim}{\usecs{nav@outline_\the\numexpr#2:level}pt<\usecs{nav@outline_\the\numexpr#1:level}pt\relax}
+ {\ifemptystring{#3}
+ {\changewhile{#1+1}{#2}{#1}{#4+1}}
+ {\reverse\straighteniff{ifdim}{\usecs{nav@outline_\the\numexpr#3:level}pt<\usecs{nav@outline_\the\numexpr#1:level}pt\relax}
+ {\changewhile{#1+1}{#2}{#1}{#4+1}}}}
+ {\breakwhile{\nav@processoutlines_create{#2}{#4}}}}%
+ }
+
+\def\nav@processoutlines_create#1#2{%
+ \passexpandedcs{\nav@prepare_options{}}{nav@outline_\the\numexpr#1:specs}%
+ \pdfoutline
+ attr {\nav@outline_attributes}
+ user {\usecs{nav@outline_\the\numexpr#1:action}}
+ count \nav@ifvalue nav@temp:open; = true {}{-}\numexpr#2\relax {\pdfstring{\usecs{nav@outline_\the\numexpr#1:title}}}%
+ \deleteparameter nav@temp:%
+ }
+
+\else
+%
+% So much simpler because xdvipdfmx deals with children
+% automatically; thus \nav@processoutlines is unnecessary.
+%
+
+\let\nav@processoutlines\relax
+
+\def\nav@outline_do#1#2[#3]#4{%
+ \global\advance\nav@outline_count 1
+ \nav@prepare_options{\gobbleone}{#1}%
+ \nav@outline_getaction{#1}{#3}%
+ \bgroup
+ \passexpanded\nav@pdfdef_loop\nav@pdfdef_list
+%
+ \special{pdf: out
+ [\nav@ifvalue nav@temp:open;=true {}{-}] #2
+ << /Title (#4)
+ /A << \nav@temp >>
+ \nav@outline_attributes >>}%
+%
+ \egroup
+ \deleteparameter nav@temp:%
+ }
+
+\fi
+
+\def\nav@outline_getaction#1#2{%
+ \nav@storevalueand\nav@temp nav@temp:anchor;
+ {\edef\nav@temp{/S/GoTo /D (\anchorname{\nav@temp})}}
+ {\nav@storevalueand\nav@temp nav@temp:action;
+ {\pdfensureobject{\nav@temp}%
+ \edef\nav@temp{/S/Named /N/NoAction /Next \pdfrefobject{\nav@temp}}}
+ {\nav@anchor[#1]{\ifemptystring{#2}{outline_\the\nav@outline_count}{#2}}%
+ \edef\nav@temp{/S/GoTo /D (\anchorname{\ifemptystring{#2}{outline_\the\nav@outline_count}{#2})}}}}%
+ }
+
+
+\def\nav@outline_attributes{%
+ % See REMARK above for default values.
+ /C [\nav@usevalueor nav@temp:color;{\nav@usevalueor nav@temp:outlinecolor;{0 0 0}}]
+ /F \nav@ifvalue nav@temp:bold; = true {1}{0}\nav@ifvalue nav@temp:italic; = true {1}{0}
+ }
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%% Annotations %%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def\actionlink{%
+ \ifnext[
+ {\nav@actionlink_do{a}}
+ {\nav@actionlink_do{a}[]}%
+ }
+
+\def\rawactionlink{%
+ \ifnext[
+ {\nav@actionlink_do{r}}
+ {\nav@actionlink_do{r}[]}%
+ }
+
+\def\jumplink{%
+ \ifnext[
+ {\nav@actionlink_do{d}}
+ {\nav@actionlink_do{d}[]}%
+ }
+
+\def\annotation{%
+ \ifnext[
+ {\nav@actionlink_do{x}}
+ {\nav@actionlink_do{x}[]}%
+ }
+
+\def\openfilelink{%
+ \ifnext[
+ {\nav@openfilelink}
+ {\nav@openfilelink[]}%
+ }
+
+\def\nav@openfilelink[#1]#2{%
+ \ifnext[
+ {\nav@openfilelink_do{#1}{#2}}
+ {\nav@openfilelink_do{#1}{#2}[0]}%
+ }
+
+\def\nav@openfilelink_do#1#2[#3]{%
+ \nav@actionlink_do{r}[#1]
+ {/S/GoToE /D [\the\numexpr#3-1\relax /Fit]
+ /T << /R/C /N (#2) >> /NewWindow true}%
+ }
+
+\long\def\nav@actionlink_do#1[#2]#3#4{%
+ \nav@quitvmode
+ \nav@prepare_options{}{#2}%
+ \iffstring{#1}{a}{\pdfensureobject{#3}}%
+ \nav@actionlink_create{#1}{#3}{%
+ % Something in pre might be delimited by something in post
+ % so post must be passed expanded.
+ \nav@passvaluenobracesor{\nav@usevalue nav@temp:pre;#4}nav@temp:post;
+ {\nav@usevalue nav@temp:pre;#4}%
+ }%
+ \deleteparameter nav@temp:%
+ }
+
+\ifpdforluatex
+
+\let\nav@quitvmode\quitvmode
+
+\long\def\nav@actionlink_create#1#2#3{%
+ \pdfstartlink
+ attr {\nav@actionlink_attributes{#1}{#2}}
+ user {}%
+ #3\pdfendlink
+ }
+
+\else
+
+\let\nav@quitvmode\leavevmode
+
+\long\def\nav@actionlink_create#1#2#3{%
+ \special{pdf: bannot
+ << \nav@actionlink_attributes{#1}{#2} >>}%
+ #3\special{pdf: eannot}%
+ }
+
+\fi
+
+\def\nav@actionlink_attributes#1#2{%
+ /Border [0 0 \nav@usevalueor nav@temp:border;{1}%
+ \nav@passvaluenobracesand{[}nav@temp:dash;{]}{}]
+ /C [\nav@usevalueor nav@temp:color;{\nav@usevalueor nav@temp:linkcolor;{0 0 0}}]
+ \nav@ifcasevalue nav@temp:highlight;%
+ \val none /H/N
+ \val invert /H/I
+ \val outline /H/O
+ \val push /H/P
+ \endval
+ \ifstring{#1}{x}
+ {#2}
+ {/Subtype/Link
+ \ifstring{#1}{d}
+ {/Dest (\anchorname{#2})}
+ {/A \ifstring{#1}{r}
+ {<< #2 >>}
+ {\pdfrefobject{#2}}}}%
+ \nav@usevalue nav@temp:raw;%
+ }
+
+\pdfdictobject{firstpage}{/S/Named /N/FirstPage}
+\pdfdictobject{lastpage} {/S/Named /N/LastPage}
+\pdfdictobject{prevpage} {/S/Named /N/PrevPage}
+\pdfdictobject{nextpage} {/S/Named /N/NextPage}
+
+\def\urlaction#1#2{%
+ \pdfdictobject{#1}{/S/URI /URI (#2)}%
+ }
+
+\def\javascriptaction#1#2{%
+ \pdfdictobject{#1}{/S/JavaScript /JS (\pdfstring{#2})}%
+ }
+
+\def\urllink{%
+ \ifnext[
+ {\nav@urllink}
+ {\nav@urllink[]}%
+ }
+
+\def\nav@urllink[#1]#2{%
+ \nav@actionlink_do{r}[#1]{/S/URI /URI (#2)}%
+ }
+
+\def\javascriptlink{%
+ \ifnext[
+ {\nav@javascriptlink}
+ {\nav@javascriptlink[]}%
+ }
+
+\def\nav@javascriptlink[#1]#2{%
+ \nav@actionlink_do{r}[#1]{/S/JavaScript /JS (\pdfstring{#2})}%
+ }
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%% Embedded files %%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\def\nav@embeddedfile_names{}%
+
+\ifcase\texenginenumber
+
+\or % XeTeX
+\def\nav@sort#1#2{%
+ \straightenif{ifnum}{\strcmp{#1}{#2} < 0\relax}%
+ }
+
+\or % PDFTeX
+\def\nav@sort#1#2{%
+ \straightenif{ifnum}{\pdfstrcmp{#1}{#2} < 0\relax}%
+ }
+
+\or % LuaTeX
+\def\nav@sort#1#2{%
+ \usecs{%
+ \directlua{%
+ if [[#1]] < [[#2]] then
+ tex.print("firstoftwo")
+ else
+ tex.print("secondoftwo")
+ end}}}
+\fi
+
+\def\embeddedfile{%
+ \ifnext[
+ {\nav@embeddedfile_getdesc}
+ {\nav@embeddedfile_getdesc[]}%
+ }
+
+\def\nav@embeddedfile_getdesc[#1]#2{%
+ \ifnext[
+ {\nav@embeddedfile_do{#1}{#2}}
+ {\nav@embeddedfile_do{#1}{#2}[]}%
+ }
+
+\def\nav@embeddedfile_do#1#2[#3]#4{%s
+ \pdffileobject[/Type/EmbeddedFile]{nav@embeddedfile:#2}{#4}%
+ \pdfdictobject{#2}{%
+ /Type/Filespec
+ /F (\ifemptystring{#3}{#4}{#3})
+ \reverse\iffemptystring{#1}{/Desc (\pdfstring{#1})}
+ /EF << /F \pdfrefobject{nav@embeddedfile:#2} >>}%
+ \let\nav@temp\nav@embeddedfile_names
+ \let\nav@embeddedfile_names\emptycs
+ \passexpanded{\ifemptystring{#3}{\nav@embeddedfile_add{#4}}{\nav@embeddedfile_add{#3}}{\pdfrefobject{#2}}}\nav@temp
+ }
+
+\newfor\nav@embeddedfile_add{2}#3#4{%
+ \nav@sort{#1}{#3}
+ {\global\eaddright\nav@embeddedfile_names{{#1}{#2}{#3}{#4}}%
+ \retrieverest{\global\eaddright\nav@embeddedfile_names}}
+ {\global\eaddright\nav@embeddedfile_names{{#3}{#4}}}%
+ }[\global\eaddright\nav@embeddedfile_names{{#1}{#2}}]
+
+\newfor\nav@embeddedfile_print#1#2{(#1) #2}
+
+\def\nav@embeddedfile_process{%
+ \pdfdictobject{EmbeddedFiles}{/Names [\passexpanded\nav@embeddedfile_print\nav@embeddedfile_names]}%
+ \nav@embeddedfile_setnames
+ }
+
+\ifpdforluatex
+
+\def\nav@embeddedfile_setnames{%
+ \pdfnames{/EmbeddedFiles \pdfrefobject{EmbeddedFiles}}%
+ }
+
+\else
+
+\def\nav@embeddedfile_setnames{%
+ \special{pdf: put @names << /EmbeddedFiles \pdfrefobject{EmbeddedFiles} >>}%
+ }
+
+\fi
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%% INFO %%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newif\ifnav@finished
+\def\finishpdffile{%
+ \unless\ifnav@finished
+ \global\nav@finishedtrue
+ \nav@embeddedfile_process
+ \nav@processoutlines
+ \nav@processinfo
+ \fi
+ }
+
+\setparameter navigator :
+% ANCHORS (and bookmarks which create implicit anchors)
+ up = \baselineskip
+ left = 0pt
+ fit = xyz
+% zoom = 1000 % If it is set, it always sets view to 100%, which is extremely irritating.
+%
+% LINKS
+ border = 0
+ linkcolor = "0 0 0" % "color" in individual links
+ highlight = invert
+% dash = 1 0
+% raw = makes sense for individual links only
+% pre = nothing
+% post = nothing
+%
+% OUTLINES
+ outlinecolor = "0 0 0" % "color" in individual outlines
+ open = false
+ bold = false
+ italic = false
+% action = makes sense for individual outlines only
+% anchor = idem
+%
+% PDF info, no default values:
+% author, title, keywords, subject, date, moddate,
+% creator, producer, rawinfo
+%
+% PDF catalog, idem:
+% layout, mode, uri or base, openaction, rawcatalog
+
+
+\def\nav@processinfo_do#1#2{%
+ \nav@passvalueand{/#1 (\pdfstring}navigator:#2;{) }{}%
+ }
+
+\def\nav@processinfo{%
+ \nav@info{%
+ \nav@processinfo_do{Author} {author}%
+ \nav@processinfo_do{Title} {title}%
+ \nav@processinfo_do{Keywords} {keywords}%
+ \nav@processinfo_do{Subject} {subject}%
+ \nav@processinfo_do{CreationDate} {date}%
+ \nav@processinfo_do{ModDate} {moddate}%
+ \nav@processinfo_do{Creator} {creator}%
+ \nav@processinfo_do{Producer} {producer}%
+ \nav@usevalue navigator:rawinfo;}%
+%
+ \nav@passvalue\pdfensureobject navigator:openaction;%
+ \nav@catalog{%
+ \nav@ifattribute navigator:layout;
+ {/PageLayout%
+ \nav@ifcasevalue navigator:layout;%
+ \val onepage /SinglePage
+ \val onecolumn /OneColumn
+ \val twopage /TwoPageRight
+ \val twopage* /TwoPageLeft
+ \val twocolumn /TwoColumnRight
+ \val twocolumn* /TwoColumnLeft
+ \endval\spacecs}{}%
+ \nav@ifattribute navigator:mode;
+ {/PageMode
+ \nav@ifcasevalue navigator:mode;%
+ \val outlines /UseOutlines
+ \val bookmarks /UseOutlines
+ \val thumbnails /UseThumbs
+ \val thumbs /UseThumbs
+ \val oc /UseOC
+ \val attachments /UseAttachments
+ \val files /UseAttachments
+ \elseval /UseOutlines
+ \endval\spacecs}{}%
+ \nav@ifattribute navigator:uri;
+ {/URI << /Base (\nav@usevalue navigator:uri;) >> }
+ {\nav@ifattribute navigator:base;
+ {/URI << /Base (\nav@usevalue navigator:base;) >> }
+ {}}%
+ \nav@passvalue{/OpenAction \pdfrefobject}navigator:openaction;%
+ \nav@usevalue navigator:rawcatalog;}%
+ }%
+
+\ifpdforluatex
+
+\let\nav@info\pdfinfo
+\let\nav@catalog\pdfcatalog
+
+\else
+
+\def\nav@info#1{%
+ \special{pdf: docinfo << #1 >>}%
+ }
+\def\nav@catalog#1{%
+ \special{pdf: docview << #1 >>}%
+ }
+
+\fi
+
+\restorecatcodes
+\endinput
+% Almost 800 lines? Gee, that code was supposed to
+% be short and light...
diff --git a/macros/generic/navigator/t-navigator.tex b/macros/generic/navigator/t-navigator.tex
new file mode 100644
index 0000000000..1641d394fc
--- /dev/null
+++ b/macros/generic/navigator/t-navigator.tex
@@ -0,0 +1,33 @@
+% This is t-navigator.tex, a third-party file to load
+% the Navigator package in ConTeXt. Useful information
+% can be found in navigator-doc.pdf
+%
+% Author: Paul Isambert.
+% E-mail: zappathustra AT free DOT fr
+% Comments and suggestions are welcome.
+% Date: May 2016.
+%
+% Note that support for Navigator is limited in ConTeXt,
+% because ConTeXt doesn't really need it, and any effort
+% on my part could be harmful to the integrity of ConTeXt's
+% processing, to put it in a somewhat tragic tone. More
+% precisely, embedded files and document infos and display
+% aren't supported.
+%
+%D \module
+%D [ file=t-navigator,
+%D version=2016.05.22,
+%D title=\CONTEXT\ User Module,
+%D subtitle=Navigator,
+%D author=Paul Isambert,
+%D date=\currentdate,
+%D copyright=Paul Isambert,
+%D email=zappathustra@free.fr,
+%D license=LaTeX Project Public License]
+
+\writestatus{loading}{ConTeXt User Module / navigator}
+\chardef\formatnumber=3
+\input navigator.tex
+\appendtoks \finishpdffile \to \everystoptext
+\endinput
+