2018-07-02 14:46:00

1 files changed, 174 insertions, 106 deletions

diff --git a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
index 72c4e72d7..b1b803d48 100644
--- a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
+++ b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex
@@ -1,4 +1,4 @@
-4% language=uk
+% language=uk
 
 \environment luatex-style
 
@@ -409,8 +409,8 @@ we say next applies to both these programs.
 \stopitem
 
 \startitem
-    \LUATEX\ only understands 4~of the 16~direction specifiers of \ALEPH: \orm
-    {TLT} (latin), \orm {TRT} (arabic), \orm {RTT} (cjk), \orm {LTL} (mongolian).
+    \LUATEX\ only understands 4~of the 16~direction specifiers of \ALEPH: \type
+    {TLT} (latin), \type {TRT} (arabic), \type {RTT} (cjk), \type {LTL} (mongolian).
     All other direction specifiers generate an error. In addition to a keyword
     driven model we also provide an integer driven one.
 \stopitem
@@ -543,7 +543,9 @@ different:
 
 \stopsection
 
-\startsection[reference=backendprimitives,title=The backend primitives \type {\pdf*}]
+\startsection[reference=backendprimitives,title=The backend primitives]
+
+\startsubsection[title={Less primitives}]
 
 \topicindex {backend}
 \topicindex {\PDF+backend}
@@ -568,6 +570,10 @@ An extension triggers further parsing, depending on the command given. A variabl
 a (kind of) register and can be read and written, while a feedback is reporting
 something (as it comes from the backend it's normally a sequence of tokens).
 
+\stopsubsection
+
+\startsubsection[title={\lpr{pdfextension}, \lpr {pdfvariable} and \lpr {pdffeedback}}]
+
 In order for \LUATEX\ to be more than just \TEX\ you need to enable primitives. That
 has already been the case right from the start. If you want the traditional \PDFTEX\
 primitives (for as far their functionality is still around) you now can do this:
@@ -676,101 +682,16 @@ macro:->[internal backend integer]
 macro:->[internal backend tokenlist]
 \stoptyping
 
-The \prm {edef} can also be a \prm {def} but it's a bit more efficient
-to expand the lookup related register beforehand. After that you can adapt
-the defaults; these are:
-
-\starttyping
-\pdfcompresslevel         9
-\pdfobjcompresslevel      1 % used: (0,9)
-\pdfrecompress            0 % mostly for debugging
-\pdfdecimaldigits         4 % used: (3,6)
-\pdfgamma              1000
-\pdfimageresolution      71
-\pdfimageapplygamma       0
-\pdfimagegamma         2200
-\pdfimagehicolor          1
-\pdfimageaddfilename      1
-\pdfpkresolution         72
-\pdfpkfixeddpi            0
-\pdfinclusioncopyfonts    0
-\pdfinclusionerrorlevel   0
-\pdfignoreunknownimages   0
-\pdfgentounicode          0
-\pdfomitcidset            0
-\pdfpagebox               0
-\pdfminorversion          4
-\pdfuniqueresname         0
-
-\pdfhorigin             1in
-\pdfvorigin             1in
-\pdflinkmargin          0pt
-\pdfdestmargin          0pt
-\pdfthreadmargin        0pt
-\pdfxformmargin         0pt
-\stoptyping
-
-If you also want some backward compatibility, you can add:
-
-\starttyping
-\let\pdfpagewidth      \pagewidth
-\let\pdfpageheight     \pageheight
-
-\let\pdfadjustspacing  \adjustspacing
-\let\pdfprotrudechars  \protrudechars
-\let\pdfnoligatures    \ignoreligaturesinfont
-\let\pdffontexpand     \expandglyphsinfont
-\let\pdfcopyfont       \copyfont
-
-\let\pdfxform          \saveboxresource
-\let\pdflastxform      \lastsavedboxresourceindex
-\let\pdfrefxform       \useboxresource
-
-\let\pdfximage         \saveimageresource
-\let\pdflastximage     \lastsavedimageresourceindex
-\let\pdflastximagepages\lastsavedimageresourcepages
-\let\pdfrefximage      \useimageresource
-
-\let\pdfsavepos        \savepos
-\let\pdflastxpos       \lastxpos
-\let\pdflastypos       \lastypos
-
-\let\pdfoutput         \outputmode
-\let\pdfdraftmode      \draftmode
-
-\let\pdfpxdimen        \pxdimen
-
-\let\pdfinsertht       \insertht
-
-\let\pdfnormaldeviate  \normaldeviate
-\let\pdfuniformdeviate \uniformdeviate
-\let\pdfsetrandomseed  \setrandomseed
-\let\pdfrandomseed     \randomseed
-
-\let\pdfprimitive      \primitive
-\let\ifpdfprimitive    \ifprimitive
-
-\let\ifpdfabsnum       \ifabsnum
-\let\ifpdfabsdim       \ifabsdim
-\stoptyping
-
-And even:
-
-\starttyping
-\newdimen\pdfeachlineheight
-\newdimen\pdfeachlinedepth
-\newdimen\pdflastlinedepth
-\newdimen\pdffirstlineheight
-\newdimen\pdfignoreddimen
-\stoptyping
+The \prm {edef} can also be a \prm {def} but it's a bit more efficient to expand
+the lookup related register beforehand.
 
 The backend is derived from \PDFTEX\ so the same syntax applies. However, the
 \type {outline} command accepts a \type {objnum} followed by a number. No
 checking takes place so when this is used it had better be a valid (flushed)
 object.
 
-In order to be (more or less) compatible with \PDFTEX\ we also support the
-option to suppress some info:
+In order to be (more or less) compatible with \PDFTEX\ we also support the option
+to suppress some info but we do so via a bitset:
 
 \starttyping
 \pdfvariable suppressoptionalinfo \numexpr
@@ -790,7 +711,7 @@ option to suppress some info:
 
 In addition you can overload the trailer id, but we don't do any checking on
 validity, so you have to pass a valid array. The following is like the ones
-normally generated by the engine:
+normally generated by the engine. You even need to include the brackets here!
 
 \starttyping
 \pdfvariable trailerid {[
@@ -799,8 +720,6 @@ normally generated by the engine:
 ]}
 \stoptyping
 
-So, you even need to include the brackets!
-
 Although we started from a merge of \PDFTEX\ and \ALEPH, by now the code base as
 well as functionality has diverted from those parents. Here we show the options
 that can be passed to the extensions.
@@ -948,6 +867,102 @@ that can be passed to the extensions.
     {tokens}
 \stoptexsyntax
 
+\stopsubsection
+
+\startsubsection[title={Defaults}]
+
+The engine sets the following defaults.
+
+\starttyping
+\pdfcompresslevel         9
+\pdfobjcompresslevel      1 % used: (0,9)
+\pdfrecompress            0 % mostly for debugging
+\pdfdecimaldigits         4 % used: (3,6)
+\pdfgamma              1000
+\pdfimageresolution      71
+\pdfimageapplygamma       0
+\pdfimagegamma         2200
+\pdfimagehicolor          1
+\pdfimageaddfilename      1
+\pdfpkresolution         72
+\pdfpkfixeddpi            0
+\pdfinclusioncopyfonts    0
+\pdfinclusionerrorlevel   0
+\pdfignoreunknownimages   0
+\pdfgentounicode          0
+\pdfomitcidset            0
+\pdfpagebox               0
+\pdfminorversion          4
+\pdfuniqueresname         0
+
+\pdfhorigin             1in
+\pdfvorigin             1in
+\pdflinkmargin          0pt
+\pdfdestmargin          0pt
+\pdfthreadmargin        0pt
+\pdfxformmargin         0pt
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={Backward compatibility}]
+
+If you also want some backward compatibility, you can add:
+
+\starttyping
+\let\pdfpagewidth      \pagewidth
+\let\pdfpageheight     \pageheight
+
+\let\pdfadjustspacing  \adjustspacing
+\let\pdfprotrudechars  \protrudechars
+\let\pdfnoligatures    \ignoreligaturesinfont
+\let\pdffontexpand     \expandglyphsinfont
+\let\pdfcopyfont       \copyfont
+
+\let\pdfxform          \saveboxresource
+\let\pdflastxform      \lastsavedboxresourceindex
+\let\pdfrefxform       \useboxresource
+
+\let\pdfximage         \saveimageresource
+\let\pdflastximage     \lastsavedimageresourceindex
+\let\pdflastximagepages\lastsavedimageresourcepages
+\let\pdfrefximage      \useimageresource
+
+\let\pdfsavepos        \savepos
+\let\pdflastxpos       \lastxpos
+\let\pdflastypos       \lastypos
+
+\let\pdfoutput         \outputmode
+\let\pdfdraftmode      \draftmode
+
+\let\pdfpxdimen        \pxdimen
+
+\let\pdfinsertht       \insertht
+
+\let\pdfnormaldeviate  \normaldeviate
+\let\pdfuniformdeviate \uniformdeviate
+\let\pdfsetrandomseed  \setrandomseed
+\let\pdfrandomseed     \randomseed
+
+\let\pdfprimitive      \primitive
+\let\ifpdfprimitive    \ifprimitive
+
+\let\ifpdfabsnum       \ifabsnum
+\let\ifpdfabsdim       \ifabsdim
+\stoptyping
+
+And even:
+
+\starttyping
+\newdimen\pdfeachlineheight
+\newdimen\pdfeachlinedepth
+\newdimen\pdflastlinedepth
+\newdimen\pdffirstlineheight
+\newdimen\pdfignoreddimen
+\stoptyping
+
+\stopsubsection
+
 \stopsection
 
 \startsection[title=Directions]
@@ -956,6 +971,8 @@ that can be passed to the extensions.
 \topicindex {\ALEPH}
 \topicindex {directions}
 
+\startsubsection[title={Four directions}]
+
 The directional model in \LUATEX\ is inherited from \OMEGA|/|\ALEPH\ but we tried
 to improve it a bit. At some point we played with recovery of modes but that was
 disabled later on when we found that it interfered with nested directions. That
@@ -963,14 +980,23 @@ itself had as side effect that the node list was no longer balanced with respect
 to directional nodes which in turn can give side effects when a series of dir
 changes happens without grouping.
 
-The current (0.97 onward) approach is that we again make the list balanced but
-try to avoid some side effects. What happens is quite intuitive if we forget
-about spaces (turned into glue) but even there what happens makes sense if you
-look at it in detail. However that logic makes in|-|group switching kind of
-useless when no proper nested grouping is used: switching from right to left
-several times nested, results in spacing ending up after each other due to nested
-mirroring. Of course a sane macro package will manage this for the user but here
-we are discussing the low level dir injection.
+When extending the \PDF\ backend to support directions some inconsistencies were
+found and as a result we decided to support only the four models that make sense
+\type {TLT} (latin), \type {TRT} (arabic), \type {RTT} (cjk) and \type {LTL}
+(mongolian).
+
+\stopsubsection
+
+\startsubsection[title={How it works}]
+
+The approach is that we again make the list balanced but try to avoid some side
+effects. What happens is quite intuitive if we forget about spaces (turned into
+glue) but even there what happens makes sense if you look at it in detail.
+However that logic makes in|-|group switching kind of useless when no proper
+nested grouping is used: switching from right to left several times nested,
+results in spacing ending up after each other due to nested mirroring. Of course
+a sane macro package will manage this for the user but here we are discussing the
+low level dir injection.
 
 This is what happens:
 
@@ -1087,6 +1113,10 @@ kerns, should be handled in the input or macro package because there is no way w
 can predict the expected behaviour. In fact, the \lpr {linedir} is just a
 convenience extra which could also have been implemented using node list parsing.
 
+\stopsubsection
+
+\startsubsection[title={Controlling glue with \lpr {breakafterdirmode}}]
+
 Glue after a dir node is ignored in the linebreak decision but you can bypass that
 by setting \lpr {breakafterdirmode} to~\type {1}. The following table shows the
 difference. Watch your spaces.
@@ -1117,6 +1147,10 @@ difference. Watch your spaces.
     \LL
 \stoptabulate
 
+\stopsubsection
+
+\startsubsection[title={Controling parshapes with \lpr {shapemode}}]
+
 Another adaptation to the \ALEPH\ directional model is control over shapes driven
 by \prm {hangindent} and \prm {parshape}. This is controlled by a new parameter
 \lpr {shapemode}:
@@ -1178,6 +1212,38 @@ this. In \in {figure} [fig:shapemode] a few examples are given.
     \stopcombination
 \stopplacefigure
 
+\stopsubsection
+
+\startsubsection[title={Symbols or numbers}]
+
+Internally the implementation is different from \ALEPH. First of all we use no
+whatsits but dedicated nodes, but also we have only 4 directions that are mapped
+onto 4 numbers. A text direction node can mark the start or end of a sequence of
+nodes, and therefore has two states. At the \TEX\ end we don't see these states
+because \TEX\ itself will add proper end state nodes if needed.
+
+The symbolic names \type {TLT}, \type {TRT}, etc.\ originate in \OMEGA. In
+\LUATEX\ we also have a number based model which sometimes makes more sense.
+
+\starttabulate[|c|l|l|]
+\DB value     \BC equivalent \NC \NR
+\TB
+\BC \type {0} \NC TLT \NC \NR
+\BC \type {1} \NC TRT \NC \NR
+\BC \type {2} \NC LTL \NC \NR
+\BC \type {3} \NC RTT \NC \NR
+\LL
+\stoptabulate
+
+We support the \OMEGA\ primitives \orm {textdir}, \orm {pardir}, \orm {pagedir},
+\orm {pardir} and \orm {mathdir}. These accept three character keywords. The
+primitives that set the direction by number are: \lpr {textdirection}, \lpr
+{pardirection}, \lpr {pagedirection} and \lpr {bodydirection} and \lpr
+{mathdirection}. When specifying a direction for a box you can use \type {bdir}
+instead of \type {dir}.
+
+\stopsubsection
+
 \stopsection
 
 \startsection[title=Implementation notes]
@@ -1255,13 +1321,15 @@ control sequences that uses a prefix that is otherwise impossible to obtain.
 
 \stopsubsection
 
-\startsubsection[title=Compressed format]
+\startsubsection[title=The compressed format file]
 
 \topicindex {format}
 
 The format is passed through \type {zlib}, allowing it to shrink to roughly half
 of the size it would have had in uncompressed form. This takes a bit more \CPU\
-cycles but much less disk \IO, so it should still be faster.
+cycles but much less disk \IO, so it should still be faster. We use a level~3
+compression which we found to be the optimal trade|-|off between filesize and
+decompression speed.
 
 \stopsubsection