| 1 |
% language=uk |
| 2 |
|
| 3 |
\environment luatex-style |
| 4 |
|
| 5 |
\startcomponent luatex-callbacks |
| 6 |
|
| 7 |
\startchapter[reference=callbacks,title={\LUA\ callbacks}] |
| 8 |
|
| 9 |
\startsection[title={Registering callbacks}][library=callback] |
| 10 |
|
| 11 |
\topicindex{callbacks} |
| 12 |
|
| 13 |
\libindex{register} |
| 14 |
\libindex{list} |
| 15 |
\libindex{find} |
| 16 |
|
| 17 |
This library has functions that register, find and list callbacks. Callbacks are |
| 18 |
\LUA\ functions that are called in well defined places. There are two kind of |
| 19 |
callbacks: those that mix with existing functionality, and those that (when |
| 20 |
enabled) replace functionality. In mosty cases the second category is expected to |
| 21 |
behave similar to the built in functionality because in a next step specific |
| 22 |
data is expected. For instance, you can replace the hyphenation routine. The |
| 23 |
function gets a list that can be hyphenated (or not). The final list should be |
| 24 |
valid and is (normally) used for constructing a paragraph. Another function can |
| 25 |
replace the ligature builder and|/|or kerner. Doing something else is possible |
| 26 |
but in the end might not give the user the expected outcome. |
| 27 |
|
| 28 |
The first thing you need to do is registering a callback: |
| 29 |
|
| 30 |
\startfunctioncall |
| 31 |
id, error = |
| 32 |
callback.register(<string> callback_name, <function> func) |
| 33 |
id, error = |
| 34 |
callback.register(<string> callback_name, nil) |
| 35 |
id, error = |
| 36 |
callback.register(<string> callback_name, false) |
| 37 |
\stopfunctioncall |
| 38 |
|
| 39 |
Here the \syntax {callback_name} is a predefined callback name, see below. The |
| 40 |
function returns the internal \type {id} of the callback or \type {nil}, if the |
| 41 |
callback could not be registered. In the latter case, \type {error} contains an |
| 42 |
error message, otherwise it is \type {nil}. |
| 43 |
|
| 44 |
\LUATEX\ internalizes the callback function in such a way that it does not matter |
| 45 |
if you redefine a function accidentally. |
| 46 |
|
| 47 |
Callback assignments are always global. You can use the special value \type {nil} |
| 48 |
instead of a function for clearing the callback. |
| 49 |
|
| 50 |
For some minor speed gain, you can assign the boolean \type {false} to the |
| 51 |
non|-|file related callbacks, doing so will prevent \LUATEX\ from executing |
| 52 |
whatever it would execute by default (when no callback function is registered at |
| 53 |
all). Be warned: this may cause all sorts of grief unless you know \notabene |
| 54 |
{exactly} what you are doing! |
| 55 |
|
| 56 |
\startfunctioncall |
| 57 |
<table> info = |
| 58 |
callback.list() |
| 59 |
\stopfunctioncall |
| 60 |
|
| 61 |
The keys in the table are the known callback names, the value is a boolean where |
| 62 |
\type {true} means that the callback is currently set (active). |
| 63 |
|
| 64 |
\startfunctioncall |
| 65 |
<function> f = callback.find(callback_name) |
| 66 |
\stopfunctioncall |
| 67 |
|
| 68 |
If the callback is not set, \type {find} returns \type {nil}. |
| 69 |
|
| 70 |
\stopsection |
| 71 |
|
| 72 |
\startsection[title={File discovery callbacks}][library=callback] |
| 73 |
|
| 74 |
The behaviour documented in this subsection is considered stable in the sense that |
| 75 |
there will not be backward|-|incompatible changes any more. |
| 76 |
|
| 77 |
\subsection{\cbk {find_read_file} and \cbk {find_write_file}} |
| 78 |
|
| 79 |
Your callback function should have the following conventions: |
| 80 |
|
| 81 |
\startfunctioncall |
| 82 |
<string> actual_name = |
| 83 |
function (<number> id_number, <string> asked_name) |
| 84 |
\stopfunctioncall |
| 85 |
|
| 86 |
Arguments: |
| 87 |
|
| 88 |
\startitemize |
| 89 |
|
| 90 |
\sym{id_number} |
| 91 |
|
| 92 |
This number is zero for the log or \prm {input} files. For \TEX's \prm {read} |
| 93 |
or \prm {write} the number is incremented by one, so \type {\read0} becomes~1. |
| 94 |
|
| 95 |
\sym{asked_name} |
| 96 |
|
| 97 |
This is the user|-|supplied filename, as found by \prm {input}, \prm {openin} |
| 98 |
or \prm {openout}. |
| 99 |
|
| 100 |
\stopitemize |
| 101 |
|
| 102 |
Return value: |
| 103 |
|
| 104 |
\startitemize |
| 105 |
|
| 106 |
\sym{actual_name} |
| 107 |
|
| 108 |
This is the filename used. For the very first file that is read in by \TEX, you |
| 109 |
have to make sure you return an \type {actual_name} that has an extension and |
| 110 |
that is suitable for use as \type {jobname}. If you don't, you will have to |
| 111 |
manually fix the name of the log file and output file after \LUATEX\ is finished, |
| 112 |
and an eventual format filename will become mangled. That is because these file |
| 113 |
names depend on the jobname. |
| 114 |
|
| 115 |
You have to return \type {nil} if the file cannot be found. |
| 116 |
|
| 117 |
\stopitemize |
| 118 |
|
| 119 |
\subsection{\cbk {find_font_file}} |
| 120 |
|
| 121 |
\topicindex{callbacks+font files} |
| 122 |
|
| 123 |
Your callback function should have the following conventions: |
| 124 |
|
| 125 |
\startfunctioncall |
| 126 |
<string> actual_name = |
| 127 |
function (<string> asked_name) |
| 128 |
\stopfunctioncall |
| 129 |
|
| 130 |
The \type {asked_name} is an \OTF\ or \TFM\ font metrics file. |
| 131 |
|
| 132 |
Return \type {nil} if the file cannot be found. |
| 133 |
|
| 134 |
\subsection{\cbk {find_output_file}} |
| 135 |
|
| 136 |
\topicindex{callbacks+output file} |
| 137 |
|
| 138 |
Your callback function should have the following conventions: |
| 139 |
|
| 140 |
\startfunctioncall |
| 141 |
<string> actual_name = |
| 142 |
function (<string> asked_name) |
| 143 |
\stopfunctioncall |
| 144 |
|
| 145 |
The \type {asked_name} is the \PDF\ or \DVI\ file for writing. |
| 146 |
|
| 147 |
\subsection{\cbk {find_format_file}} |
| 148 |
|
| 149 |
\topicindex{callbacks+format file} |
| 150 |
|
| 151 |
Your callback function should have the following conventions: |
| 152 |
|
| 153 |
\startfunctioncall |
| 154 |
<string> actual_name = |
| 155 |
function (<string> asked_name) |
| 156 |
\stopfunctioncall |
| 157 |
|
| 158 |
The \type {asked_name} is a format file for reading (the format file for writing |
| 159 |
is always opened in the current directory). |
| 160 |
|
| 161 |
\subsection{\cbk {find_vf_file}} |
| 162 |
|
| 163 |
\topicindex{callbacks+font files} |
| 164 |
|
| 165 |
Like \cbk {find_font_file}, but for virtual fonts. This applies to both \ALEPH's |
| 166 |
\OVF\ files and traditional Knuthian \VF\ files. |
| 167 |
|
| 168 |
\subsection{\cbk {find_map_file}} |
| 169 |
|
| 170 |
\topicindex{callbacks+font files} |
| 171 |
|
| 172 |
Like \cbk {find_font_file}, but for map files. |
| 173 |
|
| 174 |
\subsection{\cbk {find_enc_file}} |
| 175 |
|
| 176 |
\topicindex{callbacks+font files} |
| 177 |
|
| 178 |
Like \cbk {find_font_file}, but for enc files. |
| 179 |
|
| 180 |
\subsection{\cbk {find_pk_file}} |
| 181 |
|
| 182 |
\topicindex{callbacks+font files} |
| 183 |
|
| 184 |
Like \cbk {find_font_file}, but for pk bitmap files. This callback takes two |
| 185 |
arguments: \type {name} and \type {dpi}. In your callback you can decide to |
| 186 |
look for: |
| 187 |
|
| 188 |
\starttyping |
| 189 |
<base res>dpi/<fontname>.<actual res>pk |
| 190 |
\stoptyping |
| 191 |
|
| 192 |
but other strategies are possible. It is up to you to find a \quote {reasonable} |
| 193 |
bitmap file to go with that specification. |
| 194 |
|
| 195 |
\subsection{\cbk {find_data_file}} |
| 196 |
|
| 197 |
\topicindex{callbacks+data files} |
| 198 |
|
| 199 |
Like \cbk {find_font_file}, but for embedded files (\type {\pdfobj file '...'}). |
| 200 |
|
| 201 |
\subsection{\cbk {find_opentype_file}} |
| 202 |
|
| 203 |
\topicindex{callbacks+font files} |
| 204 |
|
| 205 |
Like \cbk {find_font_file}, but for \OPENTYPE\ font files. |
| 206 |
|
| 207 |
\subsection{\cbk {find_truetype_file} and \cbk {find_type1_file}} |
| 208 |
|
| 209 |
\topicindex{callbacks+font files} |
| 210 |
|
| 211 |
Your callback function should have the following conventions: |
| 212 |
|
| 213 |
\startfunctioncall |
| 214 |
<string> actual_name = |
| 215 |
function (<string> asked_name) |
| 216 |
\stopfunctioncall |
| 217 |
|
| 218 |
The \type {asked_name} is a font file. This callback is called while \LUATEX\ is |
| 219 |
building its internal list of needed font files, so the actual timing may |
| 220 |
surprise you. Your return value is later fed back into the matching \type |
| 221 |
{read_file} callback. |
| 222 |
|
| 223 |
Strangely enough, \cbk {find_type1_file} is also used for \OPENTYPE\ (\OTF) |
| 224 |
fonts. |
| 225 |
|
| 226 |
\subsection{\cbk {find_image_file}} |
| 227 |
|
| 228 |
\topicindex{callbacks+image files} |
| 229 |
|
| 230 |
Your callback function should have the following conventions: |
| 231 |
|
| 232 |
\startfunctioncall |
| 233 |
<string> actual_name = |
| 234 |
function (<string> asked_name) |
| 235 |
\stopfunctioncall |
| 236 |
|
| 237 |
The \type {asked_name} is an image file. Your return value is used to open a file |
| 238 |
from the hard disk, so make sure you return something that is considered the name |
| 239 |
of a valid file by your operating system. |
| 240 |
|
| 241 |
\stopsection |
| 242 |
|
| 243 |
\startsection[reference=iocallback,title={File reading callbacks}] |
| 244 |
|
| 245 |
The behavior documented in this subsection is considered stable in the sense that |
| 246 |
there will not be backward-incompatible changes any more. |
| 247 |
|
| 248 |
\subsection{\cbk {open_read_file}} |
| 249 |
|
| 250 |
\topicindex{callbacks+opening files} |
| 251 |
|
| 252 |
Your callback function should have the following conventions: |
| 253 |
|
| 254 |
\startfunctioncall |
| 255 |
<table> env = |
| 256 |
function (<string> file_name) |
| 257 |
\stopfunctioncall |
| 258 |
|
| 259 |
Argument: |
| 260 |
|
| 261 |
\startitemize |
| 262 |
|
| 263 |
\sym{file_name} |
| 264 |
|
| 265 |
The filename returned by a previous \cbk {find_read_file} or the return value of |
| 266 |
\type {kpse.find_file()} if there was no such callback defined. |
| 267 |
|
| 268 |
\stopitemize |
| 269 |
|
| 270 |
Return value: |
| 271 |
|
| 272 |
\startitemize |
| 273 |
|
| 274 |
\sym{env} |
| 275 |
|
| 276 |
This is a table containing at least one required and one optional callback |
| 277 |
function for this file. The required field is \type {reader} and the associated |
| 278 |
function will be called once for each new line to be read, the optional one is |
| 279 |
\type {close} that will be called once when \LUATEX\ is done with the file. |
| 280 |
|
| 281 |
\LUATEX\ never looks at the rest of the table, so you can use it to store your |
| 282 |
private per|-|file data. Both the callback functions will receive the table as |
| 283 |
their only argument. |
| 284 |
|
| 285 |
\stopitemize |
| 286 |
|
| 287 |
\subsubsection{\type {reader}} |
| 288 |
|
| 289 |
\topicindex{callbacks+reader} |
| 290 |
|
| 291 |
\LUATEX\ will run this function whenever it needs a new input line from the file. |
| 292 |
|
| 293 |
\startfunctioncall |
| 294 |
function(<table> env) |
| 295 |
return <string> line |
| 296 |
end |
| 297 |
\stopfunctioncall |
| 298 |
|
| 299 |
Your function should return either a string or \type {nil}. The value \type {nil} |
| 300 |
signals that the end of file has occurred, and will make \TEX\ call the optional |
| 301 |
\type {close} function next. |
| 302 |
|
| 303 |
\subsubsection{\type {close}} |
| 304 |
|
| 305 |
\topicindex{callbacks+closing files} |
| 306 |
|
| 307 |
\LUATEX\ will run this optional function when it decides to close the file. |
| 308 |
|
| 309 |
\startfunctioncall |
| 310 |
function(<table> env) |
| 311 |
end |
| 312 |
\stopfunctioncall |
| 313 |
|
| 314 |
Your function should not return any value. |
| 315 |
|
| 316 |
\subsection{General file readers} |
| 317 |
|
| 318 |
\topicindex{callbacks+readers} |
| 319 |
|
| 320 |
There is a set of callbacks for the loading of binary data files. These all use |
| 321 |
the same interface: |
| 322 |
|
| 323 |
\startfunctioncall |
| 324 |
function(<string> name) |
| 325 |
return <boolean> success, <string> data, <number> data_size |
| 326 |
end |
| 327 |
\stopfunctioncall |
| 328 |
|
| 329 |
The \type {name} will normally be a full path name as it is returned by either |
| 330 |
one of the file discovery callbacks or the internal version of \type |
| 331 |
{kpse.find_file()}. |
| 332 |
|
| 333 |
\startitemize |
| 334 |
|
| 335 |
\sym{success} |
| 336 |
|
| 337 |
Return \type {false} when a fatal error occurred (e.g.\ when the file cannot be |
| 338 |
found, after all). |
| 339 |
|
| 340 |
\sym{data} |
| 341 |
|
| 342 |
The bytes comprising the file. |
| 343 |
|
| 344 |
\sym{data_size} |
| 345 |
|
| 346 |
The length of the \type {data}, in bytes. |
| 347 |
|
| 348 |
\stopitemize |
| 349 |
|
| 350 |
Return an empty string and zero if the file was found but there was a |
| 351 |
reading problem. |
| 352 |
|
| 353 |
The list of functions is: |
| 354 |
|
| 355 |
\starttabulate[|l|p|] |
| 356 |
\DB function \BC usage \NC \NR |
| 357 |
\TB |
| 358 |
\NC \type{read_font_file} \NC ofm or tfm files \NC \NR |
| 359 |
\NC \type{read_vf_file} \NC virtual fonts \NC \NR |
| 360 |
\NC \type{read_map_file} \NC map files \NC \NR |
| 361 |
\NC \type{read_enc_file} \NC encoding files \NC \NR |
| 362 |
\NC \type{read_pk_file} \NC pk bitmap files \NC \NR |
| 363 |
\NC \type{read_data_file} \NC embedded files (as is possible with \PDF\ objects) \NC \NR |
| 364 |
\NC \type{read_truetype_file} \NC \TRUETYPE\ font files \NC \NR |
| 365 |
\NC \type{read_type1_file} \NC \TYPEONE\ font files \NC \NR |
| 366 |
\NC \type{read_opentype_file} \NC \OPENTYPE\ font files \NC \NR |
| 367 |
\LL |
| 368 |
\stoptabulate |
| 369 |
|
| 370 |
\stopsection |
| 371 |
|
| 372 |
\startsection[title={Data processing callbacks}][library=callback] |
| 373 |
|
| 374 |
\subsection{\cbk {process_input_buffer}} |
| 375 |
|
| 376 |
\topicindex{callbacks+input buffer} |
| 377 |
|
| 378 |
This callback allows you to change the contents of the line input buffer just |
| 379 |
before \LUATEX\ actually starts looking at it. |
| 380 |
|
| 381 |
\startfunctioncall |
| 382 |
function(<string> buffer) |
| 383 |
return <string> adjusted_buffer |
| 384 |
end |
| 385 |
\stopfunctioncall |
| 386 |
|
| 387 |
If you return \type {nil}, \LUATEX\ will pretend like your callback never |
| 388 |
happened. You can gain a small amount of processing time from that. This callback |
| 389 |
does not replace any internal code. |
| 390 |
|
| 391 |
\subsection{\cbk {process_output_buffer}} |
| 392 |
|
| 393 |
\topicindex{callbacks+output buffer} |
| 394 |
|
| 395 |
This callback allows you to change the contents of the line output buffer just |
| 396 |
before \LUATEX\ actually starts writing it to a file as the result of a \prm |
| 397 |
{write} command. It is only called for output to an actual file (that is, |
| 398 |
excluding the log, the terminal, and so called \prm {write} 18 calls). |
| 399 |
|
| 400 |
\startfunctioncall |
| 401 |
function(<string> buffer) |
| 402 |
return <string> adjusted_buffer |
| 403 |
end |
| 404 |
\stopfunctioncall |
| 405 |
|
| 406 |
If you return \type {nil}, \LUATEX\ will pretend like your callback never |
| 407 |
happened. You can gain a small amount of processing time from that. This callback |
| 408 |
does not replace any internal code. |
| 409 |
|
| 410 |
\subsection{\cbk {process_jobname}} |
| 411 |
|
| 412 |
\topicindex{callbacks+jobname} |
| 413 |
|
| 414 |
This callback allows you to change the jobname given by \prm {jobname} in \TEX\ |
| 415 |
and \type {tex.jobname} in Lua. It does not affect the internal job name or the |
| 416 |
name of the output or log files. |
| 417 |
|
| 418 |
\startfunctioncall |
| 419 |
function(<string> jobname) |
| 420 |
return <string> adjusted_jobname |
| 421 |
end |
| 422 |
\stopfunctioncall |
| 423 |
|
| 424 |
The only argument is the actual job name; you should not use \type {tex.jobname} |
| 425 |
inside this function or infinite recursion may occur. If you return \type {nil}, |
| 426 |
\LUATEX\ will pretend your callback never happened. This callback does not |
| 427 |
replace any internal code. |
| 428 |
|
| 429 |
\stopsection |
| 430 |
|
| 431 |
\startsection[title={Node list processing callbacks}][library=callback] |
| 432 |
|
| 433 |
The description of nodes and node lists is in~\in{chapter}[nodes]. |
| 434 |
|
| 435 |
\subsection{\cbk {contribute_filter}} |
| 436 |
|
| 437 |
\topicindex{callbacks+contributions} |
| 438 |
|
| 439 |
This callback is called when \LUATEX\ adds contents to list: |
| 440 |
|
| 441 |
\startfunctioncall |
| 442 |
function(<string> extrainfo) |
| 443 |
end |
| 444 |
\stopfunctioncall |
| 445 |
|
| 446 |
The string reports the group code. From this you can deduce from |
| 447 |
what list you can give a treat. |
| 448 |
|
| 449 |
\starttabulate[|l|p|] |
| 450 |
\DB value \BC explanation \NC \NR |
| 451 |
\TB |
| 452 |
\NC \type{pre_box} \NC interline material is being added \NC \NR |
| 453 |
\NC \type{pre_adjust} \NC \prm {vadjust} material is being added \NC \NR |
| 454 |
\NC \type{box} \NC a typeset box is being added (always called) \NC \NR |
| 455 |
\NC \type{adjust} \NC \prm {vadjust} material is being added \NC \NR |
| 456 |
\LL |
| 457 |
\stoptabulate |
| 458 |
|
| 459 |
\subsection{\cbk {buildpage_filter}} |
| 460 |
|
| 461 |
\topicindex{callbacks+building pages} |
| 462 |
|
| 463 |
This callback is called whenever \LUATEX\ is ready to move stuff to the main |
| 464 |
vertical list. You can use this callback to do specialized manipulation of the |
| 465 |
page building stage like imposition or column balancing. |
| 466 |
|
| 467 |
\startfunctioncall |
| 468 |
function(<string> extrainfo) |
| 469 |
end |
| 470 |
\stopfunctioncall |
| 471 |
|
| 472 |
The string \type {extrainfo} gives some additional information about what \TEX's |
| 473 |
state is with respect to the \quote {current page}. The possible values for the |
| 474 |
\cbk {buildpage_filter} callback are: |
| 475 |
|
| 476 |
\starttabulate[|l|p|] |
| 477 |
\DB value \BC explanation \NC \NR |
| 478 |
\TB |
| 479 |
\NC \type{alignment} \NC a (partial) alignment is being added \NC \NR |
| 480 |
\NC \type{after_output} \NC an output routine has just finished \NC \NR |
| 481 |
\NC \type{new_graf} \NC the beginning of a new paragraph \NC \NR |
| 482 |
\NC \type{vmode_par} \NC \prm {par} was found in vertical mode \NC \NR |
| 483 |
\NC \type{hmode_par} \NC \prm {par} was found in horizontal mode \NC \NR |
| 484 |
\NC \type{insert} \NC an insert is added \NC \NR |
| 485 |
\NC \type{penalty} \NC a penalty (in vertical mode) \NC \NR |
| 486 |
\NC \type{before_display} \NC immediately before a display starts \NC \NR |
| 487 |
\NC \type{after_display} \NC a display is finished \NC \NR |
| 488 |
\NC \type{end} \NC \LUATEX\ is terminating (it's all over) \NC \NR |
| 489 |
\LL |
| 490 |
\stoptabulate |
| 491 |
|
| 492 |
\subsection{\cbk {build_page_insert}} |
| 493 |
|
| 494 |
\topicindex{callbacks+inserts} |
| 495 |
|
| 496 |
This callback is called when the pagebuilder adds an insert. There is not much |
| 497 |
control over this mechanism but this callback permits some last minute |
| 498 |
manipulations of the spacing before an insert, something that might be handy when |
| 499 |
for instance multiple inserts (types) are appended in a row. |
| 500 |
|
| 501 |
\startfunctioncall |
| 502 |
function(<number> n, <number> i) |
| 503 |
return <number> register |
| 504 |
end |
| 505 |
\stopfunctioncall |
| 506 |
|
| 507 |
with |
| 508 |
|
| 509 |
\starttabulate[|l|p|] |
| 510 |
\DB value \BC explanation \NC \NR |
| 511 |
\TB |
| 512 |
\NC \type{n} \NC the insert class \NC \NR |
| 513 |
\NC \type{i} \NC the order of the insert \NC \NR |
| 514 |
\LL |
| 515 |
\stoptabulate |
| 516 |
|
| 517 |
The return value is a number indicating the skip register to use for the |
| 518 |
prepended spacing. This permits for instance a different top space (when \type |
| 519 |
{i} equals one) and intermediate space (when \type {i} is larger than one). Of |
| 520 |
course you can mess with the insert box but you need to make sure that \LUATEX\ |
| 521 |
is happy afterwards. |
| 522 |
|
| 523 |
\subsection{\cbk {pre_linebreak_filter}} |
| 524 |
|
| 525 |
\topicindex{callbacks+linebreaks} |
| 526 |
|
| 527 |
This callback is called just before \LUATEX\ starts converting a list of nodes |
| 528 |
into a stack of \prm {hbox}es, after the addition of \prm {parfillskip}. |
| 529 |
|
| 530 |
\startfunctioncall |
| 531 |
function(<node> head, <string> groupcode) |
| 532 |
return true | false | <node> newhead |
| 533 |
end |
| 534 |
\stopfunctioncall |
| 535 |
|
| 536 |
The string called \type {groupcode} identifies the nodelist's context within |
| 537 |
\TEX's processing. The range of possibilities is given in the table below, but |
| 538 |
not all of those can actually appear in \cbk {pre_linebreak_filter}, some are |
| 539 |
for the \cbk {hpack_filter} and \cbk {vpack_filter} callbacks that will be |
| 540 |
explained in the next two paragraphs. |
| 541 |
|
| 542 |
\starttabulate[|l|p|] |
| 543 |
\DB value \BC explanation \NC \NR |
| 544 |
\TB |
| 545 |
\NC \type{<empty>} \NC main vertical list \NC \NR |
| 546 |
\NC \type{hbox} \NC \prm {hbox} in horizontal mode \NC \NR |
| 547 |
\NC \type{adjusted_hbox} \NC \prm {hbox} in vertical mode \NC \NR |
| 548 |
\NC \type{vbox} \NC \prm {vbox} \NC \NR |
| 549 |
\NC \type{vtop} \NC \prm {vtop} \NC \NR |
| 550 |
\NC \type{align} \NC \prm {halign} or \prm {valign} \NC \NR |
| 551 |
\NC \type{disc} \NC discretionaries \NC \NR |
| 552 |
\NC \type{insert} \NC packaging an insert \NC \NR |
| 553 |
\NC \type{vcenter} \NC \prm {vcenter} \NC \NR |
| 554 |
\NC \type{local_box} \NC \lpr {localleftbox} or \lpr {localrightbox} \NC \NR |
| 555 |
\NC \type{split_off} \NC top of a \prm {vsplit} \NC \NR |
| 556 |
\NC \type{split_keep} \NC remainder of a \prm {vsplit} \NC \NR |
| 557 |
\NC \type{align_set} \NC alignment cell \NC \NR |
| 558 |
\NC \type{fin_row} \NC alignment row \NC \NR |
| 559 |
\LL |
| 560 |
\stoptabulate |
| 561 |
|
| 562 |
As for all the callbacks that deal with nodes, the return value can be one of |
| 563 |
three things: |
| 564 |
|
| 565 |
\startitemize |
| 566 |
\startitem |
| 567 |
boolean \type {true} signals successful processing |
| 568 |
\stopitem |
| 569 |
\startitem |
| 570 |
\type {<node>} signals that the \quote {head} node should be replaced by the |
| 571 |
returned node |
| 572 |
\stopitem |
| 573 |
\startitem |
| 574 |
boolean \type {false} signals that the \quote {head} node list should be |
| 575 |
ignored and flushed from memory |
| 576 |
\stopitem |
| 577 |
\stopitemize |
| 578 |
|
| 579 |
This callback does not replace any internal code. |
| 580 |
|
| 581 |
\subsection{\cbk {linebreak_filter}} |
| 582 |
|
| 583 |
\topicindex{callbacks+linebreaks} |
| 584 |
|
| 585 |
This callback replaces \LUATEX's line breaking algorithm. |
| 586 |
|
| 587 |
\startfunctioncall |
| 588 |
function(<node> head, <boolean> is_display) |
| 589 |
return <node> newhead |
| 590 |
end |
| 591 |
\stopfunctioncall |
| 592 |
|
| 593 |
The returned node is the head of the list that will be added to the main vertical |
| 594 |
list, the boolean argument is true if this paragraph is interrupted by a |
| 595 |
following math display. |
| 596 |
|
| 597 |
If you return something that is not a \type {<node>}, \LUATEX\ will apply the |
| 598 |
internal linebreak algorithm on the list that starts at \type {<head>}. |
| 599 |
Otherwise, the \type {<node>} you return is supposed to be the head of a list of |
| 600 |
nodes that are all allowed in vertical mode, and at least one of those has to |
| 601 |
represent a hbox. Failure to do so will result in a fatal error. |
| 602 |
|
| 603 |
Setting this callback to \type {false} is possible, but dangerous, because it is |
| 604 |
possible you will end up in an unfixable \quote {deadcycles loop}. |
| 605 |
|
| 606 |
\subsection{\type {append_to_vlist_filter}} |
| 607 |
|
| 608 |
\topicindex{callbacks+contributions} |
| 609 |
|
| 610 |
This callback is called whenever \LUATEX\ adds a box to a vertical list: |
| 611 |
|
| 612 |
\startfunctioncall |
| 613 |
function(<node> box, <string> locationcode, <number prevdepth>, |
| 614 |
<boolean> mirrored) |
| 615 |
return list, prevdepth |
| 616 |
end |
| 617 |
\stopfunctioncall |
| 618 |
|
| 619 |
It is ok to return nothing in which case you also need to flush the box or deal |
| 620 |
with it yourself. The prevdepth is also optional. Locations are \type {box}, |
| 621 |
\type {alignment}, \type {equation}, \type {equation_number} and \type |
| 622 |
{post_linebreak}. You can pass \type {nil} instead of a node. |
| 623 |
|
| 624 |
\subsection{\cbk {post_linebreak_filter}} |
| 625 |
|
| 626 |
\topicindex{callbacks+linebreaks} |
| 627 |
|
| 628 |
This callback is called just after \LUATEX\ has converted a list of nodes into a |
| 629 |
stack of \prm {hbox}es. |
| 630 |
|
| 631 |
\startfunctioncall |
| 632 |
function(<node> head, <string> groupcode) |
| 633 |
return true | false | <node> newhead |
| 634 |
end |
| 635 |
\stopfunctioncall |
| 636 |
|
| 637 |
This callback does not replace any internal code. |
| 638 |
|
| 639 |
\subsection{\cbk {hpack_filter}} |
| 640 |
|
| 641 |
\topicindex{callbacks+packing} |
| 642 |
|
| 643 |
This callback is called when \TEX\ is ready to start boxing some horizontal mode |
| 644 |
material. Math items and line boxes are ignored at the moment. |
| 645 |
|
| 646 |
\startfunctioncall |
| 647 |
function(<node> head, <string> groupcode, <number> size, |
| 648 |
<string> packtype [, <string> direction] [, <node> attributelist]) |
| 649 |
return true | false | <node> newhead |
| 650 |
end |
| 651 |
\stopfunctioncall |
| 652 |
|
| 653 |
The \type {packtype} is either \type {additional} or \type {exactly}. If \type |
| 654 |
{additional}, then the \type {size} is a \type {\hbox spread ...} argument. If |
| 655 |
\type {exactly}, then the \type {size} is a \type {\hbox to ...}. In both cases, |
| 656 |
the number is in scaled points. |
| 657 |
|
| 658 |
The \type {direction} is either one of the three-letter direction specifier |
| 659 |
strings, or \type {nil}. |
| 660 |
|
| 661 |
This callback does not replace any internal code. |
| 662 |
|
| 663 |
\subsection{\cbk {vpack_filter}} |
| 664 |
|
| 665 |
\topicindex{callbacks+packing} |
| 666 |
|
| 667 |
This callback is called when \TEX\ is ready to start boxing some vertical mode |
| 668 |
material. Math displays are ignored at the moment. |
| 669 |
|
| 670 |
This function is very similar to the \cbk {hpack_filter}. Besides the fact |
| 671 |
that it is called at different moments, there is an extra variable that matches |
| 672 |
\TEX's \prm {maxdepth} setting. |
| 673 |
|
| 674 |
\startfunctioncall |
| 675 |
function(<node> head, <string> groupcode, <number> size, <string> packtype, |
| 676 |
<number> maxdepth [, <string> direction] [, <node> attributelist])) |
| 677 |
return true | false | <node> newhead |
| 678 |
end |
| 679 |
\stopfunctioncall |
| 680 |
|
| 681 |
This callback does not replace any internal code. |
| 682 |
|
| 683 |
\subsection{\type {hpack_quality}} |
| 684 |
|
| 685 |
\topicindex{callbacks+packing} |
| 686 |
|
| 687 |
This callback can be used to intercept the overfull messages that can result from |
| 688 |
packing a horizontal list (as happens in the par builder). The function takes a |
| 689 |
few arguments: |
| 690 |
|
| 691 |
\startfunctioncall |
| 692 |
function(<string> incident, <number> detail, <node> head, <number> first, |
| 693 |
<number> last) |
| 694 |
return <node> whatever |
| 695 |
end |
| 696 |
\stopfunctioncall |
| 697 |
|
| 698 |
The incident is one of \type {overfull}, \type {underfull}, \type {loose} or |
| 699 |
\type {tight}. The detail is either the amount of overflow in case of \type |
| 700 |
{overfull}, or the badness otherwise. The head is the list that is constructed |
| 701 |
(when protrusion or expansion is enabled, this is an intermediate list). |
| 702 |
Optionally you can return a node, for instance an overfull rule indicator. That |
| 703 |
node will be appended to the list (just like \TEX's own rule would). |
| 704 |
|
| 705 |
\subsection{\type {vpack_quality}} |
| 706 |
|
| 707 |
\topicindex{callbacks+packing} |
| 708 |
|
| 709 |
This callback can be used to intercept the overfull messages that can result from |
| 710 |
packing a vertical list (as happens in the page builder). The function takes a |
| 711 |
few arguments: |
| 712 |
|
| 713 |
\startfunctioncall |
| 714 |
function(<string> incident, <number> detail, <node> head, <number> first, |
| 715 |
<number> last) |
| 716 |
end |
| 717 |
\stopfunctioncall |
| 718 |
|
| 719 |
The incident is one of \type {overfull}, \type {underfull}, \type {loose} or |
| 720 |
\type {tight}. The detail is either the amount of overflow in case of \type |
| 721 |
{overfull}, or the badness otherwise. The head is the list that is constructed. |
| 722 |
|
| 723 |
\subsection{\cbk {process_rule}} |
| 724 |
|
| 725 |
\topicindex{callbacks+rules} |
| 726 |
|
| 727 |
This is an experimental callback. It can be used with rules of subtype~4 |
| 728 |
(user). The callback gets three arguments: the node, the width and the |
| 729 |
height. The callback can use \type {pdf.print} to write code to the \PDF\ |
| 730 |
file but beware of not messing up the final result. No checking is done. |
| 731 |
|
| 732 |
\subsection{\type {pre_output_filter}} |
| 733 |
|
| 734 |
\topicindex{callbacks+output} |
| 735 |
|
| 736 |
This callback is called when \TEX\ is ready to start boxing the box 255 for \prm |
| 737 |
{output}. |
| 738 |
|
| 739 |
\startfunctioncall |
| 740 |
function(<node> head, <string> groupcode, <number> size, <string> packtype, |
| 741 |
<number> maxdepth [, <string> direction]) |
| 742 |
return true | false | <node> newhead |
| 743 |
end |
| 744 |
\stopfunctioncall |
| 745 |
|
| 746 |
This callback does not replace any internal code. |
| 747 |
|
| 748 |
\subsection{\cbk {hyphenate}} |
| 749 |
|
| 750 |
\topicindex{callbacks+hyphenation} |
| 751 |
|
| 752 |
\startfunctioncall |
| 753 |
function(<node> head, <node> tail) |
| 754 |
end |
| 755 |
\stopfunctioncall |
| 756 |
|
| 757 |
No return values. This callback has to insert discretionary nodes in the node |
| 758 |
list it receives. |
| 759 |
|
| 760 |
Setting this callback to \type {false} will prevent the internal discretionary |
| 761 |
insertion pass. |
| 762 |
|
| 763 |
\subsection{\cbk {ligaturing}} |
| 764 |
|
| 765 |
\topicindex{callbacks+ligature building} |
| 766 |
|
| 767 |
\startfunctioncall |
| 768 |
function(<node> head, <node> tail) |
| 769 |
end |
| 770 |
\stopfunctioncall |
| 771 |
|
| 772 |
No return values. This callback has to apply ligaturing to the node list it |
| 773 |
receives. |
| 774 |
|
| 775 |
You don't have to worry about return values because the \type {head} node that is |
| 776 |
passed on to the callback is guaranteed not to be a glyph_node (if need be, a |
| 777 |
temporary node will be prepended), and therefore it cannot be affected by the |
| 778 |
mutations that take place. After the callback, the internal value of the \quote |
| 779 |
{tail of the list} will be recalculated. |
| 780 |
|
| 781 |
The \type {next} of \type {head} is guaranteed to be non-nil. |
| 782 |
|
| 783 |
The \type {next} of \type {tail} is guaranteed to be nil, and therefore the |
| 784 |
second callback argument can often be ignored. It is provided for orthogonality, |
| 785 |
and because it can sometimes be handy when special processing has to take place. |
| 786 |
|
| 787 |
Setting this callback to \type {false} will prevent the internal ligature |
| 788 |
creation pass. |
| 789 |
|
| 790 |
You must not ruin the node list. For instance, the head normally is a local par node, |
| 791 |
and the tail a glue. Messing too much can push \LUATEX\ into panic mode. |
| 792 |
|
| 793 |
\subsection{\cbk {kerning}} |
| 794 |
|
| 795 |
\topicindex{callbacks+kerning} |
| 796 |
|
| 797 |
\startfunctioncall |
| 798 |
function(<node> head, <node> tail) |
| 799 |
end |
| 800 |
\stopfunctioncall |
| 801 |
|
| 802 |
No return values. This callback has to apply kerning between the nodes in the |
| 803 |
node list it receives. See \cbk {ligaturing} for calling conventions. |
| 804 |
|
| 805 |
Setting this callback to \type {false} will prevent the internal kern insertion |
| 806 |
pass. |
| 807 |
|
| 808 |
You must not ruin the node list. For instance, the head normally is a local par node, |
| 809 |
and the tail a glue. Messing too much can push \LUATEX\ into panic mode. |
| 810 |
|
| 811 |
\subsection{\type {insert_local_par}} |
| 812 |
|
| 813 |
Each paragraph starts with a local par node that keeps track of for instance |
| 814 |
the direction. You can hook a callback into the creator: |
| 815 |
|
| 816 |
\startfunctioncall |
| 817 |
function(<node> local_par, <string> location) |
| 818 |
end |
| 819 |
\stopfunctioncall |
| 820 |
|
| 821 |
There is no return value and you should make sure that the node stays valid |
| 822 |
as otherwise \TEX\ can get confused. |
| 823 |
|
| 824 |
\subsection{\cbk {mlist_to_hlist}} |
| 825 |
|
| 826 |
\topicindex{callbacks+math} |
| 827 |
|
| 828 |
This callback replaces \LUATEX's math list to node list conversion algorithm. |
| 829 |
|
| 830 |
\startfunctioncall |
| 831 |
function(<node> head, <string> display_type, <boolean> need_penalties) |
| 832 |
return <node> newhead |
| 833 |
end |
| 834 |
\stopfunctioncall |
| 835 |
|
| 836 |
The returned node is the head of the list that will be added to the vertical or |
| 837 |
horizontal list, the string argument is either \quote {text} or \quote {display} |
| 838 |
depending on the current math mode, the boolean argument is \type {true} if |
| 839 |
penalties have to be inserted in this list, \type {false} otherwise. |
| 840 |
|
| 841 |
Setting this callback to \type {false} is bad, it will almost certainly result in |
| 842 |
an endless loop. |
| 843 |
|
| 844 |
\stopsection |
| 845 |
|
| 846 |
\startsection[title={Information reporting callbacks}][library=callback] |
| 847 |
|
| 848 |
\subsection{\cbk {pre_dump}} |
| 849 |
|
| 850 |
\topicindex{callbacks+dump} |
| 851 |
|
| 852 |
\startfunctioncall |
| 853 |
function() |
| 854 |
end |
| 855 |
\stopfunctioncall |
| 856 |
|
| 857 |
This function is called just before dumping to a format file starts. It does not |
| 858 |
replace any code and there are neither arguments nor return values. |
| 859 |
|
| 860 |
\subsection{\cbk {start_run}} |
| 861 |
|
| 862 |
\topicindex{callbacks+job run} |
| 863 |
|
| 864 |
\startfunctioncall |
| 865 |
function() |
| 866 |
end |
| 867 |
\stopfunctioncall |
| 868 |
|
| 869 |
This callback replaces the code that prints \LUATEX's banner. Note that for |
| 870 |
successful use, this callback has to be set in the \LUA\ initialization script, |
| 871 |
otherwise it will be seen only after the run has already started. |
| 872 |
|
| 873 |
\subsection{\cbk {stop_run}} |
| 874 |
|
| 875 |
\topicindex{callbacks+job run} |
| 876 |
|
| 877 |
\startfunctioncall |
| 878 |
function() |
| 879 |
end |
| 880 |
\stopfunctioncall |
| 881 |
|
| 882 |
This callback replaces the code that prints \LUATEX's statistics and \quote |
| 883 |
{output written to} messages. The engine can still do housekeeping and therefore |
| 884 |
you should not rely on this hook for postprocessing the \PDF\ or log file. |
| 885 |
|
| 886 |
\subsection{\cbk {start_page_number}} |
| 887 |
|
| 888 |
\topicindex{callbacks+pages} |
| 889 |
|
| 890 |
\startfunctioncall |
| 891 |
function() |
| 892 |
end |
| 893 |
\stopfunctioncall |
| 894 |
|
| 895 |
Replaces the code that prints the \type {[} and the page number at the begin of |
| 896 |
\prm {shipout}. This callback will also override the printing of box information |
| 897 |
that normally takes place when \prm {tracingoutput} is positive. |
| 898 |
|
| 899 |
\subsection{\cbk {stop_page_number}} |
| 900 |
|
| 901 |
\topicindex{callbacks+pages} |
| 902 |
|
| 903 |
\startfunctioncall |
| 904 |
function() |
| 905 |
end |
| 906 |
\stopfunctioncall |
| 907 |
|
| 908 |
Replaces the code that prints the \type {]} at the end of \prm {shipout}. |
| 909 |
|
| 910 |
\subsection{\cbk {show_error_hook}} |
| 911 |
|
| 912 |
\topicindex{callbacks+errors} |
| 913 |
|
| 914 |
\startfunctioncall |
| 915 |
function() |
| 916 |
end |
| 917 |
\stopfunctioncall |
| 918 |
|
| 919 |
This callback is run from inside the \TEX\ error function, and the idea is to |
| 920 |
allow you to do some extra reporting on top of what \TEX\ already does (none of |
| 921 |
the normal actions are removed). You may find some of the values in the \type |
| 922 |
{status} table useful. This callback does not replace any internal code. |
| 923 |
|
| 924 |
\subsection{\cbk {show_error_message}} |
| 925 |
|
| 926 |
\topicindex{callbacks+errors} |
| 927 |
|
| 928 |
\startfunctioncall |
| 929 |
function() |
| 930 |
end |
| 931 |
\stopfunctioncall |
| 932 |
|
| 933 |
This callback replaces the code that prints the error message. The usual |
| 934 |
interaction after the message is not affected. |
| 935 |
|
| 936 |
\subsection{\cbk {show_ignored_error_message}} |
| 937 |
|
| 938 |
\topicindex{callbacks+errors} |
| 939 |
|
| 940 |
\startfunctioncall |
| 941 |
function() |
| 942 |
end |
| 943 |
\stopfunctioncall |
| 944 |
|
| 945 |
This callback replaces the code that prints the error message |
| 946 |
when \prm {ignoreprimitiveerror} is enabled. |
| 947 |
As before, the usual |
| 948 |
interaction after the message is not affected. |
| 949 |
|
| 950 |
|
| 951 |
\subsection{\cbk {show_lua_error_hook}} |
| 952 |
|
| 953 |
\topicindex{callbacks+errors} |
| 954 |
|
| 955 |
\startfunctioncall |
| 956 |
function() |
| 957 |
end |
| 958 |
\stopfunctioncall |
| 959 |
|
| 960 |
This callback replaces the code that prints the extra \LUA\ error message. |
| 961 |
|
| 962 |
\subsection{\cbk {start_file}} |
| 963 |
|
| 964 |
\topicindex{callbacks+files} |
| 965 |
|
| 966 |
\startfunctioncall |
| 967 |
function(category,filename) |
| 968 |
end |
| 969 |
\stopfunctioncall |
| 970 |
|
| 971 |
This callback replaces the code that prints \LUATEX's when a file is opened like |
| 972 |
\type {(filename} for regular files. The category is a number: |
| 973 |
|
| 974 |
\starttabulate[|c|l|] |
| 975 |
\DB value \BC meaning \NC \NR |
| 976 |
\TB |
| 977 |
\NC 1 \NC a normal data file, like a \TEX\ source \NC \NR |
| 978 |
\NC 2 \NC a font map coupling font names to resources \NC \NR |
| 979 |
\NC 3 \NC an image file (\type {png}, \type {pdf}, etc) \NC \NR |
| 980 |
\NC 4 \NC an embedded font subset \NC \NR |
| 981 |
\NC 5 \NC a fully embedded font \NC \NR |
| 982 |
\LL |
| 983 |
\stoptabulate |
| 984 |
|
| 985 |
\subsection{\cbk {stop_file}} |
| 986 |
|
| 987 |
\topicindex{callbacks+files} |
| 988 |
|
| 989 |
\startfunctioncall |
| 990 |
function(category) |
| 991 |
end |
| 992 |
\stopfunctioncall |
| 993 |
|
| 994 |
This callback replaces the code that prints \LUATEX's when a file is closed like |
| 995 |
the \type {)} for regular files. |
| 996 |
|
| 997 |
\subsection{\cbk {call_edit}} |
| 998 |
|
| 999 |
\topicindex{callbacks+editing} |
| 1000 |
|
| 1001 |
\startfunctioncall |
| 1002 |
function(filename,linenumber) |
| 1003 |
end |
| 1004 |
\stopfunctioncall |
| 1005 |
|
| 1006 |
This callback replaces the call to an external editor when \quote{E} is pressed |
| 1007 |
in reply to an error message. Processing will end immediately after the callback |
| 1008 |
returns control to the main program. |
| 1009 |
|
| 1010 |
\subsection{\cbk {finish_synctex}} |
| 1011 |
|
| 1012 |
\topicindex{callbacks+synctex} |
| 1013 |
|
| 1014 |
This callback can be used to wrap up alternative synctex methods. It kicks in |
| 1015 |
after the normal synctex finalizer (that happens to remove the synctex files |
| 1016 |
after a run when native synctex is not enabled). |
| 1017 |
|
| 1018 |
\subsection{\cbk {wrapup_run}} |
| 1019 |
|
| 1020 |
\topicindex{callbacks+wrapping up} |
| 1021 |
|
| 1022 |
This callback is called after the \PDF\ and log files are closed. Use it at your own |
| 1023 |
risk. |
| 1024 |
|
| 1025 |
\stopsection |
| 1026 |
|
| 1027 |
\startsection[title={\PDF\ related callbacks}][library=callback] |
| 1028 |
|
| 1029 |
\subsection{\cbk {finish_pdffile}} |
| 1030 |
|
| 1031 |
\topicindex{callbacks+\PDF\ file} |
| 1032 |
|
| 1033 |
\startfunctioncall |
| 1034 |
function() |
| 1035 |
end |
| 1036 |
\stopfunctioncall |
| 1037 |
|
| 1038 |
This callback is called when all document pages are already written to the \PDF\ |
| 1039 |
file and \LUATEX\ is about to finalize the output document structure. Its |
| 1040 |
intended use is final update of \PDF\ dictionaries such as \type {/Catalog} or |
| 1041 |
\type {/Info}. The callback does not replace any code. There are neither |
| 1042 |
arguments nor return values. |
| 1043 |
|
| 1044 |
\subsection{\cbk {finish_pdfpage}} |
| 1045 |
|
| 1046 |
\topicindex{callbacks+\PDF\ file} |
| 1047 |
|
| 1048 |
\startfunctioncall |
| 1049 |
function(shippingout) |
| 1050 |
end |
| 1051 |
\stopfunctioncall |
| 1052 |
|
| 1053 |
This callback is called after the \PDF\ page stream has been assembled and before |
| 1054 |
the page object gets finalized. |
| 1055 |
|
| 1056 |
\subsection{\cbk {page_order_index}} |
| 1057 |
|
| 1058 |
\topicindex{callbacks+\PDF\ file} |
| 1059 |
|
| 1060 |
This is one that experts can use to juggle the page tree, a data structure |
| 1061 |
that determines the order in a \PDF\ file: |
| 1062 |
|
| 1063 |
\startfunctioncall |
| 1064 |
function(pagenumber) |
| 1065 |
return pagenumber |
| 1066 |
end |
| 1067 |
\stopfunctioncall |
| 1068 |
|
| 1069 |
Say that we have 12 pages, then we can do this: |
| 1070 |
|
| 1071 |
\starttyping |
| 1072 |
callback.register("page_order_index",function(page) |
| 1073 |
if page == 1 then return 12 |
| 1074 |
elseif page == 2 then return 11 |
| 1075 |
elseif page == 11 then return 2 |
| 1076 |
elseif page == 12 then return 1 |
| 1077 |
else return page |
| 1078 |
end |
| 1079 |
end) |
| 1080 |
\stoptyping |
| 1081 |
|
| 1082 |
This will swap the first two and last two pages. You need to know the number of |
| 1083 |
pages which is a side effect of the implementation. When you mess things up |
| 1084 |
\unknown\ don't complain. |
| 1085 |
|
| 1086 |
\subsection{\cbk {process_pdf_image_content}} |
| 1087 |
|
| 1088 |
\topicindex{callbacks+image content} |
| 1089 |
|
| 1090 |
When a page from a \PDF\ file is embedded its page stream as well as related |
| 1091 |
objects are copied to the target file. However, it can be that the page stream |
| 1092 |
has operators that assume additional resources, for instance marked text. You can |
| 1093 |
decide to filter that for which \LUATEX\ provides a callback. Here is a simple |
| 1094 |
demonstration of use: |
| 1095 |
|
| 1096 |
\starttyping |
| 1097 |
pdf.setrecompress(1) |
| 1098 |
|
| 1099 |
callback.register("process_pdf_image_content",function(s) |
| 1100 |
print(s) |
| 1101 |
return s |
| 1102 |
end) |
| 1103 |
\stoptyping |
| 1104 |
|
| 1105 |
You need to explicitly enable recompression because otherwise the content stream |
| 1106 |
gets just passed on in its original compressed form. |
| 1107 |
|
| 1108 |
\stopsection |
| 1109 |
|
| 1110 |
\startsection[title={Font-related callbacks}][library=callback] |
| 1111 |
|
| 1112 |
\subsection{\cbk {define_font}} |
| 1113 |
|
| 1114 |
\topicindex{callbacks+fonts} |
| 1115 |
|
| 1116 |
\startfunctioncall |
| 1117 |
function(<string> name, <number> size, <number> id) |
| 1118 |
return <table> font | <number> id |
| 1119 |
end |
| 1120 |
\stopfunctioncall |
| 1121 |
|
| 1122 |
The string \type {name} is the filename part of the font specification, as given |
| 1123 |
by the user. |
| 1124 |
|
| 1125 |
The number \type {size} is a bit special: |
| 1126 |
|
| 1127 |
\startitemize[packed] |
| 1128 |
\startitem |
| 1129 |
If it is positive, it specifies an \quote{at size} in scaled points. |
| 1130 |
\stopitem |
| 1131 |
\startitem |
| 1132 |
If it is negative, its absolute value represents a \quote {scaled} setting |
| 1133 |
relative to the designsize of the font. |
| 1134 |
\stopitem |
| 1135 |
\stopitemize |
| 1136 |
|
| 1137 |
The \type {id} is the internal number assigned to the font. |
| 1138 |
|
| 1139 |
The internal structure of the \type {font} table that is to be returned is |
| 1140 |
explained in \in {chapter} [fonts]. That table is saved internally, so you can |
| 1141 |
put extra fields in the table for your later \LUA\ code to use. In alternative, |
| 1142 |
\type {retval} can be a previously defined fontid. This is useful if a previous |
| 1143 |
definition can be reused instead of creating a whole new font structure. |
| 1144 |
|
| 1145 |
Setting this callback to \type {false} is pointless as it will prevent font |
| 1146 |
loading completely but will nevertheless generate errors. |
| 1147 |
|
| 1148 |
\subsection{\cbk {glyph_not_found} and \cbk {glyph_info}} |
| 1149 |
|
| 1150 |
\topicindex{callbacks+fonts} |
| 1151 |
|
| 1152 |
The \type {glyph_not_found} callback, when set, kicks in when the backend cannot |
| 1153 |
insert a glyph. When no callback is defined a message is written to the log. |
| 1154 |
|
| 1155 |
\startfunctioncall |
| 1156 |
function(<number> id, <number> char) |
| 1157 |
-- do something with font id and char code |
| 1158 |
end |
| 1159 |
\stopfunctioncall |
| 1160 |
|
| 1161 |
The \type {glyph_info} callback can be set to report a useful representation of a |
| 1162 |
glyph. |
| 1163 |
|
| 1164 |
\startfunctioncall |
| 1165 |
function(<node> g) |
| 1166 |
-- return a string or nil |
| 1167 |
end |
| 1168 |
\stopfunctioncall |
| 1169 |
|
| 1170 |
When \type {nil} is returned the character code is printed, otherwise the |
| 1171 |
returned string is used. By default the \UTF\ representation is shown which is |
| 1172 |
not always that useful, especially when there is no real representation. Keep in |
| 1173 |
mind that setting this callback can change the log in an incompatible way. |
| 1174 |
|
| 1175 |
\subsection{\cbk {provide_charproc_data}} |
| 1176 |
|
| 1177 |
\topicindex{callbacks+fonts} |
| 1178 |
|
| 1179 |
The \type {provide_charproc_data} callback is triggered when the backend is |
| 1180 |
writing out a user-defined Type~3 font: |
| 1181 |
|
| 1182 |
\startfunctioncall |
| 1183 |
function(<number> mode, <number> id, <number> char) |
| 1184 |
if mode == 1 then |
| 1185 |
-- preroll |
| 1186 |
return |
| 1187 |
elseif mode == 2 then |
| 1188 |
-- write out the glyph contents |
| 1189 |
return <number> stream, <number> width |
| 1190 |
elseif mode == 3 then |
| 1191 |
-- the overall font scale |
| 1192 |
return <number> scale |
| 1193 |
end |
| 1194 |
end |
| 1195 |
\stopfunctioncall |
| 1196 |
|
| 1197 |
To make a user-defined Type~3 font, you need to set \type {encodingbytes = 0} |
| 1198 |
and \type {psname = "none"} at the top-level when defining the font. From the |
| 1199 |
\type {glyph_not_found} callback, you should return the overall font scale |
| 1200 |
(conventionally 0.001) in mode~3, and the index of a \PDF\ stream (where the |
| 1201 |
first operator is either \type {d0} or \type {d1}) and the width of the glyph |
| 1202 |
(in sp's) in mode~2. You can generally ignore mode~1. |
| 1203 |
|
| 1204 |
|
| 1205 |
\stopsection |
| 1206 |
|
| 1207 |
\stopchapter |
| 1208 |
|
| 1209 |
\stopcomponent |