summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-callbacks.tex
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/luatex/luatex-callbacks.tex')
-rw-r--r--systems/doc/luatex/luatex-callbacks.tex2314
1 files changed, 1165 insertions, 1149 deletions
diff --git a/systems/doc/luatex/luatex-callbacks.tex b/systems/doc/luatex/luatex-callbacks.tex
index b2b706ea91..9be3e36354 100644
--- a/systems/doc/luatex/luatex-callbacks.tex
+++ b/systems/doc/luatex/luatex-callbacks.tex
@@ -1,1149 +1,1165 @@
-% language=uk
-
-\environment luatex-style
-
-\startcomponent luatex-callbacks
-
-\startchapter[reference=callbacks,title={\LUA\ callbacks}]
-
-\startsection[title={Registering callbacks}][library=callback]
-
-\topicindex{callbacks}
-
-\libindex{register}
-\libindex{list}
-\libindex{find}
-
-This library has functions that register, find and list callbacks. Callbacks are
-\LUA\ functions that are called in well defined places. There are two kind of
-callbacks: those that mix with existing functionality, and those that (when
-enabled) replace functionality. In mosty cases the second category is expected to
-behave similar to the built in functionality because in a next step specific
-data is expected. For instance, you can replace the hyphenation routine. The
-function gets a list that can be hyphenated (or not). The final list should be
-valid and is (normally) used for constructing a paragraph. Another function can
-replace the ligature builder and|/|or kerner. Doing something else is possible
-but in the end might not give the user the expected outcome.
-
-The first thing you need to do is registering a callback:
-
-\startfunctioncall
-id, error =
- callback.register(<string> callback_name, <function> func)
-id, error =
- callback.register(<string> callback_name, nil)
-id, error =
- callback.register(<string> callback_name, false)
-\stopfunctioncall
-
-Here the \syntax {callback_name} is a predefined callback name, see below. The
-function returns the internal \type {id} of the callback or \type {nil}, if the
-callback could not be registered. In the latter case, \type {error} contains an
-error message, otherwise it is \type {nil}.
-
-\LUATEX\ internalizes the callback function in such a way that it does not matter
-if you redefine a function accidentally.
-
-Callback assignments are always global. You can use the special value \type {nil}
-instead of a function for clearing the callback.
-
-For some minor speed gain, you can assign the boolean \type {false} to the
-non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
-whatever it would execute by default (when no callback function is registered at
-all). Be warned: this may cause all sorts of grief unless you know \notabene
-{exactly} what you are doing!
-
-\startfunctioncall
-<table> info =
- callback.list()
-\stopfunctioncall
-
-The keys in the table are the known callback names, the value is a boolean where
-\type {true} means that the callback is currently set (active).
-
-\startfunctioncall
-<function> f = callback.find(callback_name)
-\stopfunctioncall
-
-If the callback is not set, \type {find} returns \type {nil}.
-
-\stopsection
-
-\startsection[title={File discovery callbacks}][library=callback]
-
-The behaviour documented in this subsection is considered stable in the sense that
-there will not be backward|-|incompatible changes any more.
-
-\subsection{\cbk {find_read_file} and \cbk {find_write_file}}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<number> id_number, <string> asked_name)
-\stopfunctioncall
-
-Arguments:
-
-\startitemize
-
-\sym{id_number}
-
-This number is zero for the log or \prm {input} files. For \TEX's \prm {read}
-or \prm {write} the number is incremented by one, so \type {\read0} becomes~1.
-
-\sym{asked_name}
-
-This is the user|-|supplied filename, as found by \prm {input}, \prm {openin}
-or \prm {openout}.
-
-\stopitemize
-
-Return value:
-
-\startitemize
-
-\sym{actual_name}
-
-This is the filename used. For the very first file that is read in by \TEX, you
-have to make sure you return an \type {actual_name} that has an extension and
-that is suitable for use as \type {jobname}. If you don't, you will have to
-manually fix the name of the log file and output file after \LUATEX\ is finished,
-and an eventual format filename will become mangled. That is because these file
-names depend on the jobname.
-
-You have to return \type {nil} if the file cannot be found.
-
-\stopitemize
-
-\subsection{\cbk {find_font_file}}
-
-\topicindex{callbacks+font files}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<string> asked_name)
-\stopfunctioncall
-
-The \type {asked_name} is an \OTF\ or \TFM\ font metrics file.
-
-Return \type {nil} if the file cannot be found.
-
-\subsection{\cbk {find_output_file}}
-
-\topicindex{callbacks+output file}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<string> asked_name)
-\stopfunctioncall
-
-The \type {asked_name} is the \PDF\ or \DVI\ file for writing.
-
-\subsection{\cbk {find_format_file}}
-
-\topicindex{callbacks+format file}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<string> asked_name)
-\stopfunctioncall
-
-The \type {asked_name} is a format file for reading (the format file for writing
-is always opened in the current directory).
-
-\subsection{\cbk {find_vf_file}}
-
-\topicindex{callbacks+font files}
-
-Like \cbk {find_font_file}, but for virtual fonts. This applies to both \ALEPH's
-\OVF\ files and traditional Knuthian \VF\ files.
-
-\subsection{\cbk {find_map_file}}
-
-\topicindex{callbacks+font files}
-
-Like \cbk {find_font_file}, but for map files.
-
-\subsection{\cbk {find_enc_file}}
-
-\topicindex{callbacks+font files}
-
-Like \cbk {find_font_file}, but for enc files.
-
-\subsection{\cbk {find_pk_file}}
-
-\topicindex{callbacks+font files}
-
-Like \cbk {find_font_file}, but for pk bitmap files. This callback takes two
-arguments: \type {name} and \type {dpi}. In your callback you can decide to
-look for:
-
-\starttyping
-<base res>dpi/<fontname>.<actual res>pk
-\stoptyping
-
-but other strategies are possible. It is up to you to find a \quote {reasonable}
-bitmap file to go with that specification.
-
-\subsection{\cbk {find_data_file}}
-
-\topicindex{callbacks+data files}
-
-Like \cbk {find_font_file}, but for embedded files (\type {\pdfobj file '...'}).
-
-\subsection{\cbk {find_opentype_file}}
-
-\topicindex{callbacks+font files}
-
-Like \cbk {find_font_file}, but for \OPENTYPE\ font files.
-
-\subsection{\cbk {find_truetype_file} and \cbk {find_type1_file}}
-
-\topicindex{callbacks+font files}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<string> asked_name)
-\stopfunctioncall
-
-The \type {asked_name} is a font file. This callback is called while \LUATEX\ is
-building its internal list of needed font files, so the actual timing may
-surprise you. Your return value is later fed back into the matching \type
-{read_file} callback.
-
-Strangely enough, \cbk {find_type1_file} is also used for \OPENTYPE\ (\OTF)
-fonts.
-
-\subsection{\cbk {find_image_file}}
-
-\topicindex{callbacks+image files}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<string> actual_name =
- function (<string> asked_name)
-\stopfunctioncall
-
-The \type {asked_name} is an image file. Your return value is used to open a file
-from the hard disk, so make sure you return something that is considered the name
-of a valid file by your operating system.
-
-\subsection[iocallback]{File reading callbacks}
-
-The behavior documented in this subsection is considered stable in the sense that
-there will not be backward-incompatible changes any more.
-
-\subsection{\cbk {open_read_file}}
-
-\topicindex{callbacks+opening files}
-
-Your callback function should have the following conventions:
-
-\startfunctioncall
-<table> env =
- function (<string> file_name)
-\stopfunctioncall
-
-Argument:
-
-\startitemize
-
-\sym{file_name}
-
-The filename returned by a previous \cbk {find_read_file} or the return value of
-\type {kpse.find_file()} if there was no such callback defined.
-
-\stopitemize
-
-Return value:
-
-\startitemize
-
-\sym{env}
-
-This is a table containing at least one required and one optional callback
-function for this file. The required field is \type {reader} and the associated
-function will be called once for each new line to be read, the optional one is
-\type {close} that will be called once when \LUATEX\ is done with the file.
-
-\LUATEX\ never looks at the rest of the table, so you can use it to store your
-private per|-|file data. Both the callback functions will receive the table as
-their only argument.
-
-\stopitemize
-
-\subsubsection{\type {reader}}
-
-\topicindex{callbacks+reader}
-
-\LUATEX\ will run this function whenever it needs a new input line from the file.
-
-\startfunctioncall
-function(<table> env)
- return <string> line
-end
-\stopfunctioncall
-
-Your function should return either a string or \type {nil}. The value \type {nil}
-signals that the end of file has occurred, and will make \TEX\ call the optional
-\type {close} function next.
-
-\subsubsection{\type {close}}
-
-\topicindex{callbacks+closing files}
-
-\LUATEX\ will run this optional function when it decides to close the file.
-
-\startfunctioncall
-function(<table> env)
-end
-\stopfunctioncall
-
-Your function should not return any value.
-
-\subsection{General file readers}
-
-\topicindex{callbacks+readers}
-
-There is a set of callbacks for the loading of binary data files. These all use
-the same interface:
-
-\startfunctioncall
-function(<string> name)
- return <boolean> success, <string> data, <number> data_size
-end
-\stopfunctioncall
-
-The \type {name} will normally be a full path name as it is returned by either
-one of the file discovery callbacks or the internal version of \type
-{kpse.find_file()}.
-
-\startitemize
-
-\sym{success}
-
-Return \type {false} when a fatal error occurred (e.g.\ when the file cannot be
-found, after all).
-
-\sym{data}
-
-The bytes comprising the file.
-
-\sym{data_size}
-
-The length of the \type {data}, in bytes.
-
-\stopitemize
-
-Return an empty string and zero if the file was found but there was a
-reading problem.
-
-The list of functions is:
-
-\starttabulate[|l|p|]
-\DB function \BC usage \NC \NR
-\TB
-\NC \type{read_font_file} \NC ofm or tfm files \NC \NR
-\NC \type{read_vf_file} \NC virtual fonts \NC \NR
-\NC \type{read_map_file} \NC map files \NC \NR
-\NC \type{read_enc_file} \NC encoding files \NC \NR
-\NC \type{read_pk_file} \NC pk bitmap files \NC \NR
-\NC \type{read_data_file} \NC embedded files (as is possible with \PDF\ objects) \NC \NR
-\NC \type{read_truetype_file} \NC \TRUETYPE\ font files \NC \NR
-\NC \type{read_type1_file} \NC \TYPEONE\ font files \NC \NR
-\NC \type{read_opentype_file} \NC \OPENTYPE\ font files \NC \NR
-\LL
-\stoptabulate
-
-\stopsection
-
-\startsection[title={Data processing callbacks}][library=callback]
-
-\subsection{\cbk {process_input_buffer}}
-
-\topicindex{callbacks+input buffer}
-
-This callback allows you to change the contents of the line input buffer just
-before \LUATEX\ actually starts looking at it.
-
-\startfunctioncall
-function(<string> buffer)
- return <string> adjusted_buffer
-end
-\stopfunctioncall
-
-If you return \type {nil}, \LUATEX\ will pretend like your callback never
-happened. You can gain a small amount of processing time from that. This callback
-does not replace any internal code.
-
-\subsection{\cbk {process_output_buffer}}
-
-\topicindex{callbacks+output buffer}
-
-This callback allows you to change the contents of the line output buffer just
-before \LUATEX\ actually starts writing it to a file as the result of a \prm
-{write} command. It is only called for output to an actual file (that is,
-excluding the log, the terminal, and so called \prm {write} 18 calls).
-
-\startfunctioncall
-function(<string> buffer)
- return <string> adjusted_buffer
-end
-\stopfunctioncall
-
-If you return \type {nil}, \LUATEX\ will pretend like your callback never
-happened. You can gain a small amount of processing time from that. This callback
-does not replace any internal code.
-
-\subsection{\cbk {process_jobname}}
-
-\topicindex{callbacks+jobname}
-
-This callback allows you to change the jobname given by \prm {jobname} in \TEX\
-and \type {tex.jobname} in Lua. It does not affect the internal job name or the
-name of the output or log files.
-
-\startfunctioncall
-function(<string> jobname)
- return <string> adjusted_jobname
-end
-\stopfunctioncall
-
-The only argument is the actual job name; you should not use \type {tex.jobname}
-inside this function or infinite recursion may occur. If you return \type {nil},
-\LUATEX\ will pretend your callback never happened. This callback does not
-replace any internal code.
-
-\stopsection
-
-\startsection[title={Node list processing callbacks}][library=callback]
-
-The description of nodes and node lists is in~\in{chapter}[nodes].
-
-\subsection{\cbk {contribute_filter}}
-
-\topicindex{callbacks+contributions}
-
-This callback is called when \LUATEX\ adds contents to list:
-
-\startfunctioncall
-function(<string> extrainfo)
-end
-\stopfunctioncall
-
-The string reports the group code. From this you can deduce from
-what list you can give a treat.
-
-\starttabulate[|l|p|]
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type{pre_box} \NC interline material is being added \NC \NR
-\NC \type{pre_adjust} \NC \prm {vadjust} material is being added \NC \NR
-\NC \type{box} \NC a typeset box is being added (always called) \NC \NR
-\NC \type{adjust} \NC \prm {vadjust} material is being added \NC \NR
-\LL
-\stoptabulate
-
-\subsection{\cbk {buildpage_filter}}
-
-\topicindex{callbacks+building pages}
-
-This callback is called whenever \LUATEX\ is ready to move stuff to the main
-vertical list. You can use this callback to do specialized manipulation of the
-page building stage like imposition or column balancing.
-
-\startfunctioncall
-function(<string> extrainfo)
-end
-\stopfunctioncall
-
-The string \type {extrainfo} gives some additional information about what \TEX's
-state is with respect to the \quote {current page}. The possible values for the
-\cbk {buildpage_filter} callback are:
-
-\starttabulate[|l|p|]
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type{alignment} \NC a (partial) alignment is being added \NC \NR
-\NC \type{after_output} \NC an output routine has just finished \NC \NR
-\NC \type{new_graf} \NC the beginning of a new paragraph \NC \NR
-\NC \type{vmode_par} \NC \prm {par} was found in vertical mode \NC \NR
-\NC \type{hmode_par} \NC \prm {par} was found in horizontal mode \NC \NR
-\NC \type{insert} \NC an insert is added \NC \NR
-\NC \type{penalty} \NC a penalty (in vertical mode) \NC \NR
-\NC \type{before_display} \NC immediately before a display starts \NC \NR
-\NC \type{after_display} \NC a display is finished \NC \NR
-\NC \type{end} \NC \LUATEX\ is terminating (it's all over) \NC \NR
-\LL
-\stoptabulate
-
-\subsection{\cbk {build_page_insert}}
-
-\topicindex{callbacks+inserts}
-
-This callback is called when the pagebuilder adds an insert. There is not much
-control over this mechanism but this callback permits some last minute
-manipulations of the spacing before an insert, something that might be handy when
-for instance multiple inserts (types) are appended in a row.
-
-\startfunctioncall
-function(<number> n, <number> i)
- return <number> register
-end
-\stopfunctioncall
-
-with
-
-\starttabulate[|l|p|]
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type{n} \NC the insert class \NC \NR
-\NC \type{i} \NC the order of the insert \NC \NR
-\LL
-\stoptabulate
-
-The return value is a number indicating the skip register to use for the
-prepended spacing. This permits for instance a different top space (when \type
-{i} equals one) and intermediate space (when \type {i} is larger than one). Of
-course you can mess with the insert box but you need to make sure that \LUATEX\
-is happy afterwards.
-
-\subsection{\cbk {pre_linebreak_filter}}
-
-\topicindex{callbacks+linebreaks}
-
-This callback is called just before \LUATEX\ starts converting a list of nodes
-into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}.
-
-\startfunctioncall
-function(<node> head, <string> groupcode)
- return true | false | <node> newhead
-end
-\stopfunctioncall
-
-The string called \type {groupcode} identifies the nodelist's context within
-\TEX's processing. The range of possibilities is given in the table below, but
-not all of those can actually appear in \cbk {pre_linebreak_filter}, some are
-for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be
-explained in the next two paragraphs.
-
-\starttabulate[|l|p|]
-\DB value \BC explanation \NC \NR
-\TB
-\NC \type{<empty>} \NC main vertical list \NC \NR
-\NC \type{hbox} \NC \prm {hbox} in horizontal mode \NC \NR
-\NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode \NC \NR
-\NC \type{vbox} \NC \prm {vbox} \NC \NR
-\NC \type{vtop} \NC \prm {vtop} \NC \NR
-\NC \type{align} \NC \prm {halign} or \prm {valign} \NC \NR
-\NC \type{disc} \NC discretionaries \NC \NR
-\NC \type{insert} \NC packaging an insert \NC \NR
-\NC \type{vcenter} \NC \prm {vcenter} \NC \NR
-\NC \type{local_box} \NC \lpr {localleftbox} or \lpr {localrightbox} \NC \NR
-\NC \type{split_off} \NC top of a \prm {vsplit} \NC \NR
-\NC \type{split_keep} \NC remainder of a \prm {vsplit} \NC \NR
-\NC \type{align_set} \NC alignment cell \NC \NR
-\NC \type{fin_row} \NC alignment row \NC \NR
-\LL
-\stoptabulate
-
-As for all the callbacks that deal with nodes, the return value can be one of
-three things:
-
-\startitemize
-\startitem
- boolean \type {true} signals successful processing
-\stopitem
-\startitem
- \type {<node>} signals that the \quote {head} node should be replaced by the
- returned node
-\stopitem
-\startitem
- boolean \type {false} signals that the \quote {head} node list should be
- ignored and flushed from memory
-\stopitem
-\stopitemize
-
-This callback does not replace any internal code.
-
-\subsection{\cbk {linebreak_filter}}
-
-\topicindex{callbacks+linebreaks}
-
-This callback replaces \LUATEX's line breaking algorithm.
-
-\startfunctioncall
-function(<node> head, <boolean> is_display)
- return <node> newhead
-end
-\stopfunctioncall
-
-The returned node is the head of the list that will be added to the main vertical
-list, the boolean argument is true if this paragraph is interrupted by a
-following math display.
-
-If you return something that is not a \type {<node>}, \LUATEX\ will apply the
-internal linebreak algorithm on the list that starts at \type {<head>}.
-Otherwise, the \type {<node>} you return is supposed to be the head of a list of
-nodes that are all allowed in vertical mode, and at least one of those has to
-represent a hbox. Failure to do so will result in a fatal error.
-
-Setting this callback to \type {false} is possible, but dangerous, because it is
-possible you will end up in an unfixable \quote {deadcycles loop}.
-
-\subsection{\type {append_to_vlist_filter}}
-
-\topicindex{callbacks+contributions}
-
-This callback is called whenever \LUATEX\ adds a box to a vertical list:
-
-\startfunctioncall
-function(<node> box, <string> locationcode, <number prevdepth>,
- <boolean> mirrored)
- return list, prevdepth
-end
-\stopfunctioncall
-
-It is ok to return nothing in which case you also need to flush the box or deal
-with it yourself. The prevdepth is also optional. Locations are \type {box},
-\type {alignment}, \type {equation}, \type {equation_number} and \type
-{post_linebreak}.
-
-\subsection{\cbk {post_linebreak_filter}}
-
-\topicindex{callbacks+linebreaks}
-
-This callback is called just after \LUATEX\ has converted a list of nodes into a
-stack of \prm {hbox}es.
-
-\startfunctioncall
-function(<node> head, <string> groupcode)
- return true | false | <node> newhead
-end
-\stopfunctioncall
-
-This callback does not replace any internal code.
-
-\subsection{\cbk {hpack_filter}}
-
-\topicindex{callbacks+packing}
-
-This callback is called when \TEX\ is ready to start boxing some horizontal mode
-material. Math items and line boxes are ignored at the moment.
-
-\startfunctioncall
-function(<node> head, <string> groupcode, <number> size,
- <string> packtype [, <string> direction] [, <node> attributelist])
- return true | false | <node> newhead
-end
-\stopfunctioncall
-
-The \type {packtype} is either \type {additional} or \type {exactly}. If \type
-{additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
-\type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
-the number is in scaled points.
-
-The \type {direction} is either one of the three-letter direction specifier
-strings, or \type {nil}.
-
-This callback does not replace any internal code.
-
-\subsection{\cbk {vpack_filter}}
-
-\topicindex{callbacks+packing}
-
-This callback is called when \TEX\ is ready to start boxing some vertical mode
-material. Math displays are ignored at the moment.
-
-This function is very similar to the \cbk {hpack_filter}. Besides the fact
-that it is called at different moments, there is an extra variable that matches
-\TEX's \prm {maxdepth} setting.
-
-\startfunctioncall
-function(<node> head, <string> groupcode, <number> size, <string> packtype,
- <number> maxdepth [, <string> direction] [, <node> attributelist]))
- return true | false | <node> newhead
-end
-\stopfunctioncall
-
-This callback does not replace any internal code.
-
-\subsection{\type {hpack_quality}}
-
-\topicindex{callbacks+packing}
-
-This callback can be used to intercept the overfull messages that can result from
-packing a horizontal list (as happens in the par builder). The function takes a
-few arguments:
-
-\startfunctioncall
-function(<string> incident, <number> detail, <node> head, <number> first,
- <number> last)
- return <node> whatever
-end
-\stopfunctioncall
-
-The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
-\type {tight}. The detail is either the amount of overflow in case of \type
-{overfull}, or the badness otherwise. The head is the list that is constructed
-(when protrusion or expansion is enabled, this is an intermediate list).
-Optionally you can return a node, for instance an overfull rule indicator. That
-node will be appended to the list (just like \TEX's own rule would).
-
-\subsection{\type {vpack_quality}}
-
-\topicindex{callbacks+packing}
-
-This callback can be used to intercept the overfull messages that can result from
-packing a vertical list (as happens in the page builder). The function takes a
-few arguments:
-
-\startfunctioncall
-function(<string> incident, <number> detail, <node> head, <number> first,
- <number> last)
-end
-\stopfunctioncall
-
-The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
-\type {tight}. The detail is either the amount of overflow in case of \type
-{overfull}, or the badness otherwise. The head is the list that is constructed.
-
-\subsection{\cbk {process_rule}}
-
-\topicindex{callbacks+rules}
-
-This is an experimental callback. It can be used with rules of subtype~4
-(user). The callback gets three arguments: the node, the width and the
-height. The callback can use \type {pdf.print} to write code to the \PDF\
-file but beware of not messing up the final result. No checking is done.
-
-\subsection{\type {pre_output_filter}}
-
-\topicindex{callbacks+output}
-
-This callback is called when \TEX\ is ready to start boxing the box 255 for \prm
-{output}.
-
-\startfunctioncall
-function(<node> head, <string> groupcode, <number> size, <string> packtype,
- <number> maxdepth [, <string> direction])
- return true | false | <node> newhead
-end
-\stopfunctioncall
-
-This callback does not replace any internal code.
-
-\subsection{\cbk {hyphenate}}
-
-\topicindex{callbacks+hyphenation}
-
-\startfunctioncall
-function(<node> head, <node> tail)
-end
-\stopfunctioncall
-
-No return values. This callback has to insert discretionary nodes in the node
-list it receives.
-
-Setting this callback to \type {false} will prevent the internal discretionary
-insertion pass.
-
-\subsection{\cbk {ligaturing}}
-
-\topicindex{callbacks+ligature building}
-
-\startfunctioncall
-function(<node> head, <node> tail)
-end
-\stopfunctioncall
-
-No return values. This callback has to apply ligaturing to the node list it
-receives.
-
-You don't have to worry about return values because the \type {head} node that is
-passed on to the callback is guaranteed not to be a glyph_node (if need be, a
-temporary node will be prepended), and therefore it cannot be affected by the
-mutations that take place. After the callback, the internal value of the \quote
-{tail of the list} will be recalculated.
-
-The \type {next} of \type {head} is guaranteed to be non-nil.
-
-The \type {next} of \type {tail} is guaranteed to be nil, and therefore the
-second callback argument can often be ignored. It is provided for orthogonality,
-and because it can sometimes be handy when special processing has to take place.
-
-Setting this callback to \type {false} will prevent the internal ligature
-creation pass.
-
-You must not ruin the node list. For instance, the head normally is a local par node,
-and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
-
-\subsection{\cbk {kerning}}
-
-\topicindex{callbacks+kerning}
-
-\startfunctioncall
-function(<node> head, <node> tail)
-end
-\stopfunctioncall
-
-No return values. This callback has to apply kerning between the nodes in the
-node list it receives. See \cbk {ligaturing} for calling conventions.
-
-Setting this callback to \type {false} will prevent the internal kern insertion
-pass.
-
-You must not ruin the node list. For instance, the head normally is a local par node,
-and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
-
-\subsection{\type {insert_local_par}}
-
-Each paragraph starts with a local par node that keeps track of for instance
-the direction. You can hook a callback into the creator:
-
-\startfunctioncall
-function(<node> local_par, <string> location)
-end
-\stopfunctioncall
-
-There is no return value and you should make sure that the node stays valid
-as otherwise \TEX\ can get confused.
-
-\subsection{\cbk {mlist_to_hlist}}
-
-\topicindex{callbacks+math}
-
-This callback replaces \LUATEX's math list to node list conversion algorithm.
-
-\startfunctioncall
-function(<node> head, <string> display_type, <boolean> need_penalties)
- return <node> newhead
-end
-\stopfunctioncall
-
-The returned node is the head of the list that will be added to the vertical or
-horizontal list, the string argument is either \quote {text} or \quote {display}
-depending on the current math mode, the boolean argument is \type {true} if
-penalties have to be inserted in this list, \type {false} otherwise.
-
-Setting this callback to \type {false} is bad, it will almost certainly result in
-an endless loop.
-
-\stopsection
-
-\startsection[title={Information reporting callbacks}][library=callback]
-
-\subsection{\cbk {pre_dump}}
-
-\topicindex{callbacks+dump}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This function is called just before dumping to a format file starts. It does not
-replace any code and there are neither arguments nor return values.
-
-\subsection{\cbk {start_run}}
-
-\topicindex{callbacks+job run}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback replaces the code that prints \LUATEX's banner. Note that for
-successful use, this callback has to be set in the \LUA\ initialization script,
-otherwise it will be seen only after the run has already started.
-
-\subsection{\cbk {stop_run}}
-
-\topicindex{callbacks+job run}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback replaces the code that prints \LUATEX's statistics and \quote
-{output written to} messages. The engine can still do housekeeping and therefore
-you should not rely on this hook for postprocessing the \PDF\ or log file.
-
-\subsection{\cbk {start_page_number}}
-
-\topicindex{callbacks+pages}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-Replaces the code that prints the \type {[} and the page number at the begin of
-\prm {shipout}. This callback will also override the printing of box information
-that normally takes place when \prm {tracingoutput} is positive.
-
-\subsection{\cbk {stop_page_number}}
-
-\topicindex{callbacks+pages}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-Replaces the code that prints the \type {]} at the end of \prm {shipout}.
-
-\subsection{\cbk {show_error_hook}}
-
-\topicindex{callbacks+errors}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback is run from inside the \TEX\ error function, and the idea is to
-allow you to do some extra reporting on top of what \TEX\ already does (none of
-the normal actions are removed). You may find some of the values in the \type
-{status} table useful. This callback does not replace any internal code.
-
-\subsection{\cbk {show_error_message}}
-
-\topicindex{callbacks+errors}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback replaces the code that prints the error message. The usual
-interaction after the message is not affected.
-
-\subsection{\cbk {show_lua_error_hook}}
-
-\topicindex{callbacks+errors}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback replaces the code that prints the extra \LUA\ error message.
-
-\subsection{\cbk {start_file}}
-
-\topicindex{callbacks+files}
-
-\startfunctioncall
-function(category,filename)
-end
-\stopfunctioncall
-
-This callback replaces the code that prints \LUATEX's when a file is opened like
-\type {(filename} for regular files. The category is a number:
-
-\starttabulate[|c|l|]
-\DB value \BC meaning \NC \NR
-\TB
-\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
-\NC 2 \NC a font map coupling font names to resources \NC \NR
-\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
-\NC 4 \NC an embedded font subset \NC \NR
-\NC 5 \NC a fully embedded font \NC \NR
-\LL
-\stoptabulate
-
-\subsection{\cbk {stop_file}}
-
-\topicindex{callbacks+files}
-
-\startfunctioncall
-function(category)
-end
-\stopfunctioncall
-
-This callback replaces the code that prints \LUATEX's when a file is closed like
-the \type {)} for regular files.
-
-\subsection{\cbk {call_edit}}
-
-\topicindex{callbacks+editing}
-
-\startfunctioncall
-function(filename,linenumber)
-end
-\stopfunctioncall
-
-This callback replaces the call to an external editor when \quote{E} is pressed
-in reply to an error message. Processing will end immediately after the callback
-returns control to the main program.
-
-\subsection{\cbk {finish_synctex}}
-
-\topicindex{callbacks+synctex}
-
-This callback can be used to wrap up alternative synctex methods. It kicks in
-after the normal synctex finalizer (that happens to remove the synctex files
-after a run when native synctex is not enabled).
-
-\subsection{\cbk {wrapup_run}}
-
-\topicindex{callbacks+wrapping up}
-
-This callback is called after the \PDF\ and log files are closed. Use it at your own
-risk.
-
-\stopsection
-
-\startsection[title={\PDF\ related callbacks}][library=callback]
-
-\subsection{\cbk {finish_pdffile}}
-
-\topicindex{callbacks+\PDF\ file}
-
-\startfunctioncall
-function()
-end
-\stopfunctioncall
-
-This callback is called when all document pages are already written to the \PDF\
-file and \LUATEX\ is about to finalize the output document structure. Its
-intended use is final update of \PDF\ dictionaries such as \type {/Catalog} or
-\type {/Info}. The callback does not replace any code. There are neither
-arguments nor return values.
-
-\subsection{\cbk {finish_pdfpage}}
-
-\topicindex{callbacks+\PDF\ file}
-
-\startfunctioncall
-function(shippingout)
-end
-\stopfunctioncall
-
-This callback is called after the \PDF\ page stream has been assembled and before
-the page object gets finalized.
-
-\subsection{\cbk {page_objnum_provider}}
-
-\topicindex{callbacks+\PDF\ file}
-
-This is one that experts can use to juggle the page tree, a data structure
-that determines the order in a \PDF\ file:
-
-\startfunctioncall
-function(objnum)
- return objnum
-end
-\stopfunctioncall
-
-We can for instance swap the first and last page:
-
-\starttyping
-local n = 0
-callback.register("page_objnum_provider",function(objnum)
- n = n + 1
- if n == 1 then
- return pdf.getpageref(tex.count[0])
- elseif n == tex.count[0] then
- return pdf.getpageref(1)
- else
- return objnum
- end
-end)
-\stoptyping
-
-When you mess things up \unknown\ don't complain.
-
-\subsection{\cbk {process_pdf_image_content}}
-
-\topicindex{callbacks+image content}
-
-When a page from a \PDF\ file is embedded its page stream as well as related
-objects are copied to the target file. However, it can be that the page stream
-has operators that assume additional resources, for instance marked text. You can
-decide to filter that for which \LUATEX\ provides a callback. Here is a simple
-demonstration of use:
-
-\starttyping
-pdf.setrecompress(1)
-
-callback.register("process_pdf_image_content",function(s)
- print(s)
- return s
-end)
-\stoptyping
-
-You need to explicitly enable recompression because otherwise the content stream
-gets just passed on in its original compressed form.
-
-\stopsection
-
-\startsection[title={Font-related callbacks}][library=callback]
-
-\subsection{\cbk {define_font}}
-
-\topicindex{callbacks+fonts}
-
-\startfunctioncall
-function(<string> name, <number> size, <number> id)
- return <table> font | <number> id
-end
-\stopfunctioncall
-
-The string \type {name} is the filename part of the font specification, as given
-by the user.
-
-The number \type {size} is a bit special:
-
-\startitemize[packed]
-\startitem
- If it is positive, it specifies an \quote{at size} in scaled points.
-\stopitem
-\startitem
- If it is negative, its absolute value represents a \quote {scaled} setting
- relative to the designsize of the font.
-\stopitem
-\stopitemize
-
-The \type {id} is the internal number assigned to the font.
-
-The internal structure of the \type {font} table that is to be returned is
-explained in \in {chapter} [fonts]. That table is saved internally, so you can
-put extra fields in the table for your later \LUA\ code to use. In alternative,
-\type {retval} can be a previously defined fontid. This is useful if a previous
-definition can be reused instead of creating a whole new font structure.
-
-Setting this callback to \type {false} is pointless as it will prevent font
-loading completely but will nevertheless generate errors.
-
-\subsection{\cbk {glyph_not_found}}
-
-\topicindex{callbacks+fonts}
-
-This callback kicks in when the backend cannot insert a glyph. When no callback
-is defined a message is written to the log.
-
-\startfunctioncall
-function(<number> id, <number> char)
- -- do something with font id and char code
-end
-\stopfunctioncall
-
-\stopsection
-
-\stopchapter
-
-\stopcomponent
+% language=uk
+
+\environment luatex-style
+
+\startcomponent luatex-callbacks
+
+\startchapter[reference=callbacks,title={\LUA\ callbacks}]
+
+\startsection[title={Registering callbacks}][library=callback]
+
+\topicindex{callbacks}
+
+\libindex{register}
+\libindex{list}
+\libindex{find}
+
+This library has functions that register, find and list callbacks. Callbacks are
+\LUA\ functions that are called in well defined places. There are two kind of
+callbacks: those that mix with existing functionality, and those that (when
+enabled) replace functionality. In mosty cases the second category is expected to
+behave similar to the built in functionality because in a next step specific
+data is expected. For instance, you can replace the hyphenation routine. The
+function gets a list that can be hyphenated (or not). The final list should be
+valid and is (normally) used for constructing a paragraph. Another function can
+replace the ligature builder and|/|or kerner. Doing something else is possible
+but in the end might not give the user the expected outcome.
+
+The first thing you need to do is registering a callback:
+
+\startfunctioncall
+id, error =
+ callback.register(<string> callback_name, <function> func)
+id, error =
+ callback.register(<string> callback_name, nil)
+id, error =
+ callback.register(<string> callback_name, false)
+\stopfunctioncall
+
+Here the \syntax {callback_name} is a predefined callback name, see below. The
+function returns the internal \type {id} of the callback or \type {nil}, if the
+callback could not be registered. In the latter case, \type {error} contains an
+error message, otherwise it is \type {nil}.
+
+\LUATEX\ internalizes the callback function in such a way that it does not matter
+if you redefine a function accidentally.
+
+Callback assignments are always global. You can use the special value \type {nil}
+instead of a function for clearing the callback.
+
+For some minor speed gain, you can assign the boolean \type {false} to the
+non|-|file related callbacks, doing so will prevent \LUATEX\ from executing
+whatever it would execute by default (when no callback function is registered at
+all). Be warned: this may cause all sorts of grief unless you know \notabene
+{exactly} what you are doing!
+
+\startfunctioncall
+<table> info =
+ callback.list()
+\stopfunctioncall
+
+The keys in the table are the known callback names, the value is a boolean where
+\type {true} means that the callback is currently set (active).
+
+\startfunctioncall
+<function> f = callback.find(callback_name)
+\stopfunctioncall
+
+If the callback is not set, \type {find} returns \type {nil}.
+
+\stopsection
+
+\startsection[title={File discovery callbacks}][library=callback]
+
+The behaviour documented in this subsection is considered stable in the sense that
+there will not be backward|-|incompatible changes any more.
+
+\subsection{\cbk {find_read_file} and \cbk {find_write_file}}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<number> id_number, <string> asked_name)
+\stopfunctioncall
+
+Arguments:
+
+\startitemize
+
+\sym{id_number}
+
+This number is zero for the log or \prm {input} files. For \TEX's \prm {read}
+or \prm {write} the number is incremented by one, so \type {\read0} becomes~1.
+
+\sym{asked_name}
+
+This is the user|-|supplied filename, as found by \prm {input}, \prm {openin}
+or \prm {openout}.
+
+\stopitemize
+
+Return value:
+
+\startitemize
+
+\sym{actual_name}
+
+This is the filename used. For the very first file that is read in by \TEX, you
+have to make sure you return an \type {actual_name} that has an extension and
+that is suitable for use as \type {jobname}. If you don't, you will have to
+manually fix the name of the log file and output file after \LUATEX\ is finished,
+and an eventual format filename will become mangled. That is because these file
+names depend on the jobname.
+
+You have to return \type {nil} if the file cannot be found.
+
+\stopitemize
+
+\subsection{\cbk {find_font_file}}
+
+\topicindex{callbacks+font files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is an \OTF\ or \TFM\ font metrics file.
+
+Return \type {nil} if the file cannot be found.
+
+\subsection{\cbk {find_output_file}}
+
+\topicindex{callbacks+output file}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is the \PDF\ or \DVI\ file for writing.
+
+\subsection{\cbk {find_format_file}}
+
+\topicindex{callbacks+format file}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is a format file for reading (the format file for writing
+is always opened in the current directory).
+
+\subsection{\cbk {find_vf_file}}
+
+\topicindex{callbacks+font files}
+
+Like \cbk {find_font_file}, but for virtual fonts. This applies to both \ALEPH's
+\OVF\ files and traditional Knuthian \VF\ files.
+
+\subsection{\cbk {find_map_file}}
+
+\topicindex{callbacks+font files}
+
+Like \cbk {find_font_file}, but for map files.
+
+\subsection{\cbk {find_enc_file}}
+
+\topicindex{callbacks+font files}
+
+Like \cbk {find_font_file}, but for enc files.
+
+\subsection{\cbk {find_pk_file}}
+
+\topicindex{callbacks+font files}
+
+Like \cbk {find_font_file}, but for pk bitmap files. This callback takes two
+arguments: \type {name} and \type {dpi}. In your callback you can decide to
+look for:
+
+\starttyping
+<base res>dpi/<fontname>.<actual res>pk
+\stoptyping
+
+but other strategies are possible. It is up to you to find a \quote {reasonable}
+bitmap file to go with that specification.
+
+\subsection{\cbk {find_data_file}}
+
+\topicindex{callbacks+data files}
+
+Like \cbk {find_font_file}, but for embedded files (\type {\pdfobj file '...'}).
+
+\subsection{\cbk {find_opentype_file}}
+
+\topicindex{callbacks+font files}
+
+Like \cbk {find_font_file}, but for \OPENTYPE\ font files.
+
+\subsection{\cbk {find_truetype_file} and \cbk {find_type1_file}}
+
+\topicindex{callbacks+font files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is a font file. This callback is called while \LUATEX\ is
+building its internal list of needed font files, so the actual timing may
+surprise you. Your return value is later fed back into the matching \type
+{read_file} callback.
+
+Strangely enough, \cbk {find_type1_file} is also used for \OPENTYPE\ (\OTF)
+fonts.
+
+\subsection{\cbk {find_image_file}}
+
+\topicindex{callbacks+image files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<string> actual_name =
+ function (<string> asked_name)
+\stopfunctioncall
+
+The \type {asked_name} is an image file. Your return value is used to open a file
+from the hard disk, so make sure you return something that is considered the name
+of a valid file by your operating system.
+
+\stopsection
+
+\startsection[iocallback][title={File reading callbacks}]
+
+The behavior documented in this subsection is considered stable in the sense that
+there will not be backward-incompatible changes any more.
+
+\subsection{\cbk {open_read_file}}
+
+\topicindex{callbacks+opening files}
+
+Your callback function should have the following conventions:
+
+\startfunctioncall
+<table> env =
+ function (<string> file_name)
+\stopfunctioncall
+
+Argument:
+
+\startitemize
+
+\sym{file_name}
+
+The filename returned by a previous \cbk {find_read_file} or the return value of
+\type {kpse.find_file()} if there was no such callback defined.
+
+\stopitemize
+
+Return value:
+
+\startitemize
+
+\sym{env}
+
+This is a table containing at least one required and one optional callback
+function for this file. The required field is \type {reader} and the associated
+function will be called once for each new line to be read, the optional one is
+\type {close} that will be called once when \LUATEX\ is done with the file.
+
+\LUATEX\ never looks at the rest of the table, so you can use it to store your
+private per|-|file data. Both the callback functions will receive the table as
+their only argument.
+
+\stopitemize
+
+\subsubsection{\type {reader}}
+
+\topicindex{callbacks+reader}
+
+\LUATEX\ will run this function whenever it needs a new input line from the file.
+
+\startfunctioncall
+function(<table> env)
+ return <string> line
+end
+\stopfunctioncall
+
+Your function should return either a string or \type {nil}. The value \type {nil}
+signals that the end of file has occurred, and will make \TEX\ call the optional
+\type {close} function next.
+
+\subsubsection{\type {close}}
+
+\topicindex{callbacks+closing files}
+
+\LUATEX\ will run this optional function when it decides to close the file.
+
+\startfunctioncall
+function(<table> env)
+end
+\stopfunctioncall
+
+Your function should not return any value.
+
+\subsection{General file readers}
+
+\topicindex{callbacks+readers}
+
+There is a set of callbacks for the loading of binary data files. These all use
+the same interface:
+
+\startfunctioncall
+function(<string> name)
+ return <boolean> success, <string> data, <number> data_size
+end
+\stopfunctioncall
+
+The \type {name} will normally be a full path name as it is returned by either
+one of the file discovery callbacks or the internal version of \type
+{kpse.find_file()}.
+
+\startitemize
+
+\sym{success}
+
+Return \type {false} when a fatal error occurred (e.g.\ when the file cannot be
+found, after all).
+
+\sym{data}
+
+The bytes comprising the file.
+
+\sym{data_size}
+
+The length of the \type {data}, in bytes.
+
+\stopitemize
+
+Return an empty string and zero if the file was found but there was a
+reading problem.
+
+The list of functions is:
+
+\starttabulate[|l|p|]
+\DB function \BC usage \NC \NR
+\TB
+\NC \type{read_font_file} \NC ofm or tfm files \NC \NR
+\NC \type{read_vf_file} \NC virtual fonts \NC \NR
+\NC \type{read_map_file} \NC map files \NC \NR
+\NC \type{read_enc_file} \NC encoding files \NC \NR
+\NC \type{read_pk_file} \NC pk bitmap files \NC \NR
+\NC \type{read_data_file} \NC embedded files (as is possible with \PDF\ objects) \NC \NR
+\NC \type{read_truetype_file} \NC \TRUETYPE\ font files \NC \NR
+\NC \type{read_type1_file} \NC \TYPEONE\ font files \NC \NR
+\NC \type{read_opentype_file} \NC \OPENTYPE\ font files \NC \NR
+\LL
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Data processing callbacks}][library=callback]
+
+\subsection{\cbk {process_input_buffer}}
+
+\topicindex{callbacks+input buffer}
+
+This callback allows you to change the contents of the line input buffer just
+before \LUATEX\ actually starts looking at it.
+
+\startfunctioncall
+function(<string> buffer)
+ return <string> adjusted_buffer
+end
+\stopfunctioncall
+
+If you return \type {nil}, \LUATEX\ will pretend like your callback never
+happened. You can gain a small amount of processing time from that. This callback
+does not replace any internal code.
+
+\subsection{\cbk {process_output_buffer}}
+
+\topicindex{callbacks+output buffer}
+
+This callback allows you to change the contents of the line output buffer just
+before \LUATEX\ actually starts writing it to a file as the result of a \prm
+{write} command. It is only called for output to an actual file (that is,
+excluding the log, the terminal, and so called \prm {write} 18 calls).
+
+\startfunctioncall
+function(<string> buffer)
+ return <string> adjusted_buffer
+end
+\stopfunctioncall
+
+If you return \type {nil}, \LUATEX\ will pretend like your callback never
+happened. You can gain a small amount of processing time from that. This callback
+does not replace any internal code.
+
+\subsection{\cbk {process_jobname}}
+
+\topicindex{callbacks+jobname}
+
+This callback allows you to change the jobname given by \prm {jobname} in \TEX\
+and \type {tex.jobname} in Lua. It does not affect the internal job name or the
+name of the output or log files.
+
+\startfunctioncall
+function(<string> jobname)
+ return <string> adjusted_jobname
+end
+\stopfunctioncall
+
+The only argument is the actual job name; you should not use \type {tex.jobname}
+inside this function or infinite recursion may occur. If you return \type {nil},
+\LUATEX\ will pretend your callback never happened. This callback does not
+replace any internal code.
+
+\stopsection
+
+\startsection[title={Node list processing callbacks}][library=callback]
+
+The description of nodes and node lists is in~\in{chapter}[nodes].
+
+\subsection{\cbk {contribute_filter}}
+
+\topicindex{callbacks+contributions}
+
+This callback is called when \LUATEX\ adds contents to list:
+
+\startfunctioncall
+function(<string> extrainfo)
+end
+\stopfunctioncall
+
+The string reports the group code. From this you can deduce from
+what list you can give a treat.
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{pre_box} \NC interline material is being added \NC \NR
+\NC \type{pre_adjust} \NC \prm {vadjust} material is being added \NC \NR
+\NC \type{box} \NC a typeset box is being added (always called) \NC \NR
+\NC \type{adjust} \NC \prm {vadjust} material is being added \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {buildpage_filter}}
+
+\topicindex{callbacks+building pages}
+
+This callback is called whenever \LUATEX\ is ready to move stuff to the main
+vertical list. You can use this callback to do specialized manipulation of the
+page building stage like imposition or column balancing.
+
+\startfunctioncall
+function(<string> extrainfo)
+end
+\stopfunctioncall
+
+The string \type {extrainfo} gives some additional information about what \TEX's
+state is with respect to the \quote {current page}. The possible values for the
+\cbk {buildpage_filter} callback are:
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{alignment} \NC a (partial) alignment is being added \NC \NR
+\NC \type{after_output} \NC an output routine has just finished \NC \NR
+\NC \type{new_graf} \NC the beginning of a new paragraph \NC \NR
+\NC \type{vmode_par} \NC \prm {par} was found in vertical mode \NC \NR
+\NC \type{hmode_par} \NC \prm {par} was found in horizontal mode \NC \NR
+\NC \type{insert} \NC an insert is added \NC \NR
+\NC \type{penalty} \NC a penalty (in vertical mode) \NC \NR
+\NC \type{before_display} \NC immediately before a display starts \NC \NR
+\NC \type{after_display} \NC a display is finished \NC \NR
+\NC \type{end} \NC \LUATEX\ is terminating (it's all over) \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {build_page_insert}}
+
+\topicindex{callbacks+inserts}
+
+This callback is called when the pagebuilder adds an insert. There is not much
+control over this mechanism but this callback permits some last minute
+manipulations of the spacing before an insert, something that might be handy when
+for instance multiple inserts (types) are appended in a row.
+
+\startfunctioncall
+function(<number> n, <number> i)
+ return <number> register
+end
+\stopfunctioncall
+
+with
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{n} \NC the insert class \NC \NR
+\NC \type{i} \NC the order of the insert \NC \NR
+\LL
+\stoptabulate
+
+The return value is a number indicating the skip register to use for the
+prepended spacing. This permits for instance a different top space (when \type
+{i} equals one) and intermediate space (when \type {i} is larger than one). Of
+course you can mess with the insert box but you need to make sure that \LUATEX\
+is happy afterwards.
+
+\subsection{\cbk {pre_linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback is called just before \LUATEX\ starts converting a list of nodes
+into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}.
+
+\startfunctioncall
+function(<node> head, <string> groupcode)
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+The string called \type {groupcode} identifies the nodelist's context within
+\TEX's processing. The range of possibilities is given in the table below, but
+not all of those can actually appear in \cbk {pre_linebreak_filter}, some are
+for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be
+explained in the next two paragraphs.
+
+\starttabulate[|l|p|]
+\DB value \BC explanation \NC \NR
+\TB
+\NC \type{<empty>} \NC main vertical list \NC \NR
+\NC \type{hbox} \NC \prm {hbox} in horizontal mode \NC \NR
+\NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode \NC \NR
+\NC \type{vbox} \NC \prm {vbox} \NC \NR
+\NC \type{vtop} \NC \prm {vtop} \NC \NR
+\NC \type{align} \NC \prm {halign} or \prm {valign} \NC \NR
+\NC \type{disc} \NC discretionaries \NC \NR
+\NC \type{insert} \NC packaging an insert \NC \NR
+\NC \type{vcenter} \NC \prm {vcenter} \NC \NR
+\NC \type{local_box} \NC \lpr {localleftbox} or \lpr {localrightbox} \NC \NR
+\NC \type{split_off} \NC top of a \prm {vsplit} \NC \NR
+\NC \type{split_keep} \NC remainder of a \prm {vsplit} \NC \NR
+\NC \type{align_set} \NC alignment cell \NC \NR
+\NC \type{fin_row} \NC alignment row \NC \NR
+\LL
+\stoptabulate
+
+As for all the callbacks that deal with nodes, the return value can be one of
+three things:
+
+\startitemize
+\startitem
+ boolean \type {true} signals successful processing
+\stopitem
+\startitem
+ \type {<node>} signals that the \quote {head} node should be replaced by the
+ returned node
+\stopitem
+\startitem
+ boolean \type {false} signals that the \quote {head} node list should be
+ ignored and flushed from memory
+\stopitem
+\stopitemize
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback replaces \LUATEX's line breaking algorithm.
+
+\startfunctioncall
+function(<node> head, <boolean> is_display)
+ return <node> newhead
+end
+\stopfunctioncall
+
+The returned node is the head of the list that will be added to the main vertical
+list, the boolean argument is true if this paragraph is interrupted by a
+following math display.
+
+If you return something that is not a \type {<node>}, \LUATEX\ will apply the
+internal linebreak algorithm on the list that starts at \type {<head>}.
+Otherwise, the \type {<node>} you return is supposed to be the head of a list of
+nodes that are all allowed in vertical mode, and at least one of those has to
+represent a hbox. Failure to do so will result in a fatal error.
+
+Setting this callback to \type {false} is possible, but dangerous, because it is
+possible you will end up in an unfixable \quote {deadcycles loop}.
+
+\subsection{\type {append_to_vlist_filter}}
+
+\topicindex{callbacks+contributions}
+
+This callback is called whenever \LUATEX\ adds a box to a vertical list:
+
+\startfunctioncall
+function(<node> box, <string> locationcode, <number prevdepth>,
+ <boolean> mirrored)
+ return list, prevdepth
+end
+\stopfunctioncall
+
+It is ok to return nothing in which case you also need to flush the box or deal
+with it yourself. The prevdepth is also optional. Locations are \type {box},
+\type {alignment}, \type {equation}, \type {equation_number} and \type
+{post_linebreak}.
+
+\subsection{\cbk {post_linebreak_filter}}
+
+\topicindex{callbacks+linebreaks}
+
+This callback is called just after \LUATEX\ has converted a list of nodes into a
+stack of \prm {hbox}es.
+
+\startfunctioncall
+function(<node> head, <string> groupcode)
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {hpack_filter}}
+
+\topicindex{callbacks+packing}
+
+This callback is called when \TEX\ is ready to start boxing some horizontal mode
+material. Math items and line boxes are ignored at the moment.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size,
+ <string> packtype [, <string> direction] [, <node> attributelist])
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+The \type {packtype} is either \type {additional} or \type {exactly}. If \type
+{additional}, then the \type {size} is a \type {\hbox spread ...} argument. If
+\type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases,
+the number is in scaled points.
+
+The \type {direction} is either one of the three-letter direction specifier
+strings, or \type {nil}.
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {vpack_filter}}
+
+\topicindex{callbacks+packing}
+
+This callback is called when \TEX\ is ready to start boxing some vertical mode
+material. Math displays are ignored at the moment.
+
+This function is very similar to the \cbk {hpack_filter}. Besides the fact
+that it is called at different moments, there is an extra variable that matches
+\TEX's \prm {maxdepth} setting.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size, <string> packtype,
+ <number> maxdepth [, <string> direction] [, <node> attributelist]))
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\type {hpack_quality}}
+
+\topicindex{callbacks+packing}
+
+This callback can be used to intercept the overfull messages that can result from
+packing a horizontal list (as happens in the par builder). The function takes a
+few arguments:
+
+\startfunctioncall
+function(<string> incident, <number> detail, <node> head, <number> first,
+ <number> last)
+ return <node> whatever
+end
+\stopfunctioncall
+
+The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
+\type {tight}. The detail is either the amount of overflow in case of \type
+{overfull}, or the badness otherwise. The head is the list that is constructed
+(when protrusion or expansion is enabled, this is an intermediate list).
+Optionally you can return a node, for instance an overfull rule indicator. That
+node will be appended to the list (just like \TEX's own rule would).
+
+\subsection{\type {vpack_quality}}
+
+\topicindex{callbacks+packing}
+
+This callback can be used to intercept the overfull messages that can result from
+packing a vertical list (as happens in the page builder). The function takes a
+few arguments:
+
+\startfunctioncall
+function(<string> incident, <number> detail, <node> head, <number> first,
+ <number> last)
+end
+\stopfunctioncall
+
+The incident is one of \type {overfull}, \type {underfull}, \type {loose} or
+\type {tight}. The detail is either the amount of overflow in case of \type
+{overfull}, or the badness otherwise. The head is the list that is constructed.
+
+\subsection{\cbk {process_rule}}
+
+\topicindex{callbacks+rules}
+
+This is an experimental callback. It can be used with rules of subtype~4
+(user). The callback gets three arguments: the node, the width and the
+height. The callback can use \type {pdf.print} to write code to the \PDF\
+file but beware of not messing up the final result. No checking is done.
+
+\subsection{\type {pre_output_filter}}
+
+\topicindex{callbacks+output}
+
+This callback is called when \TEX\ is ready to start boxing the box 255 for \prm
+{output}.
+
+\startfunctioncall
+function(<node> head, <string> groupcode, <number> size, <string> packtype,
+ <number> maxdepth [, <string> direction])
+ return true | false | <node> newhead
+end
+\stopfunctioncall
+
+This callback does not replace any internal code.
+
+\subsection{\cbk {hyphenate}}
+
+\topicindex{callbacks+hyphenation}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to insert discretionary nodes in the node
+list it receives.
+
+Setting this callback to \type {false} will prevent the internal discretionary
+insertion pass.
+
+\subsection{\cbk {ligaturing}}
+
+\topicindex{callbacks+ligature building}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to apply ligaturing to the node list it
+receives.
+
+You don't have to worry about return values because the \type {head} node that is
+passed on to the callback is guaranteed not to be a glyph_node (if need be, a
+temporary node will be prepended), and therefore it cannot be affected by the
+mutations that take place. After the callback, the internal value of the \quote
+{tail of the list} will be recalculated.
+
+The \type {next} of \type {head} is guaranteed to be non-nil.
+
+The \type {next} of \type {tail} is guaranteed to be nil, and therefore the
+second callback argument can often be ignored. It is provided for orthogonality,
+and because it can sometimes be handy when special processing has to take place.
+
+Setting this callback to \type {false} will prevent the internal ligature
+creation pass.
+
+You must not ruin the node list. For instance, the head normally is a local par node,
+and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
+
+\subsection{\cbk {kerning}}
+
+\topicindex{callbacks+kerning}
+
+\startfunctioncall
+function(<node> head, <node> tail)
+end
+\stopfunctioncall
+
+No return values. This callback has to apply kerning between the nodes in the
+node list it receives. See \cbk {ligaturing} for calling conventions.
+
+Setting this callback to \type {false} will prevent the internal kern insertion
+pass.
+
+You must not ruin the node list. For instance, the head normally is a local par node,
+and the tail a glue. Messing too much can push \LUATEX\ into panic mode.
+
+\subsection{\type {insert_local_par}}
+
+Each paragraph starts with a local par node that keeps track of for instance
+the direction. You can hook a callback into the creator:
+
+\startfunctioncall
+function(<node> local_par, <string> location)
+end
+\stopfunctioncall
+
+There is no return value and you should make sure that the node stays valid
+as otherwise \TEX\ can get confused.
+
+\subsection{\cbk {mlist_to_hlist}}
+
+\topicindex{callbacks+math}
+
+This callback replaces \LUATEX's math list to node list conversion algorithm.
+
+\startfunctioncall
+function(<node> head, <string> display_type, <boolean> need_penalties)
+ return <node> newhead
+end
+\stopfunctioncall
+
+The returned node is the head of the list that will be added to the vertical or
+horizontal list, the string argument is either \quote {text} or \quote {display}
+depending on the current math mode, the boolean argument is \type {true} if
+penalties have to be inserted in this list, \type {false} otherwise.
+
+Setting this callback to \type {false} is bad, it will almost certainly result in
+an endless loop.
+
+\stopsection
+
+\startsection[title={Information reporting callbacks}][library=callback]
+
+\subsection{\cbk {pre_dump}}
+
+\topicindex{callbacks+dump}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This function is called just before dumping to a format file starts. It does not
+replace any code and there are neither arguments nor return values.
+
+\subsection{\cbk {start_run}}
+
+\topicindex{callbacks+job run}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's banner. Note that for
+successful use, this callback has to be set in the \LUA\ initialization script,
+otherwise it will be seen only after the run has already started.
+
+\subsection{\cbk {stop_run}}
+
+\topicindex{callbacks+job run}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's statistics and \quote
+{output written to} messages. The engine can still do housekeeping and therefore
+you should not rely on this hook for postprocessing the \PDF\ or log file.
+
+\subsection{\cbk {start_page_number}}
+
+\topicindex{callbacks+pages}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+Replaces the code that prints the \type {[} and the page number at the begin of
+\prm {shipout}. This callback will also override the printing of box information
+that normally takes place when \prm {tracingoutput} is positive.
+
+\subsection{\cbk {stop_page_number}}
+
+\topicindex{callbacks+pages}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+Replaces the code that prints the \type {]} at the end of \prm {shipout}.
+
+\subsection{\cbk {show_error_hook}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback is run from inside the \TEX\ error function, and the idea is to
+allow you to do some extra reporting on top of what \TEX\ already does (none of
+the normal actions are removed). You may find some of the values in the \type
+{status} table useful. This callback does not replace any internal code.
+
+\subsection{\cbk {show_error_message}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the error message. The usual
+interaction after the message is not affected.
+
+\subsection{\cbk {show_lua_error_hook}}
+
+\topicindex{callbacks+errors}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback replaces the code that prints the extra \LUA\ error message.
+
+\subsection{\cbk {start_file}}
+
+\topicindex{callbacks+files}
+
+\startfunctioncall
+function(category,filename)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is opened like
+\type {(filename} for regular files. The category is a number:
+
+\starttabulate[|c|l|]
+\DB value \BC meaning \NC \NR
+\TB
+\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR
+\NC 2 \NC a font map coupling font names to resources \NC \NR
+\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR
+\NC 4 \NC an embedded font subset \NC \NR
+\NC 5 \NC a fully embedded font \NC \NR
+\LL
+\stoptabulate
+
+\subsection{\cbk {stop_file}}
+
+\topicindex{callbacks+files}
+
+\startfunctioncall
+function(category)
+end
+\stopfunctioncall
+
+This callback replaces the code that prints \LUATEX's when a file is closed like
+the \type {)} for regular files.
+
+\subsection{\cbk {call_edit}}
+
+\topicindex{callbacks+editing}
+
+\startfunctioncall
+function(filename,linenumber)
+end
+\stopfunctioncall
+
+This callback replaces the call to an external editor when \quote{E} is pressed
+in reply to an error message. Processing will end immediately after the callback
+returns control to the main program.
+
+\subsection{\cbk {finish_synctex}}
+
+\topicindex{callbacks+synctex}
+
+This callback can be used to wrap up alternative synctex methods. It kicks in
+after the normal synctex finalizer (that happens to remove the synctex files
+after a run when native synctex is not enabled).
+
+\subsection{\cbk {wrapup_run}}
+
+\topicindex{callbacks+wrapping up}
+
+This callback is called after the \PDF\ and log files are closed. Use it at your own
+risk.
+
+\stopsection
+
+\startsection[title={\PDF\ related callbacks}][library=callback]
+
+\subsection{\cbk {finish_pdffile}}
+
+\topicindex{callbacks+\PDF\ file}
+
+\startfunctioncall
+function()
+end
+\stopfunctioncall
+
+This callback is called when all document pages are already written to the \PDF\
+file and \LUATEX\ is about to finalize the output document structure. Its
+intended use is final update of \PDF\ dictionaries such as \type {/Catalog} or
+\type {/Info}. The callback does not replace any code. There are neither
+arguments nor return values.
+
+\subsection{\cbk {finish_pdfpage}}
+
+\topicindex{callbacks+\PDF\ file}
+
+\startfunctioncall
+function(shippingout)
+end
+\stopfunctioncall
+
+This callback is called after the \PDF\ page stream has been assembled and before
+the page object gets finalized.
+
+\subsection{\cbk {page_objnum_provider}}
+
+\topicindex{callbacks+\PDF\ file}
+
+This is one that experts can use to juggle the page tree, a data structure
+that determines the order in a \PDF\ file:
+
+\startfunctioncall
+function(objnum)
+ return objnum
+end
+\stopfunctioncall
+
+We can for instance swap the first and last page:
+
+\starttyping
+local n = 0
+callback.register("page_objnum_provider",function(objnum)
+ n = n + 1
+ if n == 1 then
+ return pdf.getpageref(tex.count[0])
+ elseif n == tex.count[0] then
+ return pdf.getpageref(1)
+ else
+ return objnum
+ end
+end)
+\stoptyping
+
+When you mess things up \unknown\ don't complain.
+
+\subsection{\cbk {process_pdf_image_content}}
+
+\topicindex{callbacks+image content}
+
+When a page from a \PDF\ file is embedded its page stream as well as related
+objects are copied to the target file. However, it can be that the page stream
+has operators that assume additional resources, for instance marked text. You can
+decide to filter that for which \LUATEX\ provides a callback. Here is a simple
+demonstration of use:
+
+\starttyping
+pdf.setrecompress(1)
+
+callback.register("process_pdf_image_content",function(s)
+ print(s)
+ return s
+end)
+\stoptyping
+
+You need to explicitly enable recompression because otherwise the content stream
+gets just passed on in its original compressed form.
+
+\stopsection
+
+\startsection[title={Font-related callbacks}][library=callback]
+
+\subsection{\cbk {define_font}}
+
+\topicindex{callbacks+fonts}
+
+\startfunctioncall
+function(<string> name, <number> size, <number> id)
+ return <table> font | <number> id
+end
+\stopfunctioncall
+
+The string \type {name} is the filename part of the font specification, as given
+by the user.
+
+The number \type {size} is a bit special:
+
+\startitemize[packed]
+\startitem
+ If it is positive, it specifies an \quote{at size} in scaled points.
+\stopitem
+\startitem
+ If it is negative, its absolute value represents a \quote {scaled} setting
+ relative to the designsize of the font.
+\stopitem
+\stopitemize
+
+The \type {id} is the internal number assigned to the font.
+
+The internal structure of the \type {font} table that is to be returned is
+explained in \in {chapter} [fonts]. That table is saved internally, so you can
+put extra fields in the table for your later \LUA\ code to use. In alternative,
+\type {retval} can be a previously defined fontid. This is useful if a previous
+definition can be reused instead of creating a whole new font structure.
+
+Setting this callback to \type {false} is pointless as it will prevent font
+loading completely but will nevertheless generate errors.
+
+\subsection{\cbk {glyph_not_found} and \cbk {glyph_info}}
+
+\topicindex{callbacks+fonts}
+
+The \type {glyph_not_found} callback, when set, kicks in when the backend cannot
+insert a glyph. When no callback is defined a message is written to the log.
+
+\startfunctioncall
+function(<number> id, <number> char)
+ -- do something with font id and char code
+end
+\stopfunctioncall
+
+The \type {glyph_info} callback can be set to report a useful representation of a
+glyph.
+
+\startfunctioncall
+function(<node> g)
+ -- return a string or nil
+end
+\stopfunctioncall
+
+When \type {nil} is returned the character code is printed, otherwise the
+returned string is used. By default the \UTF\ representation is shown which is
+not always that useful, especially when there is no real representation. Keep in
+mind that setting this callback can change the log in an incompatible way.
+
+\stopsection
+
+\stopchapter
+
+\stopcomponent