2015-10-09 19:44:00

3 files changed, 66 insertions, 42 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
index c16c66d62..bc68a0db9 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex
@@ -667,13 +667,33 @@ the node number of the nodes.
 
 \section{Images and Forms}
 
-\LUATEX\ accepts optional dimension parameters for \type {\pdfrefximage} and
-\type {\pdfrefxform} in the same format as for \type {\pdfximage}. With images,
-these dimensions are then used instead of the ones given to \type {\pdfximage}
-but the original dimensions are not overwritten, so that a \type {\pdfrefximage}
-without dimensions still provides the image with dimensions defined by \type
-{\pdfximage}. These optional parameters are not implemented for \type
-{\pdfxform}.
+These two concepts are now core concepts and no longer whatsits. They are in fact
+now implemented as rules with special properties. Normal rules have subtype~0,
+saved boxes have subtype~1 and images have subtype~2. This has the positive side
+effect that whenever we need to take content with dimensions into account, when we
+look at rule nodes, we automatically also deal with these two types.
+
+The syntax of the \type {\save...resource} is the same as in \PDFTEX\ but you
+should consider them to be backend specific. This means that a macro package
+should treat them as such and check for the current output mode if applicable.
+Here are the equivalents:
+
+\starttabulate[|l|l|]
+\NC \type {\saveboxresource}             \EQ \type {\pdfxform}           \NC \NR
+\NC \type {\saveimageresource}           \EQ \type {\pdfximage}          \NC \NR
+\NC \type {\useboxresource}              \EQ \type {\pdfrefxform}        \NC \NR
+\NC \type {\useimageresource}            \EQ \type {\pdfrefximage}       \NC \NR
+\NC \type {\lastsavedboxresourceindex}   \EQ \type {\pdflastxform}       \NC \NR
+\NC \type {\lastsavedimageresourceindex} \EQ \type {\pdflastximage}      \NC \NR
+\NC \type {\lastsavedimageresourcepages} \EQ \type {\pdflastximagepages} \NC \NR
+\stoptabulate
+
+\LUATEX\ accepts optional dimension parameters for \type {\use...resource} in the
+same format as for rules. With images, these dimensions are then used instead of
+the ones given to \type {\useimageresource} but the original dimensions are not
+overwritten, so that a \type {\useimageresource} without dimensions still
+provides the image with dimensions defined by \type {\saveimageresource}. These
+optional parameters are not implemented for \type {\saveboxresource}.
 
 \starttyping
 \pdfrefximage width 20mm height 10mm depth 5mm \pdflastximage
diff --git a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
index 9d3bd957e..28431fe29 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
@@ -257,6 +257,32 @@ which in turn triggered renaming primitives.
 
 \stopitemize
 
+One change involves the so called xforms and ximages. In \PDFTEX\ these are
+implemented as so called whatsits. But contrary to other whatsits they have
+dimensions that need to be taken into account when for instance calculating
+optimal linebreaks. In \LUATEX\ these are now promoted to normal nodes, which
+simplifies code that needs those dimensions.
+
+Another reason for promotion is that these are useful concepts. Backends can
+provide the ability to use content that has been rendered in several places,
+and images are also common. For that reason we also changed the names:
+
+\starttabulate[|l|l|]
+\NC \bf new name                         \NC \bf old name \NC \NR
+\NC \type {\saveboxresource}             \NC \type {\pdfxform}           \NC \NR
+\NC \type {\saveimageresource}           \NC \type {\pdfximage}          \NC \NR
+\NC \type {\useboxresource}              \NC \type {\pdfrefxform}        \NC \NR
+\NC \type {\useimageresource}            \NC \type {\pdfrefximage}       \NC \NR
+\NC \type {\lastsavedboxresourceindex}   \NC \type {\pdflastxform}       \NC \NR
+\NC \type {\lastsavedimageresourceindex} \NC \type {\pdflastximage}      \NC \NR
+\NC \type {\lastsavedimageresourcepages} \NC \type {\pdflastximagepages} \NC \NR
+\stoptabulate
+
+There are a few \type {\pdf...} primitives that relate to this but these are
+typical backend specific ones. The index that gets returned is to be considered
+as \quote {just a number} and although it still has the same meaning (object
+related) as before, you should not depend on that.
+
 \stopsubsection
 
 \startsubsection[title=Changes from \ALEPH\ RC4]
diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
index 6d4127341..9626190fc 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex
@@ -194,12 +194,18 @@ subtypes~0, 4, and~5.
 
 \subsubsection{rule nodes}
 
+\subsubsubsection{normal rules}
+
 Valid fields: \showfields{rule}\crlf
 Id: \showid{rule}
 
+We have three subtypes. Subtype~0 is just a normal rule, a rectangle
+filled with ink. Subtype~1 is a reusable box, while subtype_2 is an
+image.
+
 \starttabulate[|lT|l|p|]
 \NC \ssbf field \NC \bf type        \NC \bf explanation \NC \NR
-\NC subtype     \NC number          \NC unused \NC \NR
+\NC subtype     \NC number          \NC 0, 1 or 2 \NC \NR
 \NC attr        \NC \syntax{<node>} \NC \NC \NR
 \NC width       \NC number          \NC the width of the rule; the special value
                                         $-1073741824$ is used for \quote
@@ -210,8 +216,14 @@ Id: \showid{rule}
                                         negative) \NC \NR
 \NC dir         \NC string          \NC the direction of this rule,
                                         see~\in[dirnodes] \NC \NR
+\NC index       \NC number          \NC an optional index that can be referred
+                                        to (only for subtypes 1 and~2 and
+                                        backend specific). \NC \NR
 \stoptabulate
 
+The subtypes 1 and~2 replace the xform and ximage whatsits and in nodelists they
+behave like rules of subtype_0 when it comes to dimensions.
+
 \subsubsection{ins nodes}
 
 Valid fields: \showfields{ins}\crlf
@@ -364,7 +376,6 @@ Id: \showid{kern}
 \NC kern        \NC number          \NC \NC \NR
 \stoptabulate
 
-
 \subsubsection{penalty nodes}
 
 Valid fields: \showfields{penalty}\crlf
@@ -841,39 +852,6 @@ Id: \showid{whatsit,pdf_refobj}
 \NC objnum      \NC number          \NC the referenced \PDF\ object number \NC \NR
 \stoptabulate
 
-\subsubsection{pdf_refxform nodes}
-
-Valid fields: \showfields{whatsit,pdf_refxform}\crlf
-Id: \showid{whatsit,pdf_refxform}.
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf field \NC \bf type        \NC \bf explanation \NC \NR
-\NC attr        \NC \syntax{<node>} \NC \NC \NR
-\NC width       \NC number          \NC \NC \NR
-\NC height      \NC number          \NC \NC \NR
-\NC depth       \NC number          \NC \NC \NR
-\NC objnum      \NC number          \NC the referenced \PDF\ object number \NC \NR
-\stoptabulate
-
-Be aware that \type {pdf_refxform} nodes have dimensions that are used by \LUATEX.
-
-\subsubsection{pdf_refximage nodes}
-
-Valid fields: \showfields{whatsit,pdf_refximage}\crlf
-Id: \showid{whatsit,pdf_refximage}
-
-\starttabulate[|lT|l|p|]
-\NC \ssbf field \NC \bf type        \NC \bf explanation \NC \NR
-\NC attr        \NC \syntax{<node>} \NC \NC \NR
-\NC width       \NC number          \NC \NC \NR
-\NC height      \NC number          \NC \NC \NR
-\NC depth       \NC number          \NC \NC \NR
-\NC objnum      \NC number          \NC the referenced \PDF\ object number \NC \NR
-\stoptabulate
-
-Be aware that \type {pdf_refximage} nodes have dimensions that are used by
-\LUATEX.
-
 \subsubsection{pdf_annot nodes}
 
 Valid fields: \showfields{whatsit,pdf_annot}\crlf