summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-enhancements.tex34
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-modifications.tex26
-rw-r--r--doc/context/sources/general/manuals/luatex/luatex-nodes.tex48
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