summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-backend.tex
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/luatex/luatex-backend.tex')
-rw-r--r--systems/doc/luatex/luatex-backend.tex2168
1 files changed, 1084 insertions, 1084 deletions
diff --git a/systems/doc/luatex/luatex-backend.tex b/systems/doc/luatex/luatex-backend.tex
index 21cdd728c1..e99a95ed26 100644
--- a/systems/doc/luatex/luatex-backend.tex
+++ b/systems/doc/luatex/luatex-backend.tex
@@ -1,1084 +1,1084 @@
-% language=uk
-
-\environment luatex-style
-
-\startcomponent luatex-backend
-
-\startchapter[reference=backend,title={The backend libraries}]
-
-\startsection[title={The \type {pdf} library}][library=pdf]
-
-\topicindex{backend}
-\topicindex{\PDF}
-
-This library contains variables and functions that are related to the \PDF\
-backend. You can find more details about the expected values to setters in \in
-{section} [backendprimitives].
-
-\startsubsection[title={\type {mapfile}, \type {mapline}}]
-
-\topicindex{map files}
-\topicindex{files+map}
-
-\startfunctioncall
-pdf.mapfile(<string> map file)
-pdf.mapline(<string> map line)
-\stopfunctioncall
-
-These two functions can be used to replace primitives \orm {pdfmapfile} and
-\orm {pdfmapline} inherited from \PDFTEX. They expect a string as only
-parameter and have no return value. The first character in a map line can be
-\type {-}, \type {+} or \type {=} which means as much as remove, add or replace
-this line. They are not state setters but act immediately.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][catalog|info|names|trailer]}}]
-
-\topicindex{\PDF+trailer}
-\topicindex{\PDF+catalog}
-\topicindex{\PDF+info}
-
-\libindex{setcatalog} \libindex{getcatalog}
-\libindex{setinfo} \libindex{getinfo}
-\libindex{setnames} \libindex{getnames}
-\libindex{settrailer} \libindex{gettrailer}
-
-These functions complement the corresponding \PDF\ backend token lists dealing
-with metadata. The value types are strings and they are written to the \PDF\
-file directly after the token registers set at the \TEX\ end are written.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][pageattributes|pageresources|pagesattributes]}}]
-
-\libindex{setpageattributes} \libindex{getpageattributes}
-\libindex{setpageresources} \libindex{getpageresources}
-\libindex{setpagesattributes} \libindex{getpagesattributes}
-
-\topicindex{\PDF+page attributes}
-\topicindex{\PDF+page resources}
-
-These functions complement the corresponding \PDF\ backend token lists dealing
-with page resources. The variables have no interaction with the corresponding \PDF\
-backend token register. They are written to the \PDF\ file directly after the
-token registers set at the \TEX\ end are written.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][xformattributes|xformresources]}}]
-
-\libindex{setxformattributes} \libindex{getxformattributes}
-\libindex{setxformresources} \libindex{getxformresources}
-
-\topicindex{\PDF+xform attributes}
-\topicindex{\PDF+xform resources}
-
-These functions complement the corresponding \PDF\ backend token lists dealing
-with reuseable boxes and images. The variables have no interaction with the
-corresponding \PDF\ backend token register. They are written to the \PDF\
-file directly after the token registers set at the \TEX\ end are written.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][major|minor]version}}]
-
-\topicindex{\PDF+version}
-
-\libindex{getmajorversion} \libindex{setmajorversion}
-\libindex{getminorversion} \libindex{setminorversion}
-
-You can set both the major and minor version of the output. The major version is
-normally~1 but when set to~2 some data will not be written to the file in order
-to comply with the standard. What minor version you set depends on what \PDF\
-features you use. This is out of control of \LUATEX.
-
-\stopsubsection
-
-\startsubsection[title={\type {getcreationdate}}]
-
-\topicindex{\PDF+date}
-
-\libindex{getcreationdate}
-
-This function returns a string with the date in the format that ends up in the
-\PDF\ file, in this case it's: {\tttf \cldcontext{pdf.getcreationdate()}}.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]inclusionerrorlevel} and \type {[set|get]ignoreunknownimages}}]
-
-\topicindex{\PDF+options}
-
-\libindex{getinclusionerrorlevel} \libindex{setinclusionerrorlevel}
-\libindex{getignoreunknownimages} \libindex{setignoreunknownimages}
-
-These variable control how error in included image are treated. They are modeled
-after the \PDFTEX\ equivalents.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]suppressoptionalinfo}, \type {[set|get]trailerid}
-and \type {[set|get]omitcidset}}]
-
-\topicindex{\PDF+options}
-\topicindex{\PDF+trailer}
-
-\libindex{getsuppressoptionalinfo} \libindex{setsuppressoptionalinfo}
-\libindex{gettrailerid} \libindex{settrailerid}
-\libindex{getomitcidset} \libindex{setomitcidset}
-\libindex{getomitcharset} \libindex{setomitcharset}
-
-The optional info bitset (a number) determines what kind of info gets flushed.
-By default we flush all. See \in {section} [sec:pdfextensions] for more details.
-
-You can set your own trailer id. This has to be string containing valid \PDF\
-array content with checksums.
-
-The cidset and charset flags (numbers) disables inclusion of a so called \type
-{CIDSet} and \type {CharSet} entries, which can be handy when aiming at some of
-the many \PDF\ substandards.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][obj|]compresslevel} and \type {[set|get]recompress}}]
-
-\topicindex{\PDF+compression}
-
-\libindex{getcompresslevel} \libindex{setcompresslevel}
-\libindex{getobjcompresslevel} \libindex{setobjcompresslevel}
-\libindex{getrecompress} \libindex{setrecompress}
-
-These functions set the level stream compression. When object compression is
-enabled multiple objects will be packed in a compressed stream which saves space.
-The minimum values are~0, the maxima are~9.
-
-When recompression is to~1 compressed objects will be decompressed and when
-compresslevel is larger than zero they will then be recompressed. This is mostly
-a debugging feature and should not be relied upon.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]gentounicode}}]
-
-\topicindex{\PDF+unicode}
-
-\libindex{getgentounicode} \libindex{setgentounicode}
-
-This flag enables tounicode generation (like in \PDFTEX). Normally the values are
-provided by the font loader.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]decimaldigits}}]
-
-\topicindex{\PDF+precision}
-
-\libindex{getdecimaldigits} \libindex{setdecimaldigits}
-
-These two functions set the accuracy of floats written to the \PDF file. You can
-set any value but the backend will not go below~3 and above~6.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]pkresolution}}]
-
-\topicindex{\PDF+resolution}
-
-\libindex{getpkresolution} \libindex{setpkresolution}
-
-These setter takes two arguments: the resolution and an optional zero or one that
-indicates if this is a fixed one. The getter returns these two values.
-
-\stopsubsection
-
-\startsubsection[title={\type {getlast[obj|link|annot]} and \type {getretval}}]
-
-\topicindex{\PDF+objects}
-\topicindex{\PDF+annotations}
-
-\libindex{getlastobj} \libindex{setlastobj}
-\libindex{getlastlink} \libindex{setlastlink}
-\libindex{getlastannot} \libindex{setlastannot}
-\libindex{getretval}
-
-These status variables are similar to the ones traditionally used in the backend
-interface at the \TEX\ end.
-
-\stopsubsection
-
-\startsubsection[title={\type {getmaxobjnum} and \type {getobjtype}, \type {getfontname},
-\type {getfontobjnum}, \type {getfontsize}, \type {getxformname}}]
-
-\libindex{getmaxobjnum}
-\libindex{getobjtype}
-\libindex{getfontname}
-\libindex{getfontobjnum}
-\libindex{getfontsize}
-\libindex{getxformname}
-
-These introspective helpers are mostly used when you construct \PDF\ objects
-yourself and need for instance information about a (to be) embedded font.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]origin}}]
-
-\topicindex{\PDF+positioning}
-
-\libindex{setorigin} \libindex{getorigin}
-
-This one is used to set the horizonal and|/|or vertical offset, a traditional
-backend property.
-
-\starttyping
-pdf.setorigin() -- sets both to 0pt
-pdf.setorigin(tex.sp("1in")) -- sets both to 1in
-pdf.setorigin(tex.sp("1in"),tex.sp("1in"))
-\stoptyping
-
-The counterpart of this function returns two values.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get]imageresolution}}]
-
-\topicindex{\PDF+resolution}
-
-\libindex{setimageresolution} \libindex{getimageresolution}
-
-These two functions relate to the imageresolution that is used when the image
-itself doesn't provide a non|-|zero x or y resolution.
-
-\stopsubsection
-
-\startsubsection[title={\type {[set|get][link|dest|thread|xform]margin}}]
-
-\topicindex{\PDF+margins}
-
-\libindex{getlinkmargin} \libindex{setlinkmargin}
-\libindex{getdestmargin} \libindex{setdestmargin}
-\libindex{getthreadmargin} \libindex{setthreadmargin}
-\libindex{getxformmargin} \libindex{setxformmargin}
-\libindex{getmarginmargin} \libindex{setmarginmargin}
-
-These functions can be used to set and retrieve the margins that are added to the
-natural bounding boxes of the respective objects.
-
-\stopsubsection
-
-\startsubsection[title={\type {get[pos|hpos|vpos]}}]
-
-\topicindex{\PDF+positions}
-
-\libindex{getpos}
-\libindex{gethpos}
-\libindex{getvpos}
-
-These functions get current location on the output page, measured from its lower
-left corner. The values return scaled points as units.
-
-\starttyping
-local h, v = pdf.getpos()
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {[has|get]matrix}}]
-
-\topicindex{\PDF+matrix}
-
-\libindex{getmatrix} \libindex{hasmatrix}
-
-The current matrix transformation is available via the \type {getmatrix} command,
-which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type
-{tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a
-matrix is applied.
-
-\starttyping
-if pdf.hasmatrix() then
- local sx, rx, ry, sy, tx, ty = pdf.getmatrix()
- -- do something useful or not
-end
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {print}}]
-
-\topicindex{\PDF+print to}
-
-\libindex{print}
-
-You can print a string to the \PDF\ document from within a \lpr {latelua} call.
-This function is not to be used inside \prm {directlua} unless you know {\it
-exactly} what you are doing.
-
-\startfunctioncall
-pdf.print(<string> s)
-pdf.print(<string> type, <string> s)
-\stopfunctioncall
-
-The optional parameter can be used to mimic the behavior of \PDF\ literals: the
-\type {type} is \type {direct} or \type {page}.
-
-\stopsubsection
-
-\startsubsection[title={\type {immediateobj}}]
-
-\topicindex{\PDF+objects}
-
-\libindex{immediateobj}
-
-This function creates a \PDF\ object and immediately writes it to the \PDF\ file.
-It is modelled after \PDFTEX's \prm {immediate} \orm {pdfobj} primitives. All
-function variants return the object number of the newly generated object.
-
-\startfunctioncall
-<number> n =
- pdf.immediateobj(<string> objtext)
-<number> n =
- pdf.immediateobj("file", <string> filename)
-<number> n =
- pdf.immediateobj("stream", <string> streamtext, <string> attrtext)
-<number> n =
- pdf.immediateobj("streamfile", <string> filename, <string> attrtext)
-\stopfunctioncall
-
-The first version puts the \type {objtext} raw into an object. Only the object
-wrapper is automatically generated, but any internal structure (like \type {<<
->>} dictionary markers) needs to be provided by the user. The second version with
-keyword \type {file} as first argument puts the contents of the file with name
-\type {filename} raw into the object. The third version with keyword \type
-{stream} creates a stream object and puts the \type {streamtext} raw into the
-stream. The stream length is automatically calculated. The optional \type
-{attrtext} goes into the dictionary of that object. The fourth version with
-keyword \type {streamfile} does the same as the third one, it just reads the
-stream data raw from a file.
-
-An optional first argument can be given to make the function use a previously
-reserved \PDF\ object.
-
-\startfunctioncall
-<number> n =
- pdf.immediateobj(<integer> n, <string> objtext)
-<number> n =
- pdf.immediateobj(<integer> n, "file", <string> filename)
-<number> n =
- pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext)
-<number> n =
- pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext)
-\stopfunctioncall
-
-\stopsubsection
-
-\startsubsection[title={\type{obj}}]
-
-\topicindex{\PDF+objects}
-
-\libindex{obj}
-
-This function creates a \PDF\ object, which is written to the \PDF\ file only
-when referenced, e.g., by \type {refobj()}.
-
-All function variants return the object number of the newly generated object, and
-there are two separate calling modes. The first mode is modelled after \PDFTEX's
-\orm {pdfobj} primitive.
-
-\startfunctioncall
-<number> n =
- pdf.obj(<string> objtext)
-<number> n =
- pdf.obj("file", <string> filename)
-<number> n =
- pdf.obj("stream", <string> streamtext, <string> attrtext)
-<number> n =
- pdf.obj("streamfile", <string> filename, <string> attrtext)
-\stopfunctioncall
-
-An optional first argument can be given to make the function use a previously
-reserved \PDF\ object.
-
-\startfunctioncall
-<number> n =
- pdf.obj(<integer> n, <string> objtext)
-<number> n =
- pdf.obj(<integer> n, "file", <string> filename)
-<number> n =
- pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext)
-<number> n =
- pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext)
-\stopfunctioncall
-
-The second mode accepts a single argument table with key--value pairs.
-
-\startfunctioncall
-<number> n = pdf.obj {
- type = <string>,
- immediate = <boolean>,
- objnum = <number>,
- attr = <string>,
- compresslevel = <number>,
- objcompression = <boolean>,
- file = <string>,
- string = <string>,
- nolength = <boolean>,
-}
-\stopfunctioncall
-
-The \type {type} field can have the values \type {raw} and \type {stream}, this
-field is required, the others are optional (within constraints). When \type
-{nolength} is set, there will be no \type {/Length} entry added to the
-dictionary.
-
-Note: this mode makes \type{obj} look more flexible than it actually is: the
-constraints from the separate parameter version still apply, so for example you
-can't have both \type {string} and \type {file} at the same time.
-
-\stopsubsection
-
-\startsubsection[title={\type {refobj}}]
-
-\topicindex{\PDF+objects}
-
-\libindex{refobj}
-
-This function, the \LUA\ version of the \orm {pdfrefobj} primitive, references an
-object by its object number, so that the object will be written to the \PDF\ file.
-
-\startfunctioncall
-pdf.refobj(<integer> n)
-\stopfunctioncall
-
-This function works in both the \prm {directlua} and \lpr {latelua} environment.
-Inside \prm {directlua} a new whatsit node \quote {pdf_refobj} is created, which
-will be marked for flushing during page output and the object is then written
-directly after the page, when also the resources objects are written to the \PDF\
-file. Inside \lpr {latelua} the object will be marked for flushing.
-
-This function has no return values.
-
-\stopsubsection
-
-\startsubsection[title={\type {reserveobj}}]
-
-\topicindex{\PDF+objects}
-
-\libindex{reserveobj}
-
-This function creates an empty \PDF\ object and returns its number.
-
-\startfunctioncall
-<number> n = pdf.reserveobj()
-<number> n = pdf.reserveobj("annot")
-\stopfunctioncall
-
-\stopsubsection
-
-\startsubsection[title={\type {getpageref}}]
-
-\topicindex{\PDF+pages}
-
-\libindex{getpageref}
-
-The object number of a page can be fetched with this function. This can be a
-forward reference so when you ask for a future page, you do get a number back.
-
-\startfunctioncall
-<number> n = pdf.getpageref(123)
-\stopfunctioncall
-
-\stopsubsection
-
-\startsubsection[title={\type {registerannot}}]
-
-\topicindex{\PDF+annotations}
-
-\libindex{registerannot}
-
-This function adds an object number to the \type {/Annots} array for the current
-page without doing anything else. This function can only be used from within
-\lpr {latelua}.
-
-\startfunctioncall
-pdf.registerannot (<number> objnum)
-\stopfunctioncall
-
-\stopsubsection
-
-\startsubsection[title={\type {newcolorstack}}]
-
-\topicindex{\PDF+color stack}
-
-\libindex{newcolorstack}
-
-This function allocates a new color stack and returns it's id. The arguments
-are the same as for the similar backend extension primitive.
-
-\startfunctioncall
-pdf.newcolorstack("0 g","page",true) -- page|direct|origin
-\stopfunctioncall
-
-\stopsubsection
-
-\startsubsection[title={\type {setfontattributes}}]
-
-\topicindex{\PDF+fonts}
-
-\libindex{setfontattributes}
-
-This function will force some additional code into the font resource. It can for
-instance be used to add a custom \type {ToUnicode} vector to a bitmap file.
-
-\startfunctioncall
-pdf.setfontattributes(<number> font id, <string> pdf code)
-\stopfunctioncall
-
-\stopsubsection
-
-\stopsection
-
-\startsection[title={The \type {pdfe} library}][library=pdfe]
-
-\startsubsection[title={Introduction}]
-
-\topicindex{\PDF+objects}
-
-\topicindex{\PDF+analyze}
-\topicindex{\PDF+\type{pdfe}}
-
-The \type {pdfe} library replaces the \type {epdf} library and provides an
-interface to \PDF\ files. It uses the same code as is used for \PDF\ image
-inclusion. The \type {pplib} library by Paweł Jackowski replaces the \type
-{poppler} (derived from \type {xpdf}) library.
-
-A \PDF\ file is basically a tree of objects and one descends into the tree via
-dictionaries (key/value) and arrays (index/value). There are a few topmost
-dictionaries that start at root that are accessed more directly.
-
-Although everything in \PDF\ is basically an object we only wrap a few in so
-called userdata \LUA\ objects.
-
-\starttabulate
-\BC \PDF \BC \LUA \NC \NR
-\NC null \NC nil \NC \NR
-\NC boolean \NC boolean \NC \NR
-\NC integer \NC integer \NC \NR
-\NC float \NC number \NC \NR
-\NC name \NC string \NC \NR
-\NC string \NC string \NC \NR
-\NC array \NC array userdatum \NC \NR
-\NC dictionary \NC dictionary userdatum \NC \NR
-\NC stream \NC stream userdatum (with related dictionary) \NC \NR
-\NC reference \NC reference userdatum \NC \NR
-\stoptabulate
-
-The regular getters return these \LUA\ data types but one can also get more
-detailed information.
-
-\stopsubsection
-
-\startsubsection[title={\type {open}, \type {new}, \type {getstatus}, \type {close}, \type {unencrypt}}]
-
-\libindex {open}
-\libindex {new}
-\libindex {new}
-\libindex {getstatus}
-\libindex {close}
-\libindex {unencrypt}
-
-A document is loaded from a file or string
-
-\starttyping
-<pdfe document> = pdfe.open(filename)
-<pdfe document> = pdfe.new(somestring,somelength)
-\stoptyping
-
-Such a document is closed with:
-
-\starttyping
-pdfe.close(<pdfe document>)
-\stoptyping
-
-You can check if a document opened well by:
-
-\starttyping
-pdfe.getstatus(<pdfe document>)
-\stoptyping
-
-The returned codes are:
-
-\starttabulate[|c|l|]
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type {-2} \NC the document failed to open \NC \NR
-\NC \type {-1} \NC the document is (still) protected \NC \NR
-\NC \type {0} \NC the document is not encrypted \NC \NR
-\NC \type {2} \NC the document has been unencrypted \NC \NR
-\LL
-\stoptabulate
-
-An encrypted document can be unencrypted by the next command where instead of
-either password you can give \type {nil}:
-
-\starttyping
-pdfe.unencrypt(<pdfe document>,userpassword,ownerpassword)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {getsize}, \type {getversion}, \type {getnofobjects}, \type {getnofpages}}]
-
-\libindex {getsize}
-\libindex {getversion}
-\libindex {getnofobjects}
-\libindex {getnofpages}
-
-A successfully opened document can provide some information:
-
-\starttyping
-bytes = getsize(<pdfe document>)
-major, minor = getversion(<pdfe document>)
-n = getnofobjects(<pdfe document>)
-n = getnofpages(<pdfe document>)
-bytes, waste = getnofpages(<pdfe document>)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {get[catalog|trailer|info]}}]
-
-\libindex {getcatalog}
-\libindex {gettrailer}
-\libindex {getinfo}
-
-For accessing the document structure you start with the so called catalog, a
-dictionary:
-
-\starttyping
-<pdfe dictionary> = pdfe.getcatalog(<pdfe document>)
-\stoptyping
-
-The other two root dictionaries are accessed with:
-
-\starttyping
-<pdfe dictionary> = pdfe.gettrailer(<pdfe document>)
-<pdfe dictionary> = pdfe.getinfo(<pdfe document>)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {getpage}, \type {getbox}}]
-
-\libindex {getpage}
-\libindex {getbox}
-
-A specific page can conveniently be reached with the next command, which
-returns a dictionary. The first argument is to be a page dictionary.
-
-\starttyping
-<pdfe dictionary> = pdfe.getpage(<pdfe dictionary>,pagenumber)
-\stoptyping
-
-Another convenience command gives you the (bounding) box of a (normally page)
-which can be inheritted from the document itself. An example of a valid box name
-is \type {MediaBox}.
-
-\starttyping
-pages = pdfe.getbox(<pdfe document>,boxname)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {get[string|integer|number|boolean|name]}}]
-
-\libindex {getstring}
-\libindex {getinteger}
-\libindex {getnumber}
-\libindex {getboolean}
-\libindex {getname}
-
-Common values in dictionaries and arrays are strings, integers, floats, booleans
-and names (which are also strings) and these are also normal \LUA\ objects:
-
-\starttyping
-s = getstring (<pdfe array|dictionary>,index|key)
-i = getinteger(<pdfe array|dictionary>,index|key)
-n = getnumber (<pdfe array|dictionary>,index|key)
-b = getboolean(<pdfe array|dictionary>,index|key)
-n = getname (<pdfe array|dictionary>,index|key)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {get[from][dictionary|array|stream]}}]
-
-\libindex {getdictionary} \libindex {getfromdictionary}
-\libindex {getarray} \libindex {getfromarray}
-\libindex {getstream} \libindex {getfromstream}
-
-Normally you will use an index in an array and key in a dictionary but dictionaries
-also accept an index. The size of an array or dictionary is available with the
-usual \type {#} operator.
-
-\starttyping
-<pdfe dictionary> = getdictionary(<pdfe array|dictionary>,index|key)
-<pdfe array> = getarray (<pdfe array|dictionary>,index|key)
-<pdfe stream>,
-<pdfe dictionary> = getstream (<pdfe array|dictionary>,index|key)
-\stoptyping
-
-These commands return dictionaries, arrays and streams, which are dictionaries
-with a blob of data attached.
-
-Before we come to an alternative access mode, we mention that the objects provide
-access in a different way too, for instance this is valid:
-
-\starttyping
-print(pdfe.open("foo.pdf").Catalog.Type)
-\stoptyping
-
-At the topmost level there are \type {Catalog}, \type {Info}, \type {Trailer}
-and \type {Pages}, so this is also okay:
-
-\starttyping
-print(pdfe.open("foo.pdf").Pages[1])
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {[open|close|readfrom][whole|]stream}}]
-
-\libindex {openstream}
-\libindex {closestream}
-\libindex {readfromstream}
-\libindex {readfromwholestream}
-
-Streams are sort of special. When your index or key hits a stream you get back a
-stream object and dictionary object. The dictionary you can access in the usual
-way and for the stream there are the following methods:
-
-\starttyping
-okay = openstream(<pdfe stream>,[decode])
- closestream(<pdfe stream>)
-str, n = readfromstream(<pdfe stream>)
-str, n = readwholestream(<pdfe stream>,[decode])
-\stoptyping
-
-You either read in chunks, or you ask for the whole. When reading in chunks, you
-need to open and close the stream yourself. The \type {n} value indicates the
-length read. The \type {decode} parameter controls if the stream data gets
-uncompressed.
-
-As with dictionaries, you can access fields in a stream dictionary in the usual
-\LUA\ way too. You get the content when you \quote {call} the stream. You can
-pass a boolean that indicates if the stream has to be decompressed.
-
-% pdfe.objectcodes = objectcodes
-% pdfe.stringcodes = stringcodes
-% pdfe.encryptioncodes = encryptioncodes
-
-\stopsubsection
-
-\startsubsection[title={\type {getfrom[dictionary|array]}}]
-
-\libindex {getfromdictionary}
-\libindex {getfromarray}
-
-In addition to the interface described before, there is also a bit lower level
-interface available.
-
-\starttyping
-key, type, value, detail = getfromdictionary(<pdfe dictionary>,index)
-type, value, detail = getfromarray(<pdfe array>,index)
-\stoptyping
-
-\starttabulate[|c|l|l|l|]
-\DB type \BC meaning \BC value \BC detail \NC \NR
-\NC \type {0} \NC none \NC nil \NC \NC \NR
-\NC \type {1} \NC null \NC nil \NC \NC \NR
-\NC \type {2} \NC boolean \NC boolean \NC \NC \NR
-\NC \type {3} \NC boolean \NC integer \NC \NC \NR
-\NC \type {4} \NC number \NC float \NC \NC \NR
-\NC \type {5} \NC name \NC string \NC \NC \NR
-\NC \type {6} \NC string \NC string \NC hex \NC \NR
-\NC \type {7} \NC array \NC arrayobject \NC size \NC \NR
-\NC \type {8} \NC dictionary \NC dictionaryobject \NC size \NC \NR
-\NC \type {9} \NC stream \NC streamobject \NC dictionary size \NC \NR
-\NC \type {10} \NC reference \NC integer \NC \NC \NR
-\LL
-\stoptabulate
-
-A \type {hex} string is (in the \PDF\ file) surrounded by \type {<>} while plain
-strings are bounded by \type {<>}.
-
-\stopsubsection
-
-\startsubsection[title={\type {[dictionary|array]totable}}]
-
-\libindex {dictionarytotable}
-\libindex {arraytotable}
-
-All entries in a dictionary or table can be fetched with the following commands
-where the return values are a hashed or indexed table.
-
-\starttyping
-hash = dictionarytotable(<pdfe dictionary>)
-list = arraytotable(<pdfe array>)
-\stoptyping
-
-You can get a list of pages with:
-
-\starttyping
-{ { <pdfe dictionary>, size, objnum }, ... } = pagestotable(<pdfe document>)
-\stoptyping
-
-\stopsubsection
-
-\startsubsection[title={\type {getfromreference}}]
-
-\libindex {getfromreference}
-
-Because you can have unresolved references, a reference object can be resolved
-with:
-
-\starttyping
-<pdfe dictionary|array|stream> = getfromreference(<pdfe reference>)
-\stoptyping
-
-So, you get back a new \type {pdfe} userdata object that you can query.
-
-\stopsubsection
-
-\stopsection
-
-\startsection[title={Memory streams}][library=pdfe]
-
-\topicindex{\PDF+memory streams}
-
-\libindex {new}
-
-The \type {pdfe.new} that takes three arguments:
-
-\starttabulate
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata
- object, i.e.\ a pointer to a sequence of bytes \NC \NR
-\NC \type {length} \NC this is the length of the stream in bytes (the stream can
- have embedded zeros) \NC \NR
-\NC \type {name} \NC optional, this is a unique identifier that is used for
- hashing the stream, so that multiple doesn't use more
- memory \NC \NR
-\LL
-\stoptabulate
-
-The third argument is optional. When it is not given the function will return an
-\type {pdfe} document object as with a regular file, otherwise it will return a
-filename that can be used elsewhere (e.g.\ in the image library) to reference the
-stream as pseudo file.
-
-Instead of a light userdata stream (which is actually fragile but handy when you
-come from a library) you can also pass a \LUA\ string, in which case the given
-length is (at most) the string length.
-
-The function returns an \type {pdfe} object and a string. The string can be used in
-the \type {img} library instead of a filename. You need to prevent garbage
-collection of the object when you use it as image (for instance by storing it
-somewhere).
-
-Both the memory stream and it's use in the image library is experimental and can
-change. In case you wonder where this can be used: when you use the swiglib
-library for \type {graphicmagick}, it can return such a userdata object. This
-permits conversion in memory and passing the result directly to the backend. This
-might save some runtime in one|-|pass workflows. This feature is currently not
-meant for production and we might come up with a better implementation.
-
-\stopsection
-
-\startsection[title={The \type {pdfscanner} library}][library=pdfscanner]
-
-\topicindex{\PDF+scanner}
-
-\libindex {scan}
-
-The \type {pdfscanner} library allows interpretation of \PDF\ content streams and
-\type {/ToUnicode} (cmap) streams. You can get those streams from the \type
-{pdfe} library, as explained in an earlier section. There is only a single
-top|-|level function in this library:
-
-\startfunctioncall
-pdfscanner.scan (<pdfe stream>, <table> operatortable, <table> info)
-pdfscanner.scan (<pdfe array>, <table> operatortable, <table> info)
-pdfscanner.scan (<string>, <table> operatortable, <table> info)
-\stopfunctioncall
-
-The first argument should be a \LUA\ string or a stream or array onject coming
-from the \type {pdfe} library. The second argument, \type {operatortable}, should
-be a \LUA\ table where the keys are \PDF\ operator name strings and the values
-are \LUA\ functions (defined by you) that are used to process those operators.
-The functions are called whenever the scanner finds one of these \PDF\ operators
-in the content stream(s). The functions are called with two arguments: the \type
-{scanner} object itself, and the \type {info} table that was passed are the third
-argument to \type {pdfscanner.scan}.
-
-Internally, \type {pdfscanner.scan} loops over the \PDF\ operators in the
-stream(s), collecting operands on an internal stack until it finds a \PDF\
-operator. If that \PDF\ operator's name exists in \type {operatortable}, then the
-associated function is executed. After the function has run (or when there is no
-function to execute) the internal operand stack is cleared in preparation for the
-next operator, and processing continues.
-
-The \type {scanner} argument to the processing functions is needed because it
-offers various methods to get the actual operands from the internal operand
-stack.
-
-A simple example of processing a \PDF's document stream could look like this:
-
-\starttyping
-local operatortable = { }
-
-operatortable.Do = function(scanner,info)
- local resources = info.resources
- if resources then
- local val = scanner:pop()
- local name = val[2]
- local xobject = resources.XObject
- print(info.space .. "Uses XObject " .. name)
- local resources = xobject.Resources
- if resources then
- local newinfo = {
- space = info.space .. " ",
- resources = resources,
- }
- pdfscanner.scan(entry, operatortable, newinfo)
- end
- end
-end
-
-local function Analyze(filename)
- local doc = pdfe.open(filename)
- if doc then
- local pages = doc.Pages
- for i=1,#pages do
- local page = pages[i]
- local info = {
- space = " " ,
- resources = page.Resources,
- }
- print("Page " .. i)
- -- pdfscanner.scan(page.Contents,operatortable,info)
- pdfscanner.scan(page.Contents(),operatortable,info)
- end
- end
-end
-
-Analyze("foo.pdf")
-\stoptyping
-
-This example iterates over all the actual content in the \PDF, and prints out the
-found \type {XObject} names. While the code demonstrates quite some of the \type
-{pdfe} functions, let's focus on the type \type {pdfscanner} specific code
-instead.
-
-From the bottom up, the following line runs the scanner with the \PDF\ page's
-top|-|level content given in the first argument.
-
-The third argument, \type {info}, contains two entries: \type {space} is used to
-indent the printed output, and \type {resources} is needed so that embedded \type
-{XForms} can find their own content.
-
-The second argument, \type {operatortable} defines a processing function for a
-single \PDF\ operator, \type {Do}.
-
-The function \type {Do} prints the name of the current \type {XObject}, and then
-starts a new scanner for that object's content stream, under the condition that
-the \type {XObject} is in fact a \type {/Form}. That nested scanner is called
-with new \type {info} argument with an updated \type {space} value so that the
-indentation of the output nicely nests, and with a new \type {resources} field
-to help the next iteration down to properly process any other, embedded \type
-{XObject}s.
-
-Of course, this is not a very useful example in practice, but for the purpose of
-demonstrating \type {pdfscanner}, it is just long enough. It makes use of only
-one \type {scanner} method: \type {scanner:pop()}. That function pops the top
-operand of the internal stack, and returns a \LUA\ table where the object at index
-one is a string representing the type of the operand, and object two is its
-value.
-
-The list of possible operand types and associated \LUA\ value types is:
-
-\starttabulate[|l|l|]
-\DB types \BC type \NC \NR
-\TB
-\NC \type{integer} \NC <number> \NC \NR
-\NC \type{real} \NC <number> \NC \NR
-\NC \type{boolean} \NC <boolean> \NC \NR
-\NC \type{name} \NC <string> \NC \NR
-\NC \type{operator} \NC <string> \NC \NR
-\NC \type{string} \NC <string> \NC \NR
-\NC \type{array} \NC <table> \NC \NR
-\NC \type{dict} \NC <table> \NC \NR
-\LL
-\stoptabulate
-
-In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating
-point) number. In case of \type {name}, the leading slash is always stripped.
-
-In case of \type {string}, please bear in mind that \PDF\ actually supports
-different types of strings (with different encodings) in different parts of the
-\PDF\ document, so you may need to reencode some of the results; \type {pdfscanner}
-always outputs the byte stream without reencoding anything. \type {pdfscanner}
-does not differentiate between literal strings and hexadecimal strings (the
-hexadecimal values are decoded), and it treats the stream data for inline images
-as a string that is the single operand for \type {EI}.
-
-In case of \type {array}, the table content is a list of \type {pop} return
-values and in case of \type {dict}, the table keys are \PDF\ name strings and the
-values are \type {pop} return values.
-
-\libindex{pop}
-\libindex{popnumber}
-\libindex{popname}
-\libindex{popstring}
-\libindex{poparray}
-\libindex{popdictionary}
-\libindex{popboolean}
-\libindex{done}
-
-There are a few more methods defined that you can ask \type {scanner}:
-
-\starttabulate[|l|p|]
-\DB method \BC explanation \NC \NR
-\TB
-\NC \type{pop} \NC see above \NC \NR
-\NC \type{popnumber} \NC return only the value of a \type {real} or \type {integer} \NC \NR
-\NC \type{popname} \NC return only the value of a \type {name} \NC \NR
-\NC \type{popstring} \NC return only the value of a \type {string} \NC \NR
-\NC \type{poparray} \NC return only the value of a \type {array} \NC \NR
-\NC \type{popdictionary} \NC return only the value of a \type {dict} \NC \NR
-\NC \type{popboolean} \NC return only the value of a \type {boolean} \NC \NR
-\NC \type{done} \NC abort further processing of this \type {scan()} call \NC \NR
-\LL
-\stoptabulate
-
-The \type {pop*} are convenience functions, and come in handy when you know the
-type of the operands beforehand (which you usually do, in \PDF). For example, the
-\type {Do} function could have used \type {local name = scanner:popname()}
-instead, because the single operand to the \type {Do} operator is always a \PDF\
-name object.
-
-The \type {done} function allows you to abort processing of a stream once you
-have learned everything you want to learn. This comes in handy while parsing
-\type {/ToUnicode}, because there usually is trailing garbage that you are not
-interested in. Without \type {done}, processing only ends at the end of the
-stream, possibly wasting \CPU\ cycles.
-
-{\em We keep the older names \type {popNumber}, \type {popName}, \type
-{popString}, \type {popArray}, \type {popDict} and \type {popBool} around.}
-
-\stopsection
-
-\stopchapter
-
-\stopcomponent
+% language=uk
+
+\environment luatex-style
+
+\startcomponent luatex-backend
+
+\startchapter[reference=backend,title={The backend libraries}]
+
+\startsection[title={The \type {pdf} library}][library=pdf]
+
+\topicindex{backend}
+\topicindex{\PDF}
+
+This library contains variables and functions that are related to the \PDF\
+backend. You can find more details about the expected values to setters in \in
+{section} [backendprimitives].
+
+\startsubsection[title={\type {mapfile}, \type {mapline}}]
+
+\topicindex{map files}
+\topicindex{files+map}
+
+\startfunctioncall
+pdf.mapfile(<string> map file)
+pdf.mapline(<string> map line)
+\stopfunctioncall
+
+These two functions can be used to replace primitives \orm {pdfmapfile} and
+\orm {pdfmapline} inherited from \PDFTEX. They expect a string as only
+parameter and have no return value. The first character in a map line can be
+\type {-}, \type {+} or \type {=} which means as much as remove, add or replace
+this line. They are not state setters but act immediately.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][catalog|info|names|trailer]}}]
+
+\topicindex{\PDF+trailer}
+\topicindex{\PDF+catalog}
+\topicindex{\PDF+info}
+
+\libindex{setcatalog} \libindex{getcatalog}
+\libindex{setinfo} \libindex{getinfo}
+\libindex{setnames} \libindex{getnames}
+\libindex{settrailer} \libindex{gettrailer}
+
+These functions complement the corresponding \PDF\ backend token lists dealing
+with metadata. The value types are strings and they are written to the \PDF\
+file directly after the token registers set at the \TEX\ end are written.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][pageattributes|pageresources|pagesattributes]}}]
+
+\libindex{setpageattributes} \libindex{getpageattributes}
+\libindex{setpageresources} \libindex{getpageresources}
+\libindex{setpagesattributes} \libindex{getpagesattributes}
+
+\topicindex{\PDF+page attributes}
+\topicindex{\PDF+page resources}
+
+These functions complement the corresponding \PDF\ backend token lists dealing
+with page resources. The variables have no interaction with the corresponding \PDF\
+backend token register. They are written to the \PDF\ file directly after the
+token registers set at the \TEX\ end are written.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][xformattributes|xformresources]}}]
+
+\libindex{setxformattributes} \libindex{getxformattributes}
+\libindex{setxformresources} \libindex{getxformresources}
+
+\topicindex{\PDF+xform attributes}
+\topicindex{\PDF+xform resources}
+
+These functions complement the corresponding \PDF\ backend token lists dealing
+with reuseable boxes and images. The variables have no interaction with the
+corresponding \PDF\ backend token register. They are written to the \PDF\
+file directly after the token registers set at the \TEX\ end are written.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][major|minor]version}}]
+
+\topicindex{\PDF+version}
+
+\libindex{getmajorversion} \libindex{setmajorversion}
+\libindex{getminorversion} \libindex{setminorversion}
+
+You can set both the major and minor version of the output. The major version is
+normally~1 but when set to~2 some data will not be written to the file in order
+to comply with the standard. What minor version you set depends on what \PDF\
+features you use. This is out of control of \LUATEX.
+
+\stopsubsection
+
+\startsubsection[title={\type {getcreationdate}}]
+
+\topicindex{\PDF+date}
+
+\libindex{getcreationdate}
+
+This function returns a string with the date in the format that ends up in the
+\PDF\ file, in this case it's: {\tttf \cldcontext{pdf.getcreationdate()}}.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]inclusionerrorlevel} and \type {[set|get]ignoreunknownimages}}]
+
+\topicindex{\PDF+options}
+
+\libindex{getinclusionerrorlevel} \libindex{setinclusionerrorlevel}
+\libindex{getignoreunknownimages} \libindex{setignoreunknownimages}
+
+These variable control how error in included image are treated. They are modeled
+after the \PDFTEX\ equivalents.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]suppressoptionalinfo}, \type {[set|get]trailerid}
+and \type {[set|get]omitcidset}}]
+
+\topicindex{\PDF+options}
+\topicindex{\PDF+trailer}
+
+\libindex{getsuppressoptionalinfo} \libindex{setsuppressoptionalinfo}
+\libindex{gettrailerid} \libindex{settrailerid}
+\libindex{getomitcidset} \libindex{setomitcidset}
+\libindex{getomitcharset} \libindex{setomitcharset}
+
+The optional info bitset (a number) determines what kind of info gets flushed.
+By default we flush all. See \in {section} [sec:pdfextensions] for more details.
+
+You can set your own trailer id. This has to be string containing valid \PDF\
+array content with checksums.
+
+The cidset and charset flags (numbers) disables inclusion of a so called \type
+{CIDSet} and \type {CharSet} entries, which can be handy when aiming at some of
+the many \PDF\ substandards.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][obj|]compresslevel} and \type {[set|get]recompress}}]
+
+\topicindex{\PDF+compression}
+
+\libindex{getcompresslevel} \libindex{setcompresslevel}
+\libindex{getobjcompresslevel} \libindex{setobjcompresslevel}
+\libindex{getrecompress} \libindex{setrecompress}
+
+These functions set the level stream compression. When object compression is
+enabled multiple objects will be packed in a compressed stream which saves space.
+The minimum values are~0, the maxima are~9.
+
+When recompression is to~1 compressed objects will be decompressed and when
+compresslevel is larger than zero they will then be recompressed. This is mostly
+a debugging feature and should not be relied upon.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]gentounicode}}]
+
+\topicindex{\PDF+unicode}
+
+\libindex{getgentounicode} \libindex{setgentounicode}
+
+This flag enables tounicode generation (like in \PDFTEX). Normally the values are
+provided by the font loader.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]decimaldigits}}]
+
+\topicindex{\PDF+precision}
+
+\libindex{getdecimaldigits} \libindex{setdecimaldigits}
+
+These two functions set the accuracy of floats written to the \PDF file. You can
+set any value but the backend will not go below~3 and above~6.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]pkresolution}}]
+
+\topicindex{\PDF+resolution}
+
+\libindex{getpkresolution} \libindex{setpkresolution}
+
+These setter takes two arguments: the resolution and an optional zero or one that
+indicates if this is a fixed one. The getter returns these two values.
+
+\stopsubsection
+
+\startsubsection[title={\type {getlast[obj|link|annot]} and \type {getretval}}]
+
+\topicindex{\PDF+objects}
+\topicindex{\PDF+annotations}
+
+\libindex{getlastobj} \libindex{setlastobj}
+\libindex{getlastlink} \libindex{setlastlink}
+\libindex{getlastannot} \libindex{setlastannot}
+\libindex{getretval}
+
+These status variables are similar to the ones traditionally used in the backend
+interface at the \TEX\ end.
+
+\stopsubsection
+
+\startsubsection[title={\type {getmaxobjnum} and \type {getobjtype}, \type {getfontname},
+\type {getfontobjnum}, \type {getfontsize}, \type {getxformname}}]
+
+\libindex{getmaxobjnum}
+\libindex{getobjtype}
+\libindex{getfontname}
+\libindex{getfontobjnum}
+\libindex{getfontsize}
+\libindex{getxformname}
+
+These introspective helpers are mostly used when you construct \PDF\ objects
+yourself and need for instance information about a (to be) embedded font.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]origin}}]
+
+\topicindex{\PDF+positioning}
+
+\libindex{setorigin} \libindex{getorigin}
+
+This one is used to set the horizonal and|/|or vertical offset, a traditional
+backend property.
+
+\starttyping
+pdf.setorigin() -- sets both to 0pt
+pdf.setorigin(tex.sp("1in")) -- sets both to 1in
+pdf.setorigin(tex.sp("1in"),tex.sp("1in"))
+\stoptyping
+
+The counterpart of this function returns two values.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get]imageresolution}}]
+
+\topicindex{\PDF+resolution}
+
+\libindex{setimageresolution} \libindex{getimageresolution}
+
+These two functions relate to the imageresolution that is used when the image
+itself doesn't provide a non|-|zero x or y resolution.
+
+\stopsubsection
+
+\startsubsection[title={\type {[set|get][link|dest|thread|xform]margin}}]
+
+\topicindex{\PDF+margins}
+
+\libindex{getlinkmargin} \libindex{setlinkmargin}
+\libindex{getdestmargin} \libindex{setdestmargin}
+\libindex{getthreadmargin} \libindex{setthreadmargin}
+\libindex{getxformmargin} \libindex{setxformmargin}
+\libindex{getmarginmargin} \libindex{setmarginmargin}
+
+These functions can be used to set and retrieve the margins that are added to the
+natural bounding boxes of the respective objects.
+
+\stopsubsection
+
+\startsubsection[title={\type {get[pos|hpos|vpos]}}]
+
+\topicindex{\PDF+positions}
+
+\libindex{getpos}
+\libindex{gethpos}
+\libindex{getvpos}
+
+These functions get current location on the output page, measured from its lower
+left corner. The values return scaled points as units.
+
+\starttyping
+local h, v = pdf.getpos()
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {[has|get]matrix}}]
+
+\topicindex{\PDF+matrix}
+
+\libindex{getmatrix} \libindex{hasmatrix}
+
+The current matrix transformation is available via the \type {getmatrix} command,
+which returns 6 values: \type {sx}, \type {rx}, \type {ry}, \type {sy}, \type
+{tx}, and \type {ty}. The \type {hasmatrix} function returns \type {true} when a
+matrix is applied.
+
+\starttyping
+if pdf.hasmatrix() then
+ local sx, rx, ry, sy, tx, ty = pdf.getmatrix()
+ -- do something useful or not
+end
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {print}}]
+
+\topicindex{\PDF+print to}
+
+\libindex{print}
+
+You can print a string to the \PDF\ document from within a \lpr {latelua} call.
+This function is not to be used inside \prm {directlua} unless you know {\it
+exactly} what you are doing.
+
+\startfunctioncall
+pdf.print(<string> s)
+pdf.print(<string> type, <string> s)
+\stopfunctioncall
+
+The optional parameter can be used to mimic the behavior of \PDF\ literals: the
+\type {type} is \type {direct} or \type {page}.
+
+\stopsubsection
+
+\startsubsection[title={\type {immediateobj}}]
+
+\topicindex{\PDF+objects}
+
+\libindex{immediateobj}
+
+This function creates a \PDF\ object and immediately writes it to the \PDF\ file.
+It is modelled after \PDFTEX's \prm {immediate} \orm {pdfobj} primitives. All
+function variants return the object number of the newly generated object.
+
+\startfunctioncall
+<number> n =
+ pdf.immediateobj(<string> objtext)
+<number> n =
+ pdf.immediateobj("file", <string> filename)
+<number> n =
+ pdf.immediateobj("stream", <string> streamtext, <string> attrtext)
+<number> n =
+ pdf.immediateobj("streamfile", <string> filename, <string> attrtext)
+\stopfunctioncall
+
+The first version puts the \type {objtext} raw into an object. Only the object
+wrapper is automatically generated, but any internal structure (like \type {<<
+>>} dictionary markers) needs to be provided by the user. The second version with
+keyword \type {file} as first argument puts the contents of the file with name
+\type {filename} raw into the object. The third version with keyword \type
+{stream} creates a stream object and puts the \type {streamtext} raw into the
+stream. The stream length is automatically calculated. The optional \type
+{attrtext} goes into the dictionary of that object. The fourth version with
+keyword \type {streamfile} does the same as the third one, it just reads the
+stream data raw from a file.
+
+An optional first argument can be given to make the function use a previously
+reserved \PDF\ object.
+
+\startfunctioncall
+<number> n =
+ pdf.immediateobj(<integer> n, <string> objtext)
+<number> n =
+ pdf.immediateobj(<integer> n, "file", <string> filename)
+<number> n =
+ pdf.immediateobj(<integer> n, "stream", <string> streamtext, <string> attrtext)
+<number> n =
+ pdf.immediateobj(<integer> n, "streamfile", <string> filename, <string> attrtext)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type{obj}}]
+
+\topicindex{\PDF+objects}
+
+\libindex{obj}
+
+This function creates a \PDF\ object, which is written to the \PDF\ file only
+when referenced, e.g., by \type {refobj()}.
+
+All function variants return the object number of the newly generated object, and
+there are two separate calling modes. The first mode is modelled after \PDFTEX's
+\orm {pdfobj} primitive.
+
+\startfunctioncall
+<number> n =
+ pdf.obj(<string> objtext)
+<number> n =
+ pdf.obj("file", <string> filename)
+<number> n =
+ pdf.obj("stream", <string> streamtext, <string> attrtext)
+<number> n =
+ pdf.obj("streamfile", <string> filename, <string> attrtext)
+\stopfunctioncall
+
+An optional first argument can be given to make the function use a previously
+reserved \PDF\ object.
+
+\startfunctioncall
+<number> n =
+ pdf.obj(<integer> n, <string> objtext)
+<number> n =
+ pdf.obj(<integer> n, "file", <string> filename)
+<number> n =
+ pdf.obj(<integer> n, "stream", <string> streamtext, <string> attrtext)
+<number> n =
+ pdf.obj(<integer> n, "streamfile", <string> filename, <string> attrtext)
+\stopfunctioncall
+
+The second mode accepts a single argument table with key--value pairs.
+
+\startfunctioncall
+<number> n = pdf.obj {
+ type = <string>,
+ immediate = <boolean>,
+ objnum = <number>,
+ attr = <string>,
+ compresslevel = <number>,
+ objcompression = <boolean>,
+ file = <string>,
+ string = <string>,
+ nolength = <boolean>,
+}
+\stopfunctioncall
+
+The \type {type} field can have the values \type {raw} and \type {stream}, this
+field is required, the others are optional (within constraints). When \type
+{nolength} is set, there will be no \type {/Length} entry added to the
+dictionary.
+
+Note: this mode makes \type{obj} look more flexible than it actually is: the
+constraints from the separate parameter version still apply, so for example you
+can't have both \type {string} and \type {file} at the same time.
+
+\stopsubsection
+
+\startsubsection[title={\type {refobj}}]
+
+\topicindex{\PDF+objects}
+
+\libindex{refobj}
+
+This function, the \LUA\ version of the \orm {pdfrefobj} primitive, references an
+object by its object number, so that the object will be written to the \PDF\ file.
+
+\startfunctioncall
+pdf.refobj(<integer> n)
+\stopfunctioncall
+
+This function works in both the \prm {directlua} and \lpr {latelua} environment.
+Inside \prm {directlua} a new whatsit node \quote {pdf_refobj} is created, which
+will be marked for flushing during page output and the object is then written
+directly after the page, when also the resources objects are written to the \PDF\
+file. Inside \lpr {latelua} the object will be marked for flushing.
+
+This function has no return values.
+
+\stopsubsection
+
+\startsubsection[title={\type {reserveobj}}]
+
+\topicindex{\PDF+objects}
+
+\libindex{reserveobj}
+
+This function creates an empty \PDF\ object and returns its number.
+
+\startfunctioncall
+<number> n = pdf.reserveobj()
+<number> n = pdf.reserveobj("annot")
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {getpageref}}]
+
+\topicindex{\PDF+pages}
+
+\libindex{getpageref}
+
+The object number of a page can be fetched with this function. This can be a
+forward reference so when you ask for a future page, you do get a number back.
+
+\startfunctioncall
+<number> n = pdf.getpageref(123)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {registerannot}}]
+
+\topicindex{\PDF+annotations}
+
+\libindex{registerannot}
+
+This function adds an object number to the \type {/Annots} array for the current
+page without doing anything else. This function can only be used from within
+\lpr {latelua}.
+
+\startfunctioncall
+pdf.registerannot (<number> objnum)
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {newcolorstack}}]
+
+\topicindex{\PDF+color stack}
+
+\libindex{newcolorstack}
+
+This function allocates a new color stack and returns it's id. The arguments
+are the same as for the similar backend extension primitive.
+
+\startfunctioncall
+pdf.newcolorstack("0 g","page",true) -- page|direct|origin
+\stopfunctioncall
+
+\stopsubsection
+
+\startsubsection[title={\type {setfontattributes}}]
+
+\topicindex{\PDF+fonts}
+
+\libindex{setfontattributes}
+
+This function will force some additional code into the font resource. It can for
+instance be used to add a custom \type {ToUnicode} vector to a bitmap file.
+
+\startfunctioncall
+pdf.setfontattributes(<number> font id, <string> pdf code)
+\stopfunctioncall
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={The \type {pdfe} library}][library=pdfe]
+
+\startsubsection[title={Introduction}]
+
+\topicindex{\PDF+objects}
+
+\topicindex{\PDF+analyze}
+\topicindex{\PDF+\type{pdfe}}
+
+The \type {pdfe} library replaces the \type {epdf} library and provides an
+interface to \PDF\ files. It uses the same code as is used for \PDF\ image
+inclusion. The \type {pplib} library by Paweł Jackowski replaces the \type
+{poppler} (derived from \type {xpdf}) library.
+
+A \PDF\ file is basically a tree of objects and one descends into the tree via
+dictionaries (key/value) and arrays (index/value). There are a few topmost
+dictionaries that start at root that are accessed more directly.
+
+Although everything in \PDF\ is basically an object we only wrap a few in so
+called userdata \LUA\ objects.
+
+\starttabulate
+\BC \PDF \BC \LUA \NC \NR
+\NC null \NC nil \NC \NR
+\NC boolean \NC boolean \NC \NR
+\NC integer \NC integer \NC \NR
+\NC float \NC number \NC \NR
+\NC name \NC string \NC \NR
+\NC string \NC string \NC \NR
+\NC array \NC array userdatum \NC \NR
+\NC dictionary \NC dictionary userdatum \NC \NR
+\NC stream \NC stream userdatum (with related dictionary) \NC \NR
+\NC reference \NC reference userdatum \NC \NR
+\stoptabulate
+
+The regular getters return these \LUA\ data types but one can also get more
+detailed information.
+
+\stopsubsection
+
+\startsubsection[title={\type {open}, \type {new}, \type {getstatus}, \type {close}, \type {unencrypt}}]
+
+\libindex {open}
+\libindex {new}
+\libindex {new}
+\libindex {getstatus}
+\libindex {close}
+\libindex {unencrypt}
+
+A document is loaded from a file or string
+
+\starttyping
+<pdfe document> = pdfe.open(filename)
+<pdfe document> = pdfe.new(somestring,somelength)
+\stoptyping
+
+Such a document is closed with:
+
+\starttyping
+pdfe.close(<pdfe document>)
+\stoptyping
+
+You can check if a document opened well by:
+
+\starttyping
+pdfe.getstatus(<pdfe document>)
+\stoptyping
+
+The returned codes are:
+
+\starttabulate[|c|l|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type {-2} \NC the document failed to open \NC \NR
+\NC \type {-1} \NC the document is (still) protected \NC \NR
+\NC \type {0} \NC the document is not encrypted \NC \NR
+\NC \type {2} \NC the document has been unencrypted \NC \NR
+\LL
+\stoptabulate
+
+An encrypted document can be unencrypted by the next command where instead of
+either password you can give \type {nil}:
+
+\starttyping
+pdfe.unencrypt(<pdfe document>,userpassword,ownerpassword)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getsize}, \type {getversion}, \type {getnofobjects}, \type {getnofpages}}]
+
+\libindex {getsize}
+\libindex {getversion}
+\libindex {getnofobjects}
+\libindex {getnofpages}
+
+A successfully opened document can provide some information:
+
+\starttyping
+bytes = getsize(<pdfe document>)
+major, minor = getversion(<pdfe document>)
+n = getnofobjects(<pdfe document>)
+n = getnofpages(<pdfe document>)
+bytes, waste = getnofpages(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[catalog|trailer|info]}}]
+
+\libindex {getcatalog}
+\libindex {gettrailer}
+\libindex {getinfo}
+
+For accessing the document structure you start with the so called catalog, a
+dictionary:
+
+\starttyping
+<pdfe dictionary> = pdfe.getcatalog(<pdfe document>)
+\stoptyping
+
+The other two root dictionaries are accessed with:
+
+\starttyping
+<pdfe dictionary> = pdfe.gettrailer(<pdfe document>)
+<pdfe dictionary> = pdfe.getinfo(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getpage}, \type {getbox}}]
+
+\libindex {getpage}
+\libindex {getbox}
+
+A specific page can conveniently be reached with the next command, which
+returns a dictionary. The first argument is to be a page dictionary.
+
+\starttyping
+<pdfe dictionary> = pdfe.getpage(<pdfe dictionary>,pagenumber)
+\stoptyping
+
+Another convenience command gives you the (bounding) box of a (normally page)
+which can be inheritted from the document itself. An example of a valid box name
+is \type {MediaBox}.
+
+\starttyping
+pages = pdfe.getbox(<pdfe document>,boxname)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[string|integer|number|boolean|name]}}]
+
+\libindex {getstring}
+\libindex {getinteger}
+\libindex {getnumber}
+\libindex {getboolean}
+\libindex {getname}
+
+Common values in dictionaries and arrays are strings, integers, floats, booleans
+and names (which are also strings) and these are also normal \LUA\ objects:
+
+\starttyping
+s = getstring (<pdfe array|dictionary>,index|key)
+i = getinteger(<pdfe array|dictionary>,index|key)
+n = getnumber (<pdfe array|dictionary>,index|key)
+b = getboolean(<pdfe array|dictionary>,index|key)
+n = getname (<pdfe array|dictionary>,index|key)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {get[from][dictionary|array|stream]}}]
+
+\libindex {getdictionary} \libindex {getfromdictionary}
+\libindex {getarray} \libindex {getfromarray}
+\libindex {getstream} \libindex {getfromstream}
+
+Normally you will use an index in an array and key in a dictionary but dictionaries
+also accept an index. The size of an array or dictionary is available with the
+usual \type {#} operator.
+
+\starttyping
+<pdfe dictionary> = getdictionary(<pdfe array|dictionary>,index|key)
+<pdfe array> = getarray (<pdfe array|dictionary>,index|key)
+<pdfe stream>,
+<pdfe dictionary> = getstream (<pdfe array|dictionary>,index|key)
+\stoptyping
+
+These commands return dictionaries, arrays and streams, which are dictionaries
+with a blob of data attached.
+
+Before we come to an alternative access mode, we mention that the objects provide
+access in a different way too, for instance this is valid:
+
+\starttyping
+print(pdfe.open("foo.pdf").Catalog.Type)
+\stoptyping
+
+At the topmost level there are \type {Catalog}, \type {Info}, \type {Trailer}
+and \type {Pages}, so this is also okay:
+
+\starttyping
+print(pdfe.open("foo.pdf").Pages[1])
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {[open|close|readfrom][whole|]stream}}]
+
+\libindex {openstream}
+\libindex {closestream}
+\libindex {readfromstream}
+\libindex {readfromwholestream}
+
+Streams are sort of special. When your index or key hits a stream you get back a
+stream object and dictionary object. The dictionary you can access in the usual
+way and for the stream there are the following methods:
+
+\starttyping
+okay = openstream(<pdfe stream>,[decode])
+ closestream(<pdfe stream>)
+str, n = readfromstream(<pdfe stream>)
+str, n = readwholestream(<pdfe stream>,[decode])
+\stoptyping
+
+You either read in chunks, or you ask for the whole. When reading in chunks, you
+need to open and close the stream yourself. The \type {n} value indicates the
+length read. The \type {decode} parameter controls if the stream data gets
+uncompressed.
+
+As with dictionaries, you can access fields in a stream dictionary in the usual
+\LUA\ way too. You get the content when you \quote {call} the stream. You can
+pass a boolean that indicates if the stream has to be decompressed.
+
+% pdfe.objectcodes = objectcodes
+% pdfe.stringcodes = stringcodes
+% pdfe.encryptioncodes = encryptioncodes
+
+\stopsubsection
+
+\startsubsection[title={\type {getfrom[dictionary|array]}}]
+
+\libindex {getfromdictionary}
+\libindex {getfromarray}
+
+In addition to the interface described before, there is also a bit lower level
+interface available.
+
+\starttyping
+key, type, value, detail = getfromdictionary(<pdfe dictionary>,index)
+type, value, detail = getfromarray(<pdfe array>,index)
+\stoptyping
+
+\starttabulate[|c|l|l|l|]
+\DB type \BC meaning \BC value \BC detail \NC \NR
+\NC \type {0} \NC none \NC nil \NC \NC \NR
+\NC \type {1} \NC null \NC nil \NC \NC \NR
+\NC \type {2} \NC boolean \NC boolean \NC \NC \NR
+\NC \type {3} \NC boolean \NC integer \NC \NC \NR
+\NC \type {4} \NC number \NC float \NC \NC \NR
+\NC \type {5} \NC name \NC string \NC \NC \NR
+\NC \type {6} \NC string \NC string \NC hex \NC \NR
+\NC \type {7} \NC array \NC arrayobject \NC size \NC \NR
+\NC \type {8} \NC dictionary \NC dictionaryobject \NC size \NC \NR
+\NC \type {9} \NC stream \NC streamobject \NC dictionary size \NC \NR
+\NC \type {10} \NC reference \NC integer \NC \NC \NR
+\LL
+\stoptabulate
+
+A \type {hex} string is (in the \PDF\ file) surrounded by \type {<>} while plain
+strings are bounded by \type {<>}.
+
+\stopsubsection
+
+\startsubsection[title={\type {[dictionary|array]totable}}]
+
+\libindex {dictionarytotable}
+\libindex {arraytotable}
+
+All entries in a dictionary or table can be fetched with the following commands
+where the return values are a hashed or indexed table.
+
+\starttyping
+hash = dictionarytotable(<pdfe dictionary>)
+list = arraytotable(<pdfe array>)
+\stoptyping
+
+You can get a list of pages with:
+
+\starttyping
+{ { <pdfe dictionary>, size, objnum }, ... } = pagestotable(<pdfe document>)
+\stoptyping
+
+\stopsubsection
+
+\startsubsection[title={\type {getfromreference}}]
+
+\libindex {getfromreference}
+
+Because you can have unresolved references, a reference object can be resolved
+with:
+
+\starttyping
+<pdfe dictionary|array|stream> = getfromreference(<pdfe reference>)
+\stoptyping
+
+So, you get back a new \type {pdfe} userdata object that you can query.
+
+\stopsubsection
+
+\stopsection
+
+\startsection[title={Memory streams}][library=pdfe]
+
+\topicindex{\PDF+memory streams}
+
+\libindex {new}
+
+The \type {pdfe.new} that takes three arguments:
+
+\starttabulate
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type {stream} \NC this is a (in low level \LUA\ speak) light userdata
+ object, i.e.\ a pointer to a sequence of bytes \NC \NR
+\NC \type {length} \NC this is the length of the stream in bytes (the stream can
+ have embedded zeros) \NC \NR
+\NC \type {name} \NC optional, this is a unique identifier that is used for
+ hashing the stream, so that multiple doesn't use more
+ memory \NC \NR
+\LL
+\stoptabulate
+
+The third argument is optional. When it is not given the function will return an
+\type {pdfe} document object as with a regular file, otherwise it will return a
+filename that can be used elsewhere (e.g.\ in the image library) to reference the
+stream as pseudo file.
+
+Instead of a light userdata stream (which is actually fragile but handy when you
+come from a library) you can also pass a \LUA\ string, in which case the given
+length is (at most) the string length.
+
+The function returns an \type {pdfe} object and a string. The string can be used in
+the \type {img} library instead of a filename. You need to prevent garbage
+collection of the object when you use it as image (for instance by storing it
+somewhere).
+
+Both the memory stream and it's use in the image library is experimental and can
+change. In case you wonder where this can be used: when you use the swiglib
+library for \type {graphicmagick}, it can return such a userdata object. This
+permits conversion in memory and passing the result directly to the backend. This
+might save some runtime in one|-|pass workflows. This feature is currently not
+meant for production and we might come up with a better implementation.
+
+\stopsection
+
+\startsection[title={The \type {pdfscanner} library}][library=pdfscanner]
+
+\topicindex{\PDF+scanner}
+
+\libindex {scan}
+
+The \type {pdfscanner} library allows interpretation of \PDF\ content streams and
+\type {/ToUnicode} (cmap) streams. You can get those streams from the \type
+{pdfe} library, as explained in an earlier section. There is only a single
+top|-|level function in this library:
+
+\startfunctioncall
+pdfscanner.scan (<pdfe stream>, <table> operatortable, <table> info)
+pdfscanner.scan (<pdfe array>, <table> operatortable, <table> info)
+pdfscanner.scan (<string>, <table> operatortable, <table> info)
+\stopfunctioncall
+
+The first argument should be a \LUA\ string or a stream or array onject coming
+from the \type {pdfe} library. The second argument, \type {operatortable}, should
+be a \LUA\ table where the keys are \PDF\ operator name strings and the values
+are \LUA\ functions (defined by you) that are used to process those operators.
+The functions are called whenever the scanner finds one of these \PDF\ operators
+in the content stream(s). The functions are called with two arguments: the \type
+{scanner} object itself, and the \type {info} table that was passed are the third
+argument to \type {pdfscanner.scan}.
+
+Internally, \type {pdfscanner.scan} loops over the \PDF\ operators in the
+stream(s), collecting operands on an internal stack until it finds a \PDF\
+operator. If that \PDF\ operator's name exists in \type {operatortable}, then the
+associated function is executed. After the function has run (or when there is no
+function to execute) the internal operand stack is cleared in preparation for the
+next operator, and processing continues.
+
+The \type {scanner} argument to the processing functions is needed because it
+offers various methods to get the actual operands from the internal operand
+stack.
+
+A simple example of processing a \PDF's document stream could look like this:
+
+\starttyping
+local operatortable = { }
+
+operatortable.Do = function(scanner,info)
+ local resources = info.resources
+ if resources then
+ local val = scanner:pop()
+ local name = val[2]
+ local xobject = resources.XObject
+ print(info.space .. "Uses XObject " .. name)
+ local resources = xobject.Resources
+ if resources then
+ local newinfo = {
+ space = info.space .. " ",
+ resources = resources,
+ }
+ pdfscanner.scan(entry, operatortable, newinfo)
+ end
+ end
+end
+
+local function Analyze(filename)
+ local doc = pdfe.open(filename)
+ if doc then
+ local pages = doc.Pages
+ for i=1,#pages do
+ local page = pages[i]
+ local info = {
+ space = " " ,
+ resources = page.Resources,
+ }
+ print("Page " .. i)
+ -- pdfscanner.scan(page.Contents,operatortable,info)
+ pdfscanner.scan(page.Contents(),operatortable,info)
+ end
+ end
+end
+
+Analyze("foo.pdf")
+\stoptyping
+
+This example iterates over all the actual content in the \PDF, and prints out the
+found \type {XObject} names. While the code demonstrates quite some of the \type
+{pdfe} functions, let's focus on the type \type {pdfscanner} specific code
+instead.
+
+From the bottom up, the following line runs the scanner with the \PDF\ page's
+top|-|level content given in the first argument.
+
+The third argument, \type {info}, contains two entries: \type {space} is used to
+indent the printed output, and \type {resources} is needed so that embedded \type
+{XForms} can find their own content.
+
+The second argument, \type {operatortable} defines a processing function for a
+single \PDF\ operator, \type {Do}.
+
+The function \type {Do} prints the name of the current \type {XObject}, and then
+starts a new scanner for that object's content stream, under the condition that
+the \type {XObject} is in fact a \type {/Form}. That nested scanner is called
+with new \type {info} argument with an updated \type {space} value so that the
+indentation of the output nicely nests, and with a new \type {resources} field
+to help the next iteration down to properly process any other, embedded \type
+{XObject}s.
+
+Of course, this is not a very useful example in practice, but for the purpose of
+demonstrating \type {pdfscanner}, it is just long enough. It makes use of only
+one \type {scanner} method: \type {scanner:pop()}. That function pops the top
+operand of the internal stack, and returns a \LUA\ table where the object at index
+one is a string representing the type of the operand, and object two is its
+value.
+
+The list of possible operand types and associated \LUA\ value types is:
+
+\starttabulate[|l|l|]
+\DB types \BC type \NC \NR
+\TB
+\NC \type{integer} \NC <number> \NC \NR
+\NC \type{real} \NC <number> \NC \NR
+\NC \type{boolean} \NC <boolean> \NC \NR
+\NC \type{name} \NC <string> \NC \NR
+\NC \type{operator} \NC <string> \NC \NR
+\NC \type{string} \NC <string> \NC \NR
+\NC \type{array} \NC <table> \NC \NR
+\NC \type{dict} \NC <table> \NC \NR
+\LL
+\stoptabulate
+
+In case of \type {integer} or \type {real}, the value is always a \LUA\ (floating
+point) number. In case of \type {name}, the leading slash is always stripped.
+
+In case of \type {string}, please bear in mind that \PDF\ actually supports
+different types of strings (with different encodings) in different parts of the
+\PDF\ document, so you may need to reencode some of the results; \type {pdfscanner}
+always outputs the byte stream without reencoding anything. \type {pdfscanner}
+does not differentiate between literal strings and hexadecimal strings (the
+hexadecimal values are decoded), and it treats the stream data for inline images
+as a string that is the single operand for \type {EI}.
+
+In case of \type {array}, the table content is a list of \type {pop} return
+values and in case of \type {dict}, the table keys are \PDF\ name strings and the
+values are \type {pop} return values.
+
+\libindex{pop}
+\libindex{popnumber}
+\libindex{popname}
+\libindex{popstring}
+\libindex{poparray}
+\libindex{popdictionary}
+\libindex{popboolean}
+\libindex{done}
+
+There are a few more methods defined that you can ask \type {scanner}:
+
+\starttabulate[|l|p|]
+\DB method \BC explanation \NC \NR
+\TB
+\NC \type{pop} \NC see above \NC \NR
+\NC \type{popnumber} \NC return only the value of a \type {real} or \type {integer} \NC \NR
+\NC \type{popname} \NC return only the value of a \type {name} \NC \NR
+\NC \type{popstring} \NC return only the value of a \type {string} \NC \NR
+\NC \type{poparray} \NC return only the value of a \type {array} \NC \NR
+\NC \type{popdictionary} \NC return only the value of a \type {dict} \NC \NR
+\NC \type{popboolean} \NC return only the value of a \type {boolean} \NC \NR
+\NC \type{done} \NC abort further processing of this \type {scan()} call \NC \NR
+\LL
+\stoptabulate
+
+The \type {pop*} are convenience functions, and come in handy when you know the
+type of the operands beforehand (which you usually do, in \PDF). For example, the
+\type {Do} function could have used \type {local name = scanner:popname()}
+instead, because the single operand to the \type {Do} operator is always a \PDF\
+name object.
+
+The \type {done} function allows you to abort processing of a stream once you
+have learned everything you want to learn. This comes in handy while parsing
+\type {/ToUnicode}, because there usually is trailing garbage that you are not
+interested in. Without \type {done}, processing only ends at the end of the
+stream, possibly wasting \CPU\ cycles.
+
+{\em We keep the older names \type {popNumber}, \type {popName}, \type
+{popString}, \type {popArray}, \type {popDict} and \type {popBool} around.}
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent