2018-09-24 14:19:00

35 files changed, 543 insertions, 111 deletions

diff --git a/doc/context/documents/general/manuals/interaction.pdf b/doc/context/documents/general/manuals/interaction.pdf
index c38e6f9c9..8198e8b92 100644
--- a/doc/context/documents/general/manuals/interaction.pdf
+++ b/doc/context/documents/general/manuals/interaction.pdf
diff --git a/doc/context/documents/general/manuals/nodes.pdf b/doc/context/documents/general/manuals/nodes.pdf
index 8f0ec1b73..c1e94b14d 100644
--- a/doc/context/documents/general/manuals/nodes.pdf
+++ b/doc/context/documents/general/manuals/nodes.pdf
diff --git a/doc/context/documents/general/qrcs/setup-cs.pdf b/doc/context/documents/general/qrcs/setup-cs.pdf
index 7752f50f4..3f549ad7a 100644
--- a/doc/context/documents/general/qrcs/setup-cs.pdf
+++ b/doc/context/documents/general/qrcs/setup-cs.pdf
diff --git a/doc/context/documents/general/qrcs/setup-de.pdf b/doc/context/documents/general/qrcs/setup-de.pdf
index a4927c30d..d0de1aa8b 100644
--- a/doc/context/documents/general/qrcs/setup-de.pdf
+++ b/doc/context/documents/general/qrcs/setup-de.pdf
diff --git a/doc/context/documents/general/qrcs/setup-en.pdf b/doc/context/documents/general/qrcs/setup-en.pdf
index 4fd1e2ad7..33a647f28 100644
--- a/doc/context/documents/general/qrcs/setup-en.pdf
+++ b/doc/context/documents/general/qrcs/setup-en.pdf
diff --git a/doc/context/documents/general/qrcs/setup-fr.pdf b/doc/context/documents/general/qrcs/setup-fr.pdf
index dc708e301..d57e70522 100644
--- a/doc/context/documents/general/qrcs/setup-fr.pdf
+++ b/doc/context/documents/general/qrcs/setup-fr.pdf
diff --git a/doc/context/documents/general/qrcs/setup-it.pdf b/doc/context/documents/general/qrcs/setup-it.pdf
index bf1aa6f0f..12b37f24d 100644
--- a/doc/context/documents/general/qrcs/setup-it.pdf
+++ b/doc/context/documents/general/qrcs/setup-it.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-cs.pdf b/doc/context/documents/general/qrcs/setup-mapping-cs.pdf
index 2aff67bff..62d9428bb 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-cs.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-cs.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-de.pdf b/doc/context/documents/general/qrcs/setup-mapping-de.pdf
index 5a8d7d1d0..fbdb2050e 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-de.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-de.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-en.pdf b/doc/context/documents/general/qrcs/setup-mapping-en.pdf
index 25ccfc10b..f07f87bec 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-en.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-en.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-fr.pdf b/doc/context/documents/general/qrcs/setup-mapping-fr.pdf
index 2deff5d05..2f10576a2 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-fr.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-fr.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-it.pdf b/doc/context/documents/general/qrcs/setup-mapping-it.pdf
index b79276e13..f5e09955d 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-it.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-it.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-nl.pdf b/doc/context/documents/general/qrcs/setup-mapping-nl.pdf
index f1f66d876..d92b7fc96 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-nl.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-nl.pdf
diff --git a/doc/context/documents/general/qrcs/setup-mapping-ro.pdf b/doc/context/documents/general/qrcs/setup-mapping-ro.pdf
index be334b905..162809e63 100644
--- a/doc/context/documents/general/qrcs/setup-mapping-ro.pdf
+++ b/doc/context/documents/general/qrcs/setup-mapping-ro.pdf
diff --git a/doc/context/documents/general/qrcs/setup-nl.pdf b/doc/context/documents/general/qrcs/setup-nl.pdf
index e510421d6..0822a6fba 100644
--- a/doc/context/documents/general/qrcs/setup-nl.pdf
+++ b/doc/context/documents/general/qrcs/setup-nl.pdf
diff --git a/doc/context/documents/general/qrcs/setup-ro.pdf b/doc/context/documents/general/qrcs/setup-ro.pdf
index b14326565..f053b5347 100644
--- a/doc/context/documents/general/qrcs/setup-ro.pdf
+++ b/doc/context/documents/general/qrcs/setup-ro.pdf
diff --git a/doc/context/sources/general/manuals/interaction/interaction-actions.tex b/doc/context/sources/general/manuals/interaction/interaction-actions.tex
index 3c9bfe842..a5caf2c0b 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-actions.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-actions.tex
@@ -9,11 +9,11 @@
 \startchapter[title=Actions]
 
 The reference mechanism not only deals with the more traditional cross
-references, but also takes care of navigational, launching applications (although
+references, but also takes care of navigation, launching applications (although
 that is often limited by viewers), running \JAVASCRIPT, etc. By integrating these
-features in one mechanism, we limit the number of commands needed for
-hyperreferences, menus and buttons. Normally such actions are driven by the \type
-{\goto} command, but you can also use buttons:
+features in one mechanism, we limit the number of commands needed for hyperlinks,
+menus and buttons. Normally such actions are driven by the \type {\goto} command,
+but you can also use buttons:
 
 \starttyping
 \goto[inner reference]
@@ -26,7 +26,7 @@ named location like a chapter or figure. The outer reference refers to a file or
 \URL and is normally defined at the document level and is accessed by the \type
 {::}. By using symbolic names updating them becomes easier.
 
-There are also predefined references, like \type {previouspage} to go to the next
+There are also predefined references, like \type {nextpage} to go to the next
 page or \type {forward} to cycle, \type {nextcontents} for the next level table
 of contents in a linked list of such tables, etc. Some keywords are actually
 shortcuts to actions that are delegated to the viewer. Here you need to keep in
@@ -38,10 +38,10 @@ by their capitals.
 When we speak of a reference, we actually refer to a whole bunch of possible
 references. We already mentioned inner and outer references, but special actions
 are also possible. These are actually plugins. Examples are the \JAVASCRIPT\ and
-\URL\ plugins. The interface evolved over a few decades but most has been there
-right from the start, which is why we keep it as is. Actually, there is not that
-much new functionality added in \MKIV, although the implementation was mostly
-rewritten. Here is a overview of the syntax, just to give you an idea.
+\URL\ plugins. The interface evolved a bit over a few decades but most has been
+there right from the start, which is why we keep it as is. Actually, there is not
+that much new functionality added in \MKIV, although the implementation was
+mostly rewritten. Here is a overview of the syntax, just to give you an idea.
 
 \starttyping
 \goto[inner]
@@ -62,8 +62,6 @@ rewritten. Here is a overview of the syntax, just to give you an idea.
 \goto[special(operation(whatever))]
 \goto[special(operation{argument,argument{whatever}})]
 \goto[special(operation{argument{whatever}})]
-\goto[special(operation{"argument,argument{whatever"})]
-\goto[special(operation{"argument{whatever"})]
 \stoptyping
 
 There can be multiple actions, separated by a comma, think of: go to the page
@@ -72,10 +70,12 @@ with label \quote {foo} and start video \quote {bar}.
 \showsetup{goto}
 
 Examples of operations are \type {page}, \type {program}, \type {action}, \type
-{url} and \type {JS}. The \type {page} operation accepts a pagenumber as well as
-relevant keywords. One can prefix a pagenumber by a file or \URL\ tag. The \type
-{program} operation starts up a program. It is an example of an old feature that
-has proven to be unstable, simply because viewers change behaviour over time.
+{url} and \type {JS}. \footnote {There are a few more operations but not all make
+sense at the user level.} The \type {page} operation accepts a pagenumber as
+well as relevant keywords. One can prefix a pagenumber by a file or \URL\ tag.
+The \type {program} operation starts up a program. It is an example of an old
+feature that has proven to be unstable, simply because viewers change behaviour
+over time.
 
 \showsetup{definereference}
 
@@ -165,7 +165,17 @@ a command:
 
 \startbuffer
 \showreference[page(123),StartMovie{mymovie}]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
 \showreference[JS(Forget_Changes),CloseDocument]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
 \showreference[manual::contents]
 \stopbuffer
 
diff --git a/doc/context/sources/general/manuals/interaction/interaction-annotations.tex b/doc/context/sources/general/manuals/interaction/interaction-annotations.tex
index 56a799da0..e61a0953d 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-annotations.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-annotations.tex
@@ -10,7 +10,7 @@ Before we discuss interactive features (in following chapter) a few words will b
 spent on so called annotations. This term is used in Acrobat and is somewhat
 confusing as hyperlinks conceptually are not really annotations while comments
 are. The term relates to the way \PDF\ files can have added functionality. It
-might help understand the following chanters better when you know what model is
+might help understand the following chapters better when you know what model is
 used inside a \PDF.
 
 If you open a \PDF\ file in an editor you will finds lots of objects. Numbers are
@@ -41,7 +41,7 @@ A \PDF\ file is a collection of objects:
 
 \starttyping
 1 0 obj
-
+    ...
 endobj
 \stoptyping
 
@@ -78,13 +78,20 @@ about hyperlinks and such. The \type {/Link} annotation objects that implement
 interactivity are independent and kind of layered over the rendered page. They
 describe rectangular areas that a viewer can use to intercept mouse clicks. If
 you want to see where the actions happens, search for \type {/Dest} and \type
-{/Annot} in an (uncompressed) \PDF file.
+{/Annot} in an (uncompressed) \PDF file. When you process a file with
+
+\starttyping
+\nopdfcompression
+\stoptyping
+
+you get an uncompressed file and with an appropriate editor you can see where
+annotations end up.
 
 The main reason for mentioning these details is that when you are checking a file
 for problems you need to look for annotation objects instead of the page stream.
 You also need to realize that these annotations in no way interfere with the page
 stream. They only exist because a viewer can use that information to add
-functionality. Their reference point is the lower lefty corner of the page. This
+functionality. Their reference point is the lower left corner of the page. This
 is a conceptual difference with \HTML\ where hyperlinks are often in|-|line and
 part of the content stream. Both approaches have their advantages and
 disadvantages. From the perspective of quality typesetting it makes much sense to
diff --git a/doc/context/sources/general/manuals/interaction/interaction-attachments.tex b/doc/context/sources/general/manuals/interaction/interaction-attachments.tex
index 48d2abf6c..6ae9b6310 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-attachments.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-attachments.tex
@@ -17,8 +17,8 @@
 \startchapter[title=Attachments]
 
 Attachments are (normally) embedded files that the reader can extract. A viewer
-can decide to just show the content or call an associated program (which one
-depends on the operating system) to deal with the file. As with other annotations
+can decide to just show the content or call an associated program to deal with
+the file (which one depends on the operating system). As with other annotations
 they started out depicted by symbols but then browsers started showing them in
 lists next to the displayed page.
 
@@ -43,7 +43,7 @@ lists next to the displayed page.
 
 \typebuffer \getbuffer
 
-These two attachments differ in one aspect: the second ons is hidden, i.e. it has
+These two attachments differ in one aspect: the second one is hidden, i.e. it has
 no icon in the text. However, the attachment is in the file and is (often)
 visible in the side bar. The symbol for the visible one is in the margin, which
 is achieved with:
@@ -165,25 +165,10 @@ or with all options:
 \useattachment[name][file][author][title][subtitle]
 \stoptyping
 
-This variant stays around for old times sake and just maps onto \type
-{\registerattachment}, you can better use that one because it frees you from
-remembering which arguments is what for.
+The \type {\use...} variant stays around for old times sake and just maps onto
+\type {\registerattachment}, you can better use that one because it frees you
+from remembering which arguments is what for.
 
 \stopchapter
 
 \stopcomponent
-
-
-
-% old but stil valid method:
-%
-% \useattachment[test.tex]
-% \useattachment[whatever][test.tex]
-% \useattachment[whatever][newname][test.tex]
-% \useattachment[whatever][title][newname][test.tex]
-%
-% new method:
-%
-% \registerattachment[sometag][specification] % name file author title subtitle
-%
-% \attachment[sometag][extra specs]
diff --git a/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex b/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex
index 41565e7a4..04dd3f89d 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex
@@ -6,6 +6,69 @@
 
 \startchapter[title=Bookmarks]
 
+Bookmarks are a sort of table of contents displayed by the viewer and as such
+they take up extra space on the screen. You need to turn on interaction in
+order to get bookmark data embedded in the document.
+
+\starttyping
+\placebookmarks
+  [chapter,section,subsection,mylist]
+  [chapter]
+\stoptyping
+
+A bookmark list is added to the document only when interaction is enabled. The
+list in the first argument are bookmarked while the second argument specifies
+what bookmark (sub)trees are opened. if you don't get what you expect, check your
+document structure! Also, use the \type {\start}|-|\type {stop} alternatives.
+
+Bookmarks are taken from the section title, but you can overload the title
+as follows:
+
+\starttyping
+\startchapter[title=Foot,bookmark=food]
+    ...
+\stopchapter
+\stoptyping
+
+If you have a more complex typeset title you can also try:
+
+\starttyping
+\enabledirectives[references.bookmarks.preroll]
+\stoptyping
+
+From \MKII\ we inherit the option to overload the last set bookmark but the
+previously mentioned approach is better.
+
+\starttyping
+\chapter {the first chapter}
+\bookmark {the first bookmark}
+\stoptyping
+
+You can add entries to a bookmark list:
+
+\starttyping
+\bookmark[mylist]{whatever}
+\stoptyping
+
+This assumes that you have defined the list.
+
+\showsetup {bookmark}
+
+If you want to have the bookmark tab open when you start a document, you
+can say:
+
+\starttyping
+\setupinteractionscreen[option=bookmark]
+\stoptyping
+
+There are only a few options that you can use. The \type {number} parameter can
+be used to hide section numbers. The \type {sectionblock} parameter controls the
+addition of section block entries, something that can be handy when you have
+multiple section blocks with similar section titles. With \type {force} you force
+an entry to the file, bypassing mechanisms that to be clever.
+
+\showsetup{setupbookmark}
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-buttons.tex b/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
index 7c50d3ecf..d083a61a7 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-buttons.tex
@@ -4,6 +4,95 @@
 
 \startchapter[title={Buttons}]
 
+There is not much to tell about buttons. They are clickable areas on the screen
+that when clicked on bring you some location or invoke some action in the viewer,
+for instance triggered by a \JAVASCRIPT. As usual with many commands, you can
+define categories of buttons and set them up globally or per category.
+
+\showsetup{definebutton}
+
+\showsetup{setupbutton}
+
+The default button command is:
+
+\showsetup{button}
+
+Buttons are an example of a construct that builds upon \type {\framed} so the
+keys that apply there also apply to buttons. You can enable or disable buttons
+with the \type {state} parameter. As usual there are a \type {style} and \type
+{color} parameters and an additional \type {contrastcolor} option for tuning the
+color of a button which action let you stay on the same page. Actually, when you
+do stay on the same page, the \type {samepage} parameter let you control if the
+button should be empty, hidden or whatever.
+
+\starttabulate[|B|c|c|c|]
+\NC                 \BC frame \BC text \BC shown \NC \NR
+\NC \type {yes}     \NC +     \NC +    \NC +     \NC \NR % 0
+\NC \type {empty}   \NC +     \NC -    \NC +     \NC \NR % 1
+\NC \type {no}      \NC -     \NC -    \NC +     \NC \NR % 2
+\NC \type {none}    \NC -     \NC -    \NC -     \NC \NR % 3
+\NC \type {normal}  \NC +     \NC +    \NC +     \NC \NR % 1
+\NC \type {default} \NC +     \NC +    \NC +     \NC \NR % 1
+\stoptabulate
+
+Here is an example of a button:
+
+\startbuffer
+\button
+  [background=color,backgroundcolor=darkred,
+   style=bold,color=white,
+   framecolor=blue,rulethickness=2pt,
+   width=3cm,height=1.5cm]
+  {go to the next page}
+  [nexpage]
+\stopbuffer
+
+\typebuffer
+
+This colorful button shows up as:
+
+\startlinecorrection
+\getbuffer
+\stoplinecorrection
+
+When you use interaction in presentations you might want to make the page
+and|/|or text area active. Here is an example.
+
+\starttyping
+\defineoverlay
+  [PrevPage]
+  [\overlaybutton{PrevPage}]
+
+\setupbackgrounds
+  [page]
+  [background=PrevPage]
+
+\setuptexttexts
+  [\overlaybutton{NextPage}]
+\stoptyping
+
+We provide two variants: the normal one with square brackets, but also a more
+direct one that accepts curly braces, which is handy when you pass an overlay
+button as argument.
+
+\showsetup {overlaybutton}
+\showsetup {overlaybutton:direct}
+
+The difference in usage is shown here:
+
+\starttyping
+\setuptexttexts [\overlaybutton{NextPage}]
+\setuptexttexts[{\overlaybutton[NextPage]}]
+\stoptyping
+
+An overlay button adapts its size to the current overlay so you don't need to
+worry about passing dimensions.
+
+It is possible to define more complex buttons, like roll|-|over buttons or
+buttons that change appearance when you clock on them. These are more resource
+hungry and also depend on the viewer. These will discussed in the chapter about
+widgets.
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-comments.tex b/doc/context/sources/general/manuals/interaction/interaction-comments.tex
index f128905bd..b19894d57 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-comments.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-comments.tex
@@ -27,9 +27,9 @@ advanced ones with representations. A comment looks like:
 When you open a document with comment you will likely see some symbol depicting
 it. But, it's one of those features that is viewer dependent so when it looks odd
 or unexpected, check in \ACROBAT\ first. The position and size can differ per
-viewer and when you zoom in teh size can either stay the same or scale. The
+viewer and when you zoom in the size can either stay the same or scale. The
 viewer can show the pop up text at the same location or someplace else. Although
-in principle there is control over this, my experience is that viwers (also
+in principle there is control over this, my experience is that viewers (also
 Acrobat) keep changing this (not always for the best). Just assume the worst: it
 will never look good and although for a while we kept up with viewers, the
 inconsistency (and accumulated waste of time) led us to the current minimalistic
@@ -49,15 +49,19 @@ This because we are compatible with \MKII.
 
 \startbuffer
 \startcomment[french]
-  In France they use «these angle bracket glyphs» in subsentences.
+  In France they use «angle bracket glyphs» in subsentences.
 \stopcomment
 
 \startcomment[accents][color=darkgreen]
   You can used an àçéñţêð character too.
 \stopcomment
+\stopbuffer
+
+\typebuffer \getbuffer
 
 And normally empty lines are also supported (again this can differ per viewer):
 
+\startbuffer
 \startcomment[lines][color=darkblue]
   How about an
 
@@ -65,9 +69,7 @@ And normally empty lines are also supported (again this can differ per viewer):
 \stopcomment
 \stopbuffer
 
-\typebuffer
-
-\getbuffer
+\typebuffer \getbuffer
 
 As we can see here, comments are sort of stacked. These examples also show that
 we can pass an optional title and set up some characteristics. An inline comment
diff --git a/doc/context/sources/general/manuals/interaction/interaction-enabling.tex b/doc/context/sources/general/manuals/interaction/interaction-enabling.tex
index 3f3c59544..8e31ccbe6 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-enabling.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-enabling.tex
@@ -34,10 +34,9 @@ The \type {title}, \type {subtitle}, \type {author}, \type {date} and \type
 document information.
 
 The \type {openaction} parameter can for instance be used to start at a specific
-page, while the \type {closeaction} can for instance trigger a \JAVASCRIPT\
-cleanup script. The \type {openpageaction} and \type {closepageaction} can for
-instance initialize and reset states, something we do in some presentation
-styles.
+page, while the \type {closeaction} can be used to trigger a \JAVASCRIPT\ cleanup
+script. The \type {openpageaction} and \type {closepageaction} can for instance
+initialize and reset states, something we do in some presentation styles.
 
 The \type {click} parameter controls how a viewer responds to pressing a mouse
 button on an annotation: highlight or not. The \type {display} parameter
@@ -45,8 +44,8 @@ determines if a cross document link opens in the current window.
 
 The \type {menu} parameter is a quick way to disable menus, of which there can be
 many: at each side of the page, stacked or not, etc. The \type {symbolset}
-determines the look and feel of symbols used in for instance navigational buttons
-and status bars.
+determines the look and feel of symbols used in for instance menus, buttons and
+status bars.
 
 The \type {page} parameters is a bit special, and it function is an inheritance
 from the early days. Some \DVI\ and \PDF\ viewers supported named destinations,
diff --git a/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex b/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex
index cd156b3be..f204d502e 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex
@@ -6,10 +6,24 @@
 
 \startchapter[title=Hyperlinks]
 
-
-% component:inner     prefix
-% component::inner    always external
-% component:::inner   internal (for products) or external (for components)
+A hyperlink is something that you click on and that brings you to nother spot in
+the document. The regular links are a side effect of references. The most commonly
+used references are:
+
+\starttyping
+\in{figure}[fig:foo]
+\at{page}[fig:foo]
+\about[fig:foo]
+\stoptyping
+
+The first argument is what gets prepended to the number and the while can be
+clicked on. Here we create a namespace with \type {fig:}. This can be somewhat
+confusing with respect to prefixes but normally the resolver does a direct lookup
+first.
+
+\showsetup{at}
+\showsetup{in}
+\showsetup{about}
 
 \stopchapter
 
diff --git a/doc/context/sources/general/manuals/interaction/interaction-importing.tex b/doc/context/sources/general/manuals/interaction/interaction-importing.tex
index 9ad6fa20a..8c36128f6 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-importing.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-importing.tex
@@ -6,6 +6,68 @@
 
 \startchapter[title=Importing]
 
+This is a very short chapter that deals with external figures. Normally an image
+is a graphic with possible some text. There are however workflows where one
+includes pages from other documents. Such documents can contain cross references,
+bookmarks, comments and|/|or fields. Normally annotations of any kind are ignored
+and for good reason: they assume the whole document to be the, not just one or a
+few pages. Merging references for instance is a source for clashes, not only for
+named ones but also for page references.
+
+But when you {\em know} what you're doing, as for instance Taco (who requested
+this feature) does, there is a way to merge annotations. This is controlled by
+the interaction keys in \type {externalfigure}:
+
+\starttyping
+\externalfigure[somedoc][page=1,interaction=yes]
+\externalfigure[somedoc][page=2,interaction={reference,bookmark}]
+\stoptyping
+
+However, only references and bookmarks are officially supported! The other
+annotations are possible but the code is experimental and will be finished
+when we find a good reason for it.
+
+\starttabulate[|B|p|]
+\FL
+\NC \type {reference} \NC named and page references and urls \NC \NR
+\NC \type {comment}   \NC comments if possible with relevant icon \NC \NR
+\NC \type {bookmark}  \NC text bookmarks that refer to pages \NC \NR
+\NC \type {field}     \NC widgets but only within reason \NC \NR
+\NC \type {layer}     \NC viewer layers \NC \NR
+\ML
+\NC \type {yes}       \NC named and page references, urls and bookmarks \NC \NR
+\NC \type {all}       \NC all annotations \NC \NR
+\LL
+\stoptabulate
+
+If things don't work out well, imagine for a while what is involved in supporting
+this: analyzing a page from a document, remapping the annotations onto some
+\CONTEXT\ mechanism, making sure that we don't get clashes, keeping overhead
+acceptable.
+
+Because this is a somewhat tricky feature, tracing can help you to identify
+problems: \typ {figures.merging}, \typ {figures.links}, \typ {figures.comments},
+\typ {figures.fields} and \typ {figures.outlines}.
+
+Another complication when including pages can be the presence of so called marked
+content in the page stream. There is experimental support for removing those but
+right now (2018) you need to explicitly enable this explicitly:
+
+\starttyping
+\enabledirectives[graphics.pdf.uselua]
+\enabledirectives[graphics.pdf.stripmarked]
+%enabledirectives[graphics.pdf.recompress]
+\stoptyping
+
+This will delegate inclusion from the backend to \LUA. This might become the
+default as it is just as efficient as using the backend. That way we can filter
+the content stream. \footnote {We might add a callback to \LUATEX\ for filtering
+the content stream (no hard todo but post version 1.10).}
+
 \stopchapter
 
 \stopcomponent
+
+
+
+
diff --git a/doc/context/sources/general/manuals/interaction/interaction-introduction.tex b/doc/context/sources/general/manuals/interaction/interaction-introduction.tex
index 7daec25d6..a6f44b05b 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-introduction.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-introduction.tex
@@ -8,16 +8,16 @@
 
 This document introduces the cross reference mechanism, viewer control, fill||in
 fields, \JAVASCRIPT\ support, comments, attachments and more. It is a rewrite of
-the \MKII\ widgets manual. There is (always) more than discussed in manuals so if
-you miss something, take a look at test suite or when you're brave, peek into the
-source code as there can be examples there.
+the \MKII\ widgets manual. There is (always) more available than discussed in
+manuals so if you miss something, take a look at test suite or when you're brave,
+peek into the source code as there can be examples there.
 
 Interactivity has always been available in \CONTEXT\ and in fact it was one of
 the reasons for writing it. In for instance the YandY \WINDOWS\ previewer, one
 could have hyperlinks and we used that for a while when checking documents. Later
 Acrobat showed up and \PDF\ stepwise added interactive features that we always
 supported right from the start. Unfortunately there is a viewer dependency and
-the documentation of \PDF\ lagged behind so solutions based on trial and error
+the documentation of \PDF\ lagged behind, so solutions based on trial and error
 could not work well in a follow up on \PDF. Some features disappeared or became
 so limited that they effectively became useless. Especially multi||media have a
 reputation of unreliability. Because open source viewers never really catched up
@@ -25,21 +25,22 @@ reputation of unreliability. Because open source viewers never really catched up
 could have audio and video embedded in reliable ways. Even forms and basic
 \JAVASCRIPT\ control of for instance layers is often missing.
 
-That said, we do support a lot and can support more when it makes sense. Deep
+That said, we do support a lot but can support more when it makes sense. Deep
 down in \CONTEXT\ we always had the mechanisms to deal with this, so extensions
-are not that hard to program. We always thought that publishers would like these
-features but that never really was the cases, so there was no pressure from that
+are not that hard to program. Somehow we thought that publishers would like these
+features but that never really was the case, so there was no pressure from that
 end. Most features are user driven or just there because at some point we wanted
-to make some fancy presentation.
+to make some fancy presentation. In fact, the \type {s-present-*} files provide
+examples of interactivity.
 
-The original \PDF\ was a couple of hundred pages and looked quite nice. A later
-print has manu more pages and still looks ok, but nowadays we have to do with a
-\PDF\ document. If you want to see what \PDF\ supports you can study this (now
-about) 750 \PDF\ standard. It is, being an \ISO\ standard, not public, but you
-can probably find a (maybe older) copy someplace on the web.
+The original \PDF\ reference was a couple of hundred pages and looked quite nice.
+A later print has many more pages and still looks ok, but nowadays we have to do
+with a \PDF\ document. If you want to see what \PDF\ supports you can study this
+(now about) 750 page standard. It is, being an \ISO\ standard, not public but
+you can probably find a (maybe older) copy someplace on the web.
 
 When reading this manual you need to keep in mind that we assume that you design
-a decent layout and when you make something for an electronic medium, we assume
+a decent layout and when you make something for an electronic medium, we hope
 that you pay attention to the way you can enhance accessibility.
 
 If you miss something here, don't hesitate to ask for clarification, or even
@@ -49,3 +50,9 @@ mechanism.
 \stopchapter
 
 \stopcomponent
+
+% A nice double page e-ink device can be seen at:
+%
+% https://www.youtube.com/watch?v=QdOXCn1vvzI :
+%
+% vkgoeswild: Playing Pink Floyds Great Gig in the Sky on Imperial by Bösendorfer
diff --git a/doc/context/sources/general/manuals/interaction/interaction-menus.tex b/doc/context/sources/general/manuals/interaction/interaction-menus.tex
index 4477c9397..6e002b5cd 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-menus.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-menus.tex
@@ -4,6 +4,9 @@
 
 \startchapter[title={Menus}]
 
+    {\em This chapter will discuss interaction menus that normally end up in the
+    margins.}
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-progress.tex b/doc/context/sources/general/manuals/interaction/interaction-progress.tex
index c26980e27..c077337b3 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-progress.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-progress.tex
@@ -4,6 +4,8 @@
 
 \startchapter[title={Progress}]
 
+    {\em This chapter will discuss progress bars.}
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-structure.tex b/doc/context/sources/general/manuals/interaction/interaction-structure.tex
index 3d503151c..793139d6c 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-structure.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-structure.tex
@@ -6,6 +6,70 @@
 
 \startchapter[title=Structure]
 
+There is a lot of structure in \CONTEXT:
+
+\startitemize[packed]
+\startitem document structure: projects, products, components, environments \stopitem
+\startitem sectioning, with or without numbers (visible), support for lists and userdata \stopitem
+\startitem lists, most often related to sections, but there are more \stopitem
+\startitem registers \stopitem
+\startitem itemized lists \stopitem
+\startitem images, \METAPOST\ graphics, different types of tables \stopitem
+\startitem typographical objects: constructions, descriptions and enumerations \stopitem
+\startitem notes, like footnotes, endnotes, linenotes \stopitem
+\startitem marginal notes \stopitem
+\startitem formulas (and subformulas) \stopitem
+\startitem text areas, layers, overlays \stopitem
+\startitem graphic placement with captions and references \stopitem
+\startitem cross references to most structural components \stopitem
+\startitem bibliographic databases and citations \stopitem
+\blank
+\startitem \unknown\ and more \unknown \stopitem
+\stopitemize
+
+Most of them in some way carry information about their location in the document
+and on the page, and sometimes their exact position. This also means that we can
+use that information for annotations. But most users will use the standard
+functionality.
+
+\starttyping
+\startsection[title=Whatever]
+    ...
+\stopsection
+\stoptyping
+
+In addition to typesetting this will add the title to a list. In order to do that
+some anchor has to be placed in the text, because we need to register the exact
+location in order to get the right pagenumber after \TEX\ has broken the flow into
+pages.
+
+\starttyping
+\placelist[section][criterium=text]
+\stoptyping
+
+This will place a list of all sections. If you want the whole entry to be a
+clickable areas, you can say:
+
+\starttyping
+\placelist[section][interaction=all]
+\stoptyping
+
+Otherwise only clicking on the title will bring you to the spot. If you also say:
+
+\starttyping
+\setuphead[interaction=list]
+\stoptyping
+
+Clicking on the head will bring you back to the table of contents. There are
+special list rendering alternatives for interactive documents (\typ
+{alternative=e} onwards). You can use the \type {list} and \type {bookmark}
+parameters to a section head to deviate from the given \type {title}.
+
+Many commands accept a \type {reference} as optional argument and when you use
+an alternative with key|/|values a \type {reference} key will do the job.
+
+{\em What should go into this chapter.}
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-style.tex b/doc/context/sources/general/manuals/interaction/interaction-style.tex
index 11754a419..e9922fb14 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-style.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-style.tex
@@ -36,6 +36,9 @@
    contrastcolor=]
 
 \setuphead
+  [interaction=list]
+
+\setuphead
   [chapter]
   [header=high,
    style=\bfd]
diff --git a/doc/context/sources/general/manuals/interaction/interaction-tagging.tex b/doc/context/sources/general/manuals/interaction/interaction-tagging.tex
index 579e9f2a9..d38c922f2 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-tagging.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-tagging.tex
@@ -6,6 +6,21 @@
 
 \startchapter[title=Tagging]
 
+In a tagged \PDF\ document the page stream is enriched (or polluted) by marks
+that indicate what kind of content is involved.
+
+\starttyping
+\setuptagging[state=start]
+\stoptyping
+
+Only the \type {state} parameters is of general use.
+
+\showsetup {setuptagging}
+
+The \TEX\ end of this mechanism overlaps with the export related tagging so when
+you add your own elements that will be reflected in the tagging. And indeed: the
+keyword here is structure. The worse the structure, the worse the tagging.
+
 \stopchapter
 
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex b/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex
index f97dc20a1..43b29baf9 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex
@@ -41,4 +41,7 @@
 
 \stopMPpage
 
+\page[empty]
+\page[right]
+
 \stopcomponent
diff --git a/doc/context/sources/general/manuals/interaction/interaction-widgets.tex b/doc/context/sources/general/manuals/interaction/interaction-widgets.tex
index 4bb7a46b5..e4fa136c9 100644
--- a/doc/context/sources/general/manuals/interaction/interaction-widgets.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction-widgets.tex
@@ -4,12 +4,13 @@
 
 \startchapter[title={Widgets}]
 
+    {\em This chapter will discuss forms and special buttons.}
+
 \stopchapter
 
 \stopcomponent
 
-
-
+% Below comes from the old widgets manual:
 
 \def\fillinfield#1{}
 
@@ -909,6 +910,68 @@ We can for instance typeset the fields by saying:
 \stopbaselinecorrection
 
 
-\stopchapter
 
-\stopcomponent
+%D \starttyping
+%D \defineviewerlayer[test]
+%D
+%D \startviewerlayer[test]Hide Me\stopviewerlayer
+%D
+%D \defineoverlay
+%D   [WithTest]
+%D   [{\overlayrollbutton[HideLayer{test}][VideLayer{test}]}]
+%D
+%D \framed[background=WithTest]{toggle}
+%D \stoptyping
+
+
+
+% \setupinteraction[state=start]
+%
+% \definepushbutton [reset]
+%
+% \startuniqueMPgraphic{whatever}{color}
+%     fill fullcircle xysized (OverlayWidth,OverlayHeight) withcolor \MPvar{color} ;
+% \stopuniqueMPgraphic
+%
+% \definepushsymbol [reset] [n] [\uniqueMPgraphic{whatever}{color=red}]
+% \definepushsymbol [reset] [r] [\uniqueMPgraphic{whatever}{color=green}]
+% \definepushsymbol [reset] [d] [\uniqueMPgraphic{whatever}{color=blue}]
+%
+% \starttext
+%     \startTEXpage
+%         \pushbutton [reset] [page(2)]
+%     \stopTEXpage
+%     \startTEXpage
+%         \pushbutton [reset] [page(1)]
+%     \stopTEXpage
+% \stoptext
+
+
+% \setupinteraction[state=start]
+%
+% \definepushbutton [reset]
+%
+% \startuniqueMPgraphic{whatever}{color}
+%     fill fullcircle xysized (OverlayWidth,OverlayHeight) withcolor \MPvar{color} ;
+% \stopuniqueMPgraphic
+%
+% \definepushsymbol [reset] [n] [\uniqueMPgraphic{whatever}{color=red}]
+% \definepushsymbol [reset] [r] [\uniqueMPgraphic{whatever}{color=green}]
+% \definepushsymbol [reset] [d] [\uniqueMPgraphic{whatever}{color=blue}]
+%
+% \starttext
+%     \startTEXpage
+%         \pushbutton [reset] [page(2)]
+%     \stopTEXpage
+%     \startTEXpage
+%         \pushbutton [reset] [page(1)]
+%     \stopTEXpage
+% \stoptext
+
+% \appendtoks
+%     \let\startrob\scrn_menu_rob_start
+%     \let\stoprob \relax
+%     \let\rob     \scrn_menu_rob_direct
+% \to \everysetmenucommands
+
+% \protect \endinput
diff --git a/doc/context/sources/general/manuals/interaction/interaction.tex b/doc/context/sources/general/manuals/interaction/interaction.tex
index ebdbbde86..077e4abd8 100644
--- a/doc/context/sources/general/manuals/interaction/interaction.tex
+++ b/doc/context/sources/general/manuals/interaction/interaction.tex
@@ -1,5 +1,8 @@
 \environment interaction-style
 
+\setuplayout[bottom=1cm,bottomdistance=1cm]
+\setupbottomtexts[\infofont work in progress]
+
 \startdocument
 
     \component interaction-titlepage
@@ -17,15 +20,15 @@
             \component interaction-structure
         \component interaction-comments
         \component interaction-attachments
-            \component interaction-bookmarks
+        \component interaction-bookmarks
         \component interaction-javascript
-            \component interaction-buttons
+        \component interaction-buttons
             \component interaction-menus
             \component interaction-progress
             \component interaction-widgets
-            \component interaction-transitions
-            \component interaction-importing
-            \component interaction-tagging
+        \component interaction-transitions
+        \component interaction-importing
+        \component interaction-tagging
     \stopbodymatter
 
 \stopdocument
diff --git a/doc/context/sources/general/manuals/nodes/nodes.tex b/doc/context/sources/general/manuals/nodes/nodes.tex
index e9857f37e..2d97e676a 100644
--- a/doc/context/sources/general/manuals/nodes/nodes.tex
+++ b/doc/context/sources/general/manuals/nodes/nodes.tex
@@ -24,17 +24,6 @@
 %
 % comment   : The cover images are from the NASA website.
 
-
-% Alan      : There is no need for % before \startfootnote .. the less such crap the better
-%             (as it might give disappearing content if one wraps).
-%
-% Alan      : ḻṯ  What is this? An editor glitch?
-%
-% Alan      : $≠$ -> just use ≠ (also, soon the gyre fonts will have more symbols in text
-%             that match text.
-%
-% Alan      : You can use \typ {x = 0} for something that breaks accross lines.
-
 %\enabletrackers[metapost.showlog]
 
 \definemeasure [layout:margin] [\paperheight/20]
@@ -89,6 +78,7 @@
 % \definesymbol [1] [$\cdot$]
 
 % Dot rather than bullet ... Alan hates bullets! Hans hates too small dots.
+% So, a dash is OK? ;-)
 
 \setupitemize
   [symbol=2] % dash rather than bullet, I hate bullets!
@@ -160,12 +150,13 @@
 
 \startbuffer [bib]
     @ARTICLE{Krebs1946,
-        author  = {Krebs, H. A.},
-        title   = {Cyclic processes in living matter},
-        journal = {Enzymologia},
-        year    = {1946},
-        volume  = {12},
-        pages   = {88--100}
+        author   = {Krebs, H. A.},
+        title    = {Cyclic processes in living matter},
+        journal  = {Enzymologia},
+        year     = {1946},
+        volume   = {12},
+        pages    = {88--100}
+        language = {english},
     }
 
     @ARTICLE{Bethe1939a,
@@ -180,6 +171,7 @@
         issue     = {1},
         publisher = {American Physical Society},
         XXurl     = {http://link.aps.org/doi/10.1103/PhysRev.55.103}
+        language  = {english},
     }
 
     @ARTICLE{Bethe1939b,
@@ -194,6 +186,7 @@
         issue     = {5},
         publisher = {American Physical Society},
         XXurl     = {http://link.aps.org/doi/10.1103/PhysRev.55.434}
+        language  = {english},
     }
 
     @BOOK{Lawvere2009,
@@ -204,6 +197,20 @@
         publisher = {Cambridge University Press},
         address   = {Cambridge, UK},
         year      = {2009}
+        language  = {english},
+    }
+
+    @ARTICLE{Braslau2018,
+        title     = {ConTeXt nodes},
+        subtitle  = {commutative diagrams and related graphics},
+        author    = {Braslau, Alan and Hamid, Idris Samawi and Hagen, Hans},
+        year      = {2018},
+        journal   = {TUGboat},
+        volume    = {39},
+        number    = {1},
+        ISSN      = {0896-3207},
+        url       = {https://www.tug.org/TUGboat/Contents/contents39-1.html},
+        language  = {english},
     }
 \stopbuffer
 
@@ -356,6 +363,11 @@
 
 \startsubject [title=Introduction]
 
+A draft version of this manual was published in \cite[journal] [Braslau2018].
+\cite [Braslau2018]
+
+\blank
+
 The graphical representation of textual diagrams is a very useful tool in the
 communication of ideas. In category and topos theory, for example, many key
 concepts, formulas, and theorems are expressed by means of \emph {commutative
@@ -683,7 +695,7 @@ The \CONTEXT\ syntax for the current example looks like this:
   \stopnodes
 \stopbuffer
 
-\startplacefigure [location=right,
+\startplacefigure [location=right,reference=fig:ConTeXt,
     title={Drawn using \CONTEXT\ interface}]
   \getbuffer
 \stopplacefigure
@@ -692,10 +704,9 @@ The \CONTEXT\ syntax for the current example looks like this:
 
 \startplacefigure [reference=fig:indices,
   location=right,
-  title={Coordinates and indices.\footnote{For variety, a rectangular oblique
-         lattice is drawn in \in{Figure} [fig:indices].}
-  }]
-\stopfootnote
+  title={Coordinates and indices.\footnote {For variety, a rectangular oblique
+         lattice is drawn in \in{Figure} [fig:indices].}}
+  ]
   \startframed [frame=off,width=.33\textwidth,align=flushright]
   \startnodes [dx=3cm,dy=2cm,rotation=60]
     \placenode [0,0] {\node{(0,0)}}
@@ -716,14 +727,47 @@ The \CONTEXT\ syntax for the current example looks like this:
 
 This follows the more classic (and limited) approach of placing nodes on the
 coordinates of a regular lattice, here defined as a 3~cm square network.
-\footnote {The lattice can be square (\type {dx} $=$ \type {dy}), rectangular
-(\type {dx} $≠$ \type {dy}), or oblique (through \type {rotation} $≠$ 90).} The
-arguments are then $(x,y)$ coordinates of this lattice and the nodes are indexed
+\startfootnote
+    The lattice can be square (\type {dx} $=$ \type {dy}), rectangular
+    (\type {dx} ≠ \type {dy}), or oblique (through \type {rotation} ≠ 90).
+\stopfootnote
+The arguments are then $(x,y)$ coordinates of this lattice and the nodes are indexed
 0, 1, 2, … in the order that they are drawn. These are used as reference indices
 in the commands \type {\connectnodes} (rather than requiring two \emph {pairs} of
 coordinates); see \in {Figure} [fig:indices]. This might seem a bit confusing at
 first view, but it simplifies things in the end, really!
 
+To avoid such confusion, in particular when drawing complicated diagrams
+containing many nodes, the \CONTEXT\ interface allows the use of a \type
+{reference} or tag, assigning a symbolic name to a numbered node. The example of 
+\in{Figure} [fig:ConTeXt] can be redrawn a little more verbosely as:
+
+\startbuffer
+  \startnodes [dx=3cm,dy=3cm]
+    \placenode [0,0] [reference=GX] {\node{$G(X)$}}
+    \placenode [1,0] [reference=GY] {\node{$G(Y)$}}
+    \placenode [1,1] [reference=FY] {\node{$F(Y)$}}
+    \placenode [0,1] [reference=FX] {\node{$F(X)$}}
+    \connectnodes [GX,GY] [alternative=arrow,
+      label={\nodeSmall{$G(f)$}},position=bottom]
+    \connectnodes [FX,FY] [alternative=arrow,
+      label={\nodeSmall{$F(f)$}},position=top]
+    \connectnodes [FY,GY] [alternative=arrow,
+      label={\nodeSmall{$η_Y$}}, position=right]
+    \connectnodes [FX,GX] [alternative=arrow,
+      label={\nodeSmall{$η_X$}}, position=left]
+  \stopnodes
+\stopbuffer
+
+\typebuffer [option=TEX]
+
+Notice that, like for all \CONTEXT\ macros, one never mixes a
+comma|-|separated list of arguments (\type {[0,0]}) with a key=value list
+(i.e. \type {[reference=GX]}). Symbolic references are very useful for longer,
+more complicated diagrams; additionally, this easily allows modification such as
+the addition of nodes without having to keep track of counting the order in
+which they were drawn.
+
 An identity map, as shown in \in {Figure} [fig:ID], earlier, and, below, in \in
 {Figure} [fig:Me] is achieved by connecting a node to itself:
 
@@ -752,8 +796,6 @@ The scale (diameter) of the circular loop|-|back is set by the keyword \type
 straight|-|line segment between them), and the \type {position=} keyword sets its
 orientation.
 
-\page [yes]
-
 \startbuffer
 \startMPcode
 clearnodepath ;
@@ -840,8 +882,6 @@ exterior for the output.
 
 The code is as follows:
 
-\page [yes]
-
 \startbuffer
 \startMPcode
   save p ; path p[] ;
@@ -1145,7 +1185,7 @@ path:
 save p ; % path p ;
 \stopTEX
 
-The \type {save p ;} assures that the path is undefined. This path will later ḻṯ
+The \type {save p ;} assures that the path is undefined. This path will later be
 defined based on the contents of the nodes and a desired relative placement. In
 fact, it is not even necessary to declare that the suffix will be a path, as the
 path will be declared and automatically built once the positions of all the nodes
@@ -1490,8 +1530,6 @@ coordinate taken to be \type {right}, both in the page of the paper. The third
 coordinate \type {X} is an oblique projection in a right|-|hand coordinate
 system.
 
-\page [yes]
-
 \startbuffer
 \startMPcode{three}
   save nodepath ;