A basic PDF writer in Tcl - Index of

A basic PDF writer in Tcl 

Lars Hellström 

February 3, 2005 

Abstract 

This file contains some basic routines that allow a Tcl script to write 

PDF files. 

Contents 

1 Usage 2 

1.1 File structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

1.2 Direct objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.3 Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

1.4 Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

1.5 Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

1.6 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 

1.7 Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

2 PDF files and objects 11 

2.1 Building objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

2.2 File structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

2.3 Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

3 Contents and resources 23 

3.1 Resources representation . . . . . . . . . . . . . . . . . . . . . . . . 24 

3.2 Formatting content . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

3.3 Hello again, World . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

4 Document pages 32 

4.1 The tree of pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

4.2 Lengths and rectangles . . . . . . . . . . . . . . . . . . . . . . . . . 38 

4.3 Paper sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

4.4 A multi-page example . . . . . . . . . . . . . . . . . . . . . . . . . 44 

5 Document outline 45 

5.1 Low-level stuff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

5.2 An outline of headings . . . . . . . . . . . . . . . . . . . . . . . . . 49 

5.3 An outline example . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

1

1 Usage 

The aim of the basic pdf package is to simplify the generation of well-formed 

PDF files. Programmers who intend to make use of it should first familiarize 

themselves with the actual PDF format specification, as it is not the aim of the 

basic pdf package 1 to substitute anything else for the raw expressive power of the 

PDF format. Newcomers should find [2] (version 1.5 of the PDF specification) a 

good reference and introduction to the details of the PDF format. 

1.1 File structure 

A PDF file is basically a (sometimes huge) data structure, consisting of a myriad 

of objects (which are quite comparable to Tcl Objs, i.e., to Tcl values, although 

PDF objects have types). An object can be direct (encoded at the position it is 

used) or indirect (encoded somewhere else in the file and referenced by number). 

The absolute positions in the file of all indirect objects have to be given in a crossreference 

table at the end of the file, and getting this right is the first obstacle to 

generating a well-formed PDF file. 

pdf::put_obj (proc) The pdf package provides a model where indirect object can be assigned arbi- 

pdf::obj_ref (proc) trary strings as labels. Actual object numbers are allocated as needed and positions 

needed for the cross-reference table are recorded. The two basic commands 

for deailing with indirect objects are 

pdf::rewrite_pdf (proc) 

pdf::close_pdf (proc) 

pdf::obj_ref {file} {reference label} 

pdf::put_obj {file} {reference label} {object} 

put_obj writes a PDF object to a file (thus making it available as indirect object 

in that file), whereas obj_ref returns PDF code for a reference to an indirect 

object. obj_ref may occur before as well as after the put_obj for the object it 

refers to. 

Open PDF files are referenced via the usual identifier of the Tcl channel. To 

open a file for the purpose of creating a new PDF document, one uses 

pdf::rewrite_pdf {file name} 〈options〉 

which returns the identifier of the new file. The 〈options〉 is zero or more of 

-permissions {integer} 

-header {string} 

The permissions are the default permissions for the file in question. If this is not 

specified, then no such value is specified to open, The header is a string that will 

be put first in the file (as header). (The default header string declares the PDF 

version to be 1.3 [1], which is a good compromise between supporting old PDF 

consumers and providing PDF features.) 

The command used to close a PDF file should be 

1 But is a likely aim of add-on packages. 

2

pdf::close_pdf {file} {catalog label} {key} {value} ∗ 

since this is what will output the cross-reference table and trailer to this file, 

before it is closed. {catalog label} is the label of the /Catalog object for the 

document. The {key} {value} arguments are PDF objects which will be inserted 

into the file’s trailer dictionary. Each {key} must be a name object, and each 

{value} the corresponding value. (The /Size and /Root entries in this dictionary 

are generated automatically, so it is perfectly OK to only give two arguments to 

close_pdf.) 

It is part of the PDF specification how to make updates to an existing PDF 

document, but the pdf package currently offers no support for that. Should such 

support be added in the future, then one would use some other command than 

rewrite_pdf to open the file for modifications. 

1.2 Direct objects 

The pdf package commands that return {object}s (i.e., PDF code for an object) 

are 

pdf::boolean_obj {boolean} 

pdf::int_obj {integer} 

pdf::real_obj {value} {precision} ? 

pdf::string_obj {byte string} 

pdf::hexstring_obj {byte string} 

pdf::text_obj {string} 

pdf::name_obj {string} 

pdf::array_obj {object} ∗ 

pdf::dict_obj {key object} {value object} ∗ 

pdf::null_obj 

pdf::date_obj {clock value} {zonemode} ? 

pdf::length_obj {value} {unit} {precision} ? 

pdf::rect_obj {rectangle} 

pdf::int_rect_obj {rectangle} 

pdf::resource_dict_obj {array-name} 


All but the last of these return direct objects, whereas obj_ref as explained above 

returns a reference to an indirect object. In addition to using the above commands, 

an {object} can also be the explicit PDF code for an object; this is most common 

with name objects. 

pdf::int_obj (proc) The int_obj command formats a Tcl integer as a PDF object. The real_obj 

pdf::real_obj (proc) command similarly formats a Tcl double. The {precision} is the number of decimals 

that will be included in the PDF code. When omitted, the current value of 

pdf::precision (var.) the pdf::precision variable is used instead. This variable is by default set to 3. 

pdf::string_obj (proc) 

pdf::hexstring_obj (proc) 

The string_obj command takes a {byte string} (a string consisting of char- 

acters in the range \x00–\xFF) and returns the corresponding PDF string object, 

delimited by parentheses. The hexstring_obj command does the same thing, but 

3

makes use of hexstring (-delimited sequence of hexadecimal digits) encoding 

instead. 

Text objects and date objects are syntactically PDF string objects, but they 

are used in special contexts and are there given an interpretation that is slightly 

different from that of ordinary PDF strings. In particular, the character set for 

text object is always the full Unicode, whereas the encodings of ordinary PDF 

pdf::text_obj (proc) strings depend heavily on the context. The text_obj command takes an arbitrary 

pdf::date_obj (proc) Tcl string as argument and returns the corresponding text object. The date_obj 

command takes a {clock value} (as used by the clock command) and returns the 

corresponding PDF date object. The optional {zonemode} argument specifies how 

time zones are encoded in the object. An empty string (the default) or none means 

that no time zone specification should be included. utc or gmt means encode the 

time as a UTC. local or full causes the offset from local time to UTC to be 

computed and included in the result. 

pdf::boolean_obj (proc) The boolean_obj and null_obj commands return boolean and null objects, 

pdf::null_obj (proc) respectively. They’re not that frequently used. The name_obj command returns 

pdf::name_obj (proc) the name object formed from a given string. This is most often used with variable 

strings, such as for example font names, that are not known when the program is 

written. 

pdf::array_obj (proc) The array_obj command returns the array object (comparable to a Tcl list) 

pdf::dict_obj (proc) that is formed from the given sequence of objects. The dict_obj command returns 

the dictionary object that is formed from the given sequence of keys and values. 

The {key object}s must all be name objects. 

1.3 Streams 

pdf::begin_stream (proc) Much of the data in a PDF file is not stored in the above kind of objects, but 

pdf::end_stream (proc) in a special kind of indirect object called a stream. These are created using the 

commands 

pdf::begin_stream {file} {label} {key} {value} ∗ 

pdf::end_stream {file} 

The {label} is the one which will be used with obj_ref to refer to the stream 

object. Every stream comes with a stream dictionary that contains information 

about how the stream data should be decoded, e.g. decompressed. The {key} 

{value} arguments of begin_stream are placed in this dictionary; the /Length 

entry for the stream is however automatically generated. 

Data written to a PDF file, using for example puts, between a begin_stream 

and the matching end_stream will go into that stream. Such data need in general 

not conform to the ordinary PDF syntax, but can be pretty much anything. It 

will depend on where in the document the stream object is referenced whether the 

data is correct or not. Note that files opened using rewrite_pdf are configured to 

be binary. It is an error to try to begin a new stream before ending a previous one, 

but it is possible to use put_obj even inside a stream; the object is then cached 

internally and written to file after the stream has been ended. 

4

A special, but very common type of stream is the contents stream; this is for 

example used for all the text and graphics on actual document pages. Contents 

streams are created using the commands 

pdf::begin_contents {resources-array} {file} {label} {key} {value} ∗ 

pdf::end_contents {resources-array} {file} 

pdf::resource_dict_obj 

The special thing about contents streams is that they are always associated with 

some resources dictionary, which maps names used in the contents stream to PDF 

objects outside it. The extra feature provided by the . . . _contents commands as 

compared to the . . . _stream commands is a mechanism for keeping track of the 

current set or resources and which permits extending this set when needed. 

When not inside a contents stream, data for resources dictionaries are 

(proc) kept in a Tcl array. The data can be converted to a PDF object using the 

pdf::begin_contents 

resource_dict_obj command, which takes the name of an array as argument. 

begin_contents similarly takes the name of an array as argument, and copies the 

(proc) data from this array to an internal (file-specific) storage. If the {resources-array} 

argument is empty then the internally stored resources dictionary starts out empty 

pdf::end_contents (proc) 

pdf::name_resource (proc) 

as well. end_contents conversely copies the resource dictionary entries from in- 

ternal storage to the specified {resources-array} (note: it does not clear that 

array first). If several contents streams are to share the same resources array, 

then one should pass the array filled in by the previous end_contents to the next 

begin_content. 

Between begin_contents and the matching end_contents, one can use the 

name_resource command to get a name by which one can refer to a particular 

object from within this contents stream. The syntax is 

pdf::name_resource {variable} {file} {type} {object} {suggested 

name} ? 

where the {variable} is the name of a variable that will be set to the wanted name 

object. {type} is the resource type, and should be one of ColorSpace, XObject, 

ExtGState, Font, Pattern, Properties, and Shading. {object} is the actual 

object (direct or indirect) and {file} is the PDF file. 

The optional {suggested name} argument can be used to force use of a particular 

name; if this is not supplied, then an available name is automatically generated. 

(Forcing a particular name may be useful for backwards compatibility, as there are 

some known bugs in PDF readers which required using the same name in several 

different resource dictionaries.) Multiple calls for the same resource will reuse the 

same name, unless a suggested name is provided. The command returns 1 if a 

new name was added to the resource dictionary and 0 if an old name could be 

reused. An error is thrown if the {suggested name} is already assigned to some 

other object. 

The PDF specification also defines ProcSet resources, but you need not worry 

about those. By default (i.e., if the ProcSet entry is not set), resource_dict_obj 

inserts an entry for the full set of procsets. Most PDF consumers never bothered 

about the procsets anyway. 

5

pdf::shipout (proc) 

1.4 Pages 

PDF requires that all pages are arranged in a data structure called the pages tree. 

The pdf package has commands that can take care of building this tree for you; 

if you use them, then you only have to worry about generating the pages in the 

order you want them to appear in the document. 

To finish a document page, one uses the command 

pdf::shipout {file} {label} {key} {object} + 

{file} here is the PDF file identifier and {label} is the reference label you want to 

assign to the page object. (Links in a PDF file require a reference to the target 

page, so it is likely that you will want to obj_ref the page.) The {key} and 

{object} arguments are attributes for the page object (keys and values for the 

dicitionary). This should not include the /Type and /Parent attributes, which 

are inserted automatically. An example: 

pdf::shipout $F "Page $n"\ 

/Contents [pdf::obj_ref $F "Page $n contents"]\ 

/Resources [pdf::obj_ref $F "Page $n resources"] 

Before the first shipout, one must initialise the pages tree using the 

pdf::begin_pages (proc) begin_pages command, and after the last shipout, one must use end_pages 

pdf::end_pages (proc) to complete the pages tree. 

pdf::begin_pages {file} {label prefix} {option} {value} ∗ 

pdf::end_pages {file} {option} {value} ∗ 

{option}s that begin with a / are interpreted as names of entries to insert into the 

root node of the pages tree; in this case the {value} must be an object. This is 

useful if some attribute (e.g. page size) is the same for all pages, as one can then 

specify it once at the root and let it be inherited by all the pages. 

Every node in the tree is given a reference label, so to avoid clashes with other 

objects, all /Pages nodes (but not the page nodes) are given labels that begins with 

the {label prefix} specified at begin_pages. The end_pages command returns the 

label that was given to the root node. 

The pages tree constructed by end_pages is balanced and of minimal size with 

respect to its arity (number of kids per parent). The default arity is 5, but that 

can be overridden using the -arity {option} of begin_pages, in which case the 

corresponding {value} is the new arity. 

1.5 Outline 

A similar mechanism exists for building the outline tree. Construction of this is 

pdf::begin_outline (proc) begun at begin_outline and completed at end_outline. To begin_outline one 

pdf::end_outline (proc) must supply a string that will be used as prefix for all labels of nodes in the tree, 

and end_outline will return the label of the outline tree root node. 

pdf::begin_outline {file} {prefix} 

pdf::end_outline {file} 

6

pdf::outline_heading New items can be added to the outline using the outline_heading command. 

(proc) This has the syntax 

pdf::outline_heading {file} {level} {title} {option} {value} ∗ 

where {file} is the identifier of the PDF file, {level} is the nominal level of this 

item, and {title} is the title. The title is an ordinary Tcl string and there is no 

restriction on which characters it may contain. 

An {option} {value} is either a pair of PDF objects, where the first is a name 

object, or 

-open {boolean} 

The PDF objects will be placed in the dictionary object for the new item. These 

are what one should use to specify a destination or equivalent for the outline item. 

The -open option controls whether this item will be open by default, i.e., if its 

subitems (if there will be any) should be shown. It defaults to false (closed). 

The {level} is relative, and can be an arbitrary string. The way it is used 

is that if {level} is greater than the current level, then a new level is begun. 

Else if {level} is greater than the previous level, the item is a sibling of the last 

item and the current level is updated. Otherwise the current level is ended and 

the issue is reexamined. This dynamically adapts to the set of {level}s actually 

used in a document, even if these are not consecutive. It also gracefully copes 

with inconsistencies such as forgetting some heading level at the beginning of a 

document. 

It is possible to create rather obnoxious outlines by hardwiring particular zoom 

factors into the outline. It is usually best to specify no more than the destination 

page and vertical position, as shown in this example: 

pdf::outline_heading $F 1 "Introduction" /Dest [ 

pdf::array_obj [pdf::obj_ref $F "Page 1"] /XYZ null\ 

[pdf::real_obj $ypos] null 

] 

There are also four lower level commands available, which may be useful if for 

some reason some information needed for an entry is not available until the end of 

pdf::outline_node_set it (e.g. the position of that end). The outline_node_set command can be used 

(proc) to set entries in the dictionary of the current outline item. Its syntax is 

pdf::outline_item (proc) 

pdf::outline_begingroup 

(proc) 

pdf::outline_endgroup 

(proc) 

pdf::outline_node_set {file} {option} {value} ∗ 

The outline_item command creates a new item in the current level of the outline. 

Its syntax is 

pdf::outline_item {file} {title} {option} {value} ∗ 

These options and values are handled as for outline_heading. 

For beginning and ending lower level groups of items, there are the commands 

pdf::outline_begingroup {file} {option} {value} ∗ 

pdf::outline_endgroup {file} {option} {value} ∗ 

7

pdf::printf (proc) 

pdf::sprintf (proc) 

The {option} and {value} arguments here affect the parent of the new group of 

items. Note that between an outline_begingroup and the first outline_item 

after it, there is no current item in the outline. 

1.6 Contents 

Once inside a contents stream, PDF is fairly similar to Postscript (although still 

more strict and structured) with sequences of operands followed by some operator. 

To simplify writing such code, there is a command printf which offers format- 

style formatting of data written to the file. The syntax is 

pdf::printf {file} {format list} {data} ∗ 

and as with format, each conversion specifier in the {format list} consumes one 

or several {data} items. (It is probably a good idea to limit the length of {format 

list}s to small enough chunks that you can instantly see what each {data} item is 

used for.) There is also a command sprintf with syntax 

pdf::sprintf {format list} {data} ∗ 

that returns the formatted code rather than writing it to a file. 

The {format list}s are lists where every element is either explcit PDF code 

(typically an operator) or a conversion specifier. As with format, the conversion 

specifiers are recognised by the fact that their first character is a ‘%’. The contributions 

to the formatted PDF code from separate list elements will be separated 

by whitespace as necessary. 

The second character of a conversion specifier determines the type of conversion 

to carry out. The basic conversions are 

b Boolean, to be formatted by boolean_obj. 

i Integer, to be formatted by int_obj. 

l Length, to be formatted by length_obj. This consumes two {data} arguments: 

one for the value and one for the unit. 

n Data is a string, to be formatted by name_obj. 

o Already formatted PDF object. 

r Real number, to be formatted by real_obj (with default precision according 

to the precision variable). 

s PDF string, to be formatted by string_obj. 

In addition, the corresponding upper case letters select the same formatting, but 

the (first) {data} argument is interpreted as a list of values to format in the specified 

way. The character may also be an &, in which case the {data} is interpreted 

as a list 

{format list} {data} ∗ 

8

pdf::length (proc) 

pdf::length_obj (proc) 

which will be formatted by a recursive sprintf call and inserted into the result 

at that position. This is intended to simplify encoding structured data. 

The exact format of a conversion specifier is 

%〈char〉 〈count〉(.〈precision〉) ? ? 

The 〈count〉 defaults to 1 and specifying a non-unit 〈count〉 value is equivalent 

to specifying that many separate conversion specifiers in sequence. Specifying a 

〈precision〉 overrides the precision default for real and length conversions. 

Page contents in PDF are primarily graphical, and thus there is a fair amount 

of coordinates involved. For manufacturing isolated coordinates, the length com- 

mand, its object-making counterpart length_obj, and the printf counterpart %l 

are convenient, as they make it possible to express lengths in physical units and 

then have them automatically converted to the (default) PDF length unit. The 

syntax is 

pdf::length {value} {unit} 


where {value} is the numerical value, {unit} the name of the unit it is expressed 

in, and {precision} as with real_obj an optimal precision that is specified if one 

wishes to override the default. The units known to the pdf package are 

An example: 

bp Postscript point (1/72 in) 

cc cicero 

cm centimeter 

dd Didot point (European printer’s point) 

in inch 

mm millimeter 

pc pica 

pt (American) printer’s point 

pdf::begin_contents "" $F "A page" 

pdf::printf $F {%l2 m %L l S} 5 cm 5 cm {10 15} cm 

pdf::name_resource times_font $F Font [pdf::dict_obj\ 

/Type /Font /Subtype /Type1 /BaseFont /Times-Roman\ 

/Encoding /MacRomanEncoding] 

pdf::printf $F {BT} 

pdf::printf $F {%o %l Tf 1 0 0 1 %L1.1 Tm} $times_font 12 dd {8 10} cm 

pdf::printf $F {%s Tj} [encoding convertto macRoman "na\u00EFve"] 

pdf::printf $F {ET} 

pdf::end_contents resarr $F 

1.7 Rectangles 

Coordinates occur not only in page contents, but also in many other data structures 

in a PDF file. In particular it is common that one has to specify some 

9

pdf::make_rect (proc) 

pdf::offset_rect (proc) 

pdf::inset_rect (proc) 

rectangle (e.g. the clickable area of a link, or the imagable area of a page), so the 

pdf package provides several commands for creating, modifying, and formatting 

rectangles. 

The basic format for a {rectangle} that the pdf package uses is as a list of four 

elements 

{left} {bottom} {right} {top} 

each of which is the coordinate of one side of the rectangle, in default PDF units 

(i.e., bp). Such lists are returned by the commands 

pdf::make_rect {option} {value} {unit} ? + 

pdf:offset_rect {rect} {dx} {dy} {unit} ? 

pdf::inset_rect {rect} {amount} {unit} 

pdf::inset_rect {rect} {dx} {dy} {unit} 

pdf::inset_rect {rect} {dl} {db} {dr} {dt} {unit} 

pdf::standard_rect {rect} 

make_rect is a generic “tell me what you know about the rectangle and I’ll figure 

out what its coordinates are” command. Each option specifies a value for one 

or two quantities that can be derived from the rectangle coordinates, and by 

combining the information the command calculates the rectangle coordinates. 

-width Distance from left to right 

-height Distance from bottom to top 

-left left 

-right right 

-top top 

-bottom bottom 

-ll {left bottom} 

-lr {right bottom} 

-ul {left top} 

-ur {right top} 

-center midpoint 

-midx x-coordinate of midpoint 

-midy y-coordinate of midpoint 

The way it works is that the list of options is processed left to right, every 

option contributes some information about the wanted rectangle, and when all 

four coordinates are known the rectangle is returned. The {value} is, depending 

on the option, either a number or a point (list of two numbers). The {unit} is the 

unit of the {value}; it defaults to bp if omitted. 

Once a rectangle has been constructed, it can be modified using the other 

commands shown above. The offset_rect command moves the rectangle but 

preserves its size; the {unit} defaults to bp. The inset_rect command shrinks a 

rectangle by moving the sides inwards by the specified amount(s), or for a negative 

amount grows the rectangle by moving the sides outwards. One can specify a single 

10

pdf::standard_rect (proc) 

pdf::rect_obj (proc) 

pdf::int_rect_obj (proc) 

pdf::wh_rect (proc) 

pdf::paper_rect (array) 

{amount} for all sides, separate {dx} and {dy} amounts for horizontal and vertical 

coordinates respectively, or separate amounts for each of the four sides. A typical 

usage is to shrink a rectangle to leave a margin. 

It is possible to end up with a rectangle where the {bottom} is above the {top} 

or {left} is further right than {right} itself, i.e., a rectangle with negative height 

or width. PDF consumers typically normalises such rectangles by exchanging 

the sides as necessary, so this is often not a problem, but if you want to ensure 

that a rectangle has positive height or depth then you may feed it through the 

standard_rect command. This might be necessary if you want to place a point 

below some given rectangle. 

To get a rectangle into PDF code, there are three commands 



pdf::wh_rect {rectangle} 

rect_obj returns a rectangle object (a PDF array of four real numbers). 

int_rect_obj also returns a rectangle object, but rounds the coordinates to in- 

tegers first to conserve space. wh_rect does not return PDF code, but simply the 

four element Tcl list 

{left} {bottom} {width} {height} 

that corresponds to the {rectangle}. These are the operands of the re operator, 

and can be conveniently formatted using %R. 

Finally, there is an array paper_rect which contains the /MediaBox rectangles 

corresponding to some popular paper sizes: A4, A4R (landscape A4), letter, and 

legal. 

Implementation 

2 PDF files and objects 

A Portable Document Format (PDF) file is, when compared with for example a 

PostScript file or HTML file, a rather disorganised document. This is because at 

the basic level, a PDF file is a heap rather than a text; it can be “disorganised” 

since its logical structure is based on cross-referencing rather than on sequentiality. 

The first step is therefore to provide support for writing well-formed heaps. 

1 〈∗pkg〉 

2 package require Tcl 8.3 

Tcl 8.3 is required for array unset, and string equal is used in some places. It 

should be possible to make the code should run on Tcl 8.1.1 (which is required for 

string map) if those two were worked around. 

3 package provide pdf 0.2 

4 namespace eval pdf {} 

11

2.1 Building objects 

The independent units in a PDF file are called objects. An object is essentially 

a value (which includes a type). The procedures below construct strings of PDF 

code that encode objects of various types. The strings returned are generally 

such that one must insert whitespace between two such strings if the data is to 

be properly encoded. The strings may contain newlines if some building routine 

thinks the lines should otherwise be too long. 

pdf::boolean_obj (proc) The boolean_obj procedure returns a boolean object, corresponding to the string 

passed as its only argument. The argument can be any Tcl boolean value. 

5 proc pdf::boolean_obj {value} { 

6 if {$value} then {return true} else {return false} 

7 } 

pdf::int_obj (proc) The int_obj procedure returns the PDF object corresponding to the integer supplied 

as argument. 

pdf::real_obj (proc) 

pdf::precision (var.) 

8 proc pdf::int_obj {value} {format %d $value} 

The real_obj procedure returns the PDF object corresponding to the real number 

supplied as argument. The syntax is 

pdf::real_obj {value} {precision} ? 

where {precision} is the number of decimals that will be included in the object. 

If omitted, the value of the precision variable is used, and that defaults to 3. 

9 set pdf::precision 3 

10 proc pdf::real_obj {value {precision -1}} { 

11 if {$precision

24 if {$code==92} then { 

25 append str \\ 

26 incr len 

27 continue 

28 } elseif {$code=100} { 

47 lappend L [string map [list \\ \\\\ ( \$ ) \$ \r \\r \n \\n]\ 

[string range $str 0 99]] 

49 set str [string range $str 100 end] 

50 } 

51 if {[string length $str]} then { 

52 lappend L\ 

[string map [list \\ \\\\ ( \$ ) \$ \r \\r \n \\n] $str] 

54 } 

55 set str ([join $L \\\n]) 

56 } 

57 return $str 

58 } 

pdf::hexstring_obj (proc) The hexstring_obj procedure returns the PDF string object, encoded as hexadecimal 

digits, that corresponds to the argument. If the string is longer than 31 

characters then it will be broken on several lines. 

59 proc pdf::hexstring_obj {str} { 

60 set hstr "

70 incr len 2 

71 } else { 

72 error "Bad character $ch [format (U+%04x) $code] in PDF\ 

string." 

74 } 

75 } 

76 append hstr ">" 

77 } 

pdf::text_obj (proc) The text_obj procedure returns the PDF text string object that corresponds to 

the argument string. The syntax is 

pdf::text_obj {string} 

where {string} is an arbitrary Tcl string. (Ordinary PDF strings are more like Tcl 

byte arrays.) 

The greatest complication in the implementation is checking whether the 

{string} can be encoded in PDFDocEncoding or will have to be expressed in 

UTF-16BE. This is handled slightly sneakily, as in fact only the subset of 

PDFDocEncoding that coincides with iso8859-1 (and hence Unicode) is allowed; 

any character outside that set triggers conversion to UTF-16BE (as does a string 

that begins with the Byte Order Mark \xFE\xFF). 

UTF-16BE-encoded strings are hexcoded, since they are probably easier to 

interpret that way. Strings not requireing UTF-16BE-encoding are not hexcoded. 

78 proc pdf::text_obj {str} { 

79 if {[regexp -- {[^ -~\241-\254\256-\377]|^\xFE\xFF} $str]} then { 

80 binary scan [encoding convertto unicode $str] H* uhex 

81 regsub -all -- {\w{64}} "" "&\n" res 

82 return $res 

83 } else { 

84 return [string_obj $str] 

85 } 

86 } 

pdf::name_obj (proc) The name_obj procedure returns the PDF name object corresponding to its argument. 

It is useful mainly for names with strange characters in them (non-ASCII 

characters or characters with special meaning in PDF syntax), but most names 

(e.g. dictionary keys) appearing in PDF files do not require any quoting and can 

therefore just as well be written as explicit PDF code. 

87 proc pdf::name_obj {str} { 

88 if {[string bytelength $str]>126} then { 

89 error "String too long to be a PDF name." 

90 } 

91 set res / 

92 foreach ch [split [encoding convertto utf-8 $str] {}] { 

93 switch -glob -- $ch { 

94 ( - ) - < - > - \\[ - \\] - \{ - \} - / - % - # { 

95 scan $ch %c code 

96 append res [format #%02x $code] 

14

97 } 

98 [!-~] {append res $ch} 

99 default { 

100 scan $ch %c code 

101 append res [format #%02x $code] 

102 } 

103 } 

104 } 


106 } 

pdf::array_obj (proc) The array_obj procedure builds an array object of the objects it is given as 

arguments. The syntax is 

pdf::array_obj {object} ∗ 

Newlines are inserted between the objects if it does not appear as if the object 

would fit on a single (100 character) line. 

107 proc pdf::array_obj {args} { 

108 set res \[ 

109 set len 1 

110 foreach item $args { 

111 if {[string length $item] + $len >= 100} then { 

112 append res \n 

113 set len 0 

114 } elseif {[string length $res]>1} then { 

115 append res " " 

116 incr len 

117 } 

118 append res $item 

119 incr len [string length $item] 

120 } 

121 if {$len >= 100} then { 

122 append res \n 

123 } 

124 append res \] 

125 } 

pdf::dict_obj (proc) The dict_obj procedure builds a dictionary object from its arguments. The 

syntax is 

pdf::dict_obj {key} {value} ∗ 

where each {key} must be a name object and each {value} must be an object. It 

is checked that the number of elements is correct and that the keys begin with a 

slash. 

126 proc pdf::dict_obj {args} { 

127 if {[llength $args] % 2 != 0} then { 

128 error "Not the same number of keys and values." 

129 } 

15

130 set res ">" 

142 } 

pdf::null_obj (proc) The null_obj procedure returns a null object. It has no arguments. 

143 proc pdf::null_obj {} {return null} 

pdf::date_obj (proc) The date_obj procedure formats a Tcl seconds value as a PDF date string object. 

The syntax is 

pdf::date_obj {seconds} {local} ? 

where {seconds} is the time as returned by clock seconds and {local} controls 

how to deal with the issue of time zones. The possible values for this are (noncase-sensitive) 

none or an empty string Express time in local timezone, but don’t include any time zone information 

in the result. This is the default. 

UTC or gmt Express time in UTC and use Z as timezone. 

local or full Express time in local timezone, compute its difference to UTC, and include 

that in the result. 

144 proc pdf::date_obj {secs {local ""}} { 

145 switch -- [string tolower $local] none - "" { 

146 return [clock format $secs -format (D:%Y%m%d%H%M%S)] 

147 } utc - gmt { 

148 return [clock format $secs -format (D:%Y%m%d%H%M%SZ) -gmt 1] 

149 } full - local { 

150 set res [clock format $secs -format (D:%Y%m%d%H%M%S] 

151 set semilocal [clock format $secs -format "%Y%m%d %H:%M:%S"] 

152 set local [clock scan $semilocal -gmt 1] 

153 set offset [expr {$local - $secs}] 

154 if {$offset < 0} then { 

155 append res - 

156 set offset [expr abs($offset)] 

157 } else { 

158 append res + 

159 } 

160 append res [clock format $offset -format "%H’%M’)" -gmt 1] 

16


162 } default { 

163 error "Unknown locality setting ’$local’" 

164 } 

165 } 

Objects can also be streams, but those have a special relation to the file structure 

and are therefore best treated in conjunction with that. In particular, streams 

cannot be used as arguments of array_obj or dict_obj. The arguments of these 

procedures can however be indirect references to objects of any type, but these 

too are best treated in the context of the basic PDF file structure. 

2.2 File structure 

The body of a PDF file consists of a sequence of indirect objects, which are mainly 

a sort of declarations: a pair of integers are associated with an object value. Since 

any composite object can (and in several cases must) contain a reference to any 

indirect object, this makes it possible to build up arbitrary data structures. It 

is however also a complication, since it requires that there is a mechanism for 

allocating these numbers. 

pdf::file〈num〉 (array) Every file that Tcl opens gets a unique identifier which is used in calls to puts and 

such. This identifier is also used as the name of an array in the pdf namespace, 

in which the procedures below store all auxiliary information they need to create 

a proper PDF file. 

pdf::file〈num〉 

(!〈reference label〉) 


(last_object_num) 

In this API, references to indirect objects can be arbitrary strings, called reference 

labels. The correspondence to the object numbers actually found in the file is given 

by the !〈reference label〉 entries in the array of the file in question. The entries in 

this array are lists with the structure 

{object number} {generation number} {file position} ? 

where the {file position} is present only if the indirect object in question has been 

written to file already. The {object number} is the number of the object referred 

to. The {generation number} is currently always zero; it appears that it can only 

be nonzero for files that have incrementally updated, and this API only supports 

creating a file from scratch. The {file position} is the position in the file of the 

beginning of the indirect object begin referred to. 

The last_object_num entry in the array holds the most recently allocated 

object number. It is incremented whenever a new reference label is encountered. 

pdf::obj_ref (proc) The obj_ref procedure returns PDF code for an indirect reference to an object. 

The syntax is 


17

pdf::begin_stream (proc) 

pdf::end_stream (proc) 


(current_stream) 


(?〈reference label〉) 

where {file} is the indentifier of the PDF file in question. If the {reference label} 

has not been encountered before for this particular file, then a new object number 

is allocated for it. 

166 proc pdf::obj_ref {F label} { 

167 upvar #0 [namespace current]::$F A 

168 if {![info exists A(!$label)]} then { 

169 incr A(last_object_num) 

170 set A(!$label) [list $A(last_object_num) 0] 

171 } 

172 format {%d %d R} [lindex $A(!$label) 0] [lindex $A(!$label) 1] 

173 } 

The begin_stream and end_stream procedures delimit the creation of a stream 

object. Between two such commands, it is possible to write arbitrary text (usually 

page descriptors or some sort of embedded data) to the PDF file and have it 

inserted correctly into the file as the data stored in the stream object. 

The syntax for begin_stream is 

pdf::begin_stream {file} {reference label} {key} {value} ∗ 

where {file} of course is the file to write to and {reference label} is the string that 

should be used to reference this object. Each stream consists of one dictionary part 

and one data part, where the primary task of the dictionary part is to specify how 

the data part should be interpreted. The most important element in the dictionary 

is the /Length key and its value—these are inserted by the begin_stream and 

end_stream commands, so one needs not worry about those—but if for example 

the data part is encoded in some special way (for example, it might be compressed) 

then it is necessary to include additional elements in the dictionary. This is what 

the {key} and {value} arguments are for. 

The current_stream entry in a PDF file array is set if and only if the current 

position in that file is inside a stream. It is not possible to begin a new stream 

when this entry is set. The value of this entry is a list with the structure 

{reference label} {start} 

where {reference label} is the reference label of the stream and {start} is the 

position in the file of the first byte in the stream data. Both of these are needed 

at end_stream to record the length of the stream data. 

This kind of entry is used for indirect objects that are lengths of the stream whose 

reference label is the 〈reference label〉. They have the same syntax as their ! 

ordinary counterparts. 

174 proc pdf::begin_stream {F label args} { 


176 if {[info exists A(current_stream)]} then { 

177 error "There is already a stream ([lindex $A(current_stream) 0])\ 

being written to in this file." 

18

179 } 




183 } 

184 set A(?$label) [list [incr A(last_object_num)] 0] 

185 lappend A(!$label) [tell $F] 

186 puts $F\ 

[format {%d %d obj} [lindex $A(!$label) 0] [lindex $A(!$label) 1]] 

188 puts $F [eval\ 

[list dict_obj /Length [format {%d 0 R} $A(last_object_num)]]\ 

$args] 

191 puts $F stream 

192 set A(current_stream) [list $label [tell $F]] 

193 } 

The end_stream procedure takes the target file as its only argument. It finishes 

off the stream as necessary. It also evaluates everything that has been placed in 

the backlog of the file. 

pdf::file〈num〉(backlog) It is not possible to output a new indirect object when a stream is being written to, 

but it can still be at such a time that the need for such an object is discovered. The 

backlog entry provides a way around that limitation—this entry is a script that is 

evaluated (and cleared) at the end of every end_stream, hence commands can be 

delayed by appending them to this script, instead of evaluating them immediately. 

New commands are appended to the backlog, and must be preceeded by a 

command separator. 

194 proc pdf::end_stream {F} { 


196 if {![info exists A(current_stream)]} then { 

197 error "There is no stream to end." 

198 } 

199 set length [expr {[tell $F] - [lindex $A(current_stream) 1]}] 

200 set label [lindex $A(current_stream) 0] 

201 unset A(current_stream) 

202 puts $F "endstream endobj" 

203 lappend A(?$label) [tell $F] 

204 puts $F [format {%d %d obj %d endobj} [lindex $A(?$label) 0]\ 

[lindex $A(?$label) 1] $length] 

206 eval "set A(backlog) {}; $A(backlog)" 

207 } 

pdf::put_obj (proc) The put_obj procedure writes a direct object to a PDF file. The syntax is 

pdf::put_obj {file} {reference label} {object} 

208 proc pdf::put_obj {F label obj} { 


210 if {[info exists A(current_stream)]} then { 

211 append A(backlog) \n [list put_obj $F $label $obj] 

19

212 return 

213 } 




217 } 

218 lappend A(!$label) [tell $F] 

219 puts $F\ 

[format {%d %d obj} [lindex $A(!$label) 0] [lindex $A(!$label) 1]] 

221 puts $F $obj 

222 puts $F endobj 

223 } 

pdf::rewrite_pdf (proc) The rewrite_pdf procedure opens a new PDF file for writing and initialises the 

associated data structures. The syntax is 

pdf::rewrite_pdf {file name} 〈options〉 

and the return value is the identifier of the file opened. The {file name} is of 

course the name of that file. The 〈options〉 is zero or more of 

-permissions {integer} 

-header {string} 

The permissions are the default permissions for the file in question. If this is not 

specified, then no such value is specified to open, The header is a string that will 

be put first in the file (as header). It defaults to 

%PDF-1.3 

%˚aäö 

(in UTF-8) where the first line is a standard header line, and the second line is 

there to help some software understand that the file should be treated as a binary 

file. Note that no newline is inserted after this string; be sure to include it in the 

string if necessary. 

224 proc pdf::rewrite_pdf {name args} { 

225 set Opt(-header) [encoding convertto utf-8 %PDF-1.3\n%\xe5\xe4\xf6\n] 

227 array set Opt $args 

228 if {[info exists Opt(-permissions)]} then { 

229 set F [open $name w $Opt(-permissions)] 

230 } else { 

231 set F [open $name w] 

232 } 

233 fconfigure $F -translation binary 

234 puts -nonewline $F $Opt(-header) 


236 array unset A 

237 set A(last_object_num) 0 

238 set A(backlog) "" 

239 return $F 

240 } 

20

pdf::close_pdf (proc) The close_pdf procedure performs the non-trivial task of finishing off the PDF 

file and closing it. The syntax is 

pdf::close_pdf {file} {catalog label} {key} {value} ∗ 

and the return value is a report detailing any problems encountered (such as 

objects that are referred to but never defined). This is a report rather than an 

error, because there is in many cases no sharp distinction. If the return value is 

non-empty, then there is probably a bug in your program that needs to be fixed. 

The {file} is the identifier of the file to write. The {catalog label} is the reference 

label of the Catalog object in the document. The remaining arguments can be 

used to insert additional information (such as a reference to the Info dictionary of 

the document) in the trailer dictionary. 

241 proc pdf::close_pdf {F label args} { 


243 set reportL [list] 

The first step is to compile the cross-reference table of the document. I originally 

made one subsection for each range of defined indirect objects, giving the 

mandatory free entry #0 a separate subsection, but for some reason Adobe software 

didn’t like that at all. 2 Hence the current implementation is to make a 

cross-reference table with only one subsection, with an explicit free entry for every 

missing item. 

The xrA array constructed below is a prototype for the cross-reference section. 

It is indexed by object number and the entries have the list structure 

{file position} {generation number} {type} 

Just as in a PDF file, the {type} is either f or n depending on whether the entry 

is “free” or “in use”. The {file position} and {generation number} are however 

not padded with zeros, and the {file position} is initially an empty string in the 

“free” entries. 

This first round simply collects the information and detects collisions. 

244 set xrA(0) [list "" 65535 f] 

245 foreach lbl [array names A {[!?]*}] { 

246 set idx [lindex $A($lbl) 0] 

247 set ent [list [lindex $A($lbl) 2] [lindex $A($lbl) 1] n] 

248 if {[llength $A($lbl)]3} then { 

253 lappend reportL "Multiple indirect objects\ 

for label [string range $lbl 1 end]; at\ 

[join [lrange $A($lbl) 2 end]]." 

2 Whether this means Adobe isn’t following their own standard I leave to others to decide. 

Neither GhostScript nor Quartz (the PDF-based graphics system in Mac OS X) seemed to have 

any problems with this arrangement. 

21

256 } 

257 if {![info exists xrA($idx)]} then { 

258 set xrA($idx) $ent 

259 } elseif {[lindex $xrA($idx) 2]=="f" && [lindex $ent 2]=="n"}\ 

then { 

261 lappend reportL "This shouldn’t happen: There are several\ 

reference labels for indirect object $idx. Using that with\ 

label: [string range $lbl 1 end]" 

265 set xrA($idx) $ent 

266 } else { 

267 lappend reportL "This shouldn’t happen: There are several\ 

reference labels for indirect object $idx. Ignoring that\ 

with label: [string range $lbl 1 end]" 

271 } 

272 } 

The second round makes sure that there is a contiguous sequence of reference 

numbers and constructs the linked list of free entries. 

273 set last_free 0 

274 set maxidx [lindex [lsort -integer -decreasing [array names xrA]] 0] 

275 for {set n $maxidx} {$n>=0} {incr n -1} { 

276 if {![info exists xrA($n)]} then { 

277 set xrA($n) [list "" 0 f] 

278 lappend reportL "This shouldn’t happen: Object number $n was\ 

allocated, but not assigned a reference label." 

281 } 

282 if {[lindex $xrA($n) 2]=="f"} then { 

283 set xrA($n) [lreplace $xrA($n) 0 0 $last_free] 

284 set last_free $n 

285 } 

286 } 

Now the cross-reference section can be written to file. 

287 set startxref [tell $F] 

288 puts $F xref 

289 puts $F [format {%d %d} 0 [expr {$maxidx + 1}]] 

290 for {set n 0} {$n

303 puts $F "startxref\n${startxref}\n%%EOF" 

The final step is to close the file and compile the report. 

304 close $F 

305 join $reportL \n 

306 } 

307 〈/pkg〉 

2.3 Hello World 

The code below creates a PDF file matching the basic “Hello World” example [1, 

Sec. A.2]. 

308 〈∗example1〉 

309 set F [pdf::rewrite_pdf hello.pdf] 

310 pdf::put_obj $F "The catalog" [pdf::dict_obj\ 

311 /Type /Catalog\ 

312 /Pages [pdf::obj_ref $F "The pages"]\ 

313 /Outlines [pdf::obj_ref $F "The outlines"]] 

314 pdf::put_obj $F "The outlines"\ 

[pdf::dict_obj /Type /Outlines /Count [pdf::int_obj 0]] 

316 pdf::put_obj $F "The pages" [pdf::dict_obj\ 

317 /Type /Pages\ 

318 /Count [pdf::int_obj 1]\ 

319 /Kids [pdf::array_obj [pdf::obj_ref $F "Page 1"]]] 

320 pdf::put_obj $F "Page 1" [pdf::dict_obj\ 

321 /Type /Page\ 

322 /Parent [pdf::obj_ref $F "The pages"]\ 

323 /Resources [pdf::dict_obj\ 

324 /Font [pdf::dict_obj /F1 [pdf::obj_ref $F "Helvetica"]]\ 

325 /ProcSet [pdf::obj_ref $F "The procs"]]\ 

326 /MediaBox [pdf::array_obj [pdf::int_obj 0] [pdf::int_obj 0]\ 

[pdf::int_obj 612] [pdf::int_obj 792]]\ 

328 /Contents [pdf::obj_ref $F "Page 1 contents"]] 

329 pdf::begin_stream $F "Page 1 contents" 

330 puts $F {BT} 

331 puts $F {/F1 24 Tf} 

332 puts $F {100 100 Td (Hello World) Tj} 

333 puts $F {ET} 

334 pdf::end_stream $F 

335 pdf::put_obj $F "The procs" [pdf::array_obj /PDF /Text] 

336 pdf::put_obj $F "Helvetica" [pdf::dict_obj /Type /Font /Subtype /Type1\ 

/Name /F1 /BaseFont /Helvetica /Encoding /MacRomanEncoding] 

339 pdf::close_pdf $F "The catalog" 

340 〈/example1〉 

3 Contents and resources 

Most of the things one actually sees of a PDF document is part of a content stream, 

which is the side of PDF which is most like a simplified Postscript file: a sequence 

23

pdf::resource_dict_obj 

(proc) 

of simple operators for drawing text and graphics, and before each operator is 

arguments. One difference is however that many types of data are not permitted 

within a content stream, because some aspects (indirect objects, dictionaries) of 

the required forms of such data are not permitted there. Instead the content 

stream has to be supplemented by a resources dictionary, which locally associates 

names to objects, and these names are what one may use in the content stream. 

The model used here to overcome this is to equip the internal representation of 

a contents stream with a representation of the corresponding resources dictionary. 

Commands emitting operators that make use of such indirect resources should 

check if these are present in the resources dictionary, and see to that they are 

added if they were not. The resources dictionary is uniquely identified by the file 

identifier and stream object label. 

3.1 Resources representation 

Resources dictionaries are kept in arrays, where each resource type (or equivalently: 

entry in the dictionary) has a separate entry. These entries are key–value 

lists where the keys are PDF name objects and the values are the underlying resource 

objects (normally indirect references). (An exception is the ProcSet entry, 

which is a straight list of names.) The resource type names are the same as in 

the PDF file, e.g. XObject, Font, and ProcSet—in other words, don’t include a 

leading slash. 

Since explicit declaration of procsets was declared obsolete in PDF 1.4 and 

wasn’t very useful earlier either, most of the support for specifying procsets has 

been removed from the pdf package, and the ProcSet entries instead default to 

listing all five procsets. If for some reason you wish to specify a smaller set of 

procsets, then set the ProcSet entry of your resources array to a list of those 

names of procsets that you want to require. 

The resource_dict_obj procedure returns the PDF dictionary object for the 

data kept in an array. The call syntax is 

pdf::resource_dict_obj {array-name} 

where the {array-name} refers to an array in the local context of the caller. 

If the array does not contain any ProcSet entry, then for compatibility such 

an entry listing all five procsets is inserted. 

341 〈∗pkg〉 

342 proc pdf::resource_dict_obj {arrname} { 

343 upvar 1 $arrname A 

344 set call [list dict_obj] 

345 if {![info exists A(ProcSet)]} then { 

346 lappend call /ProcSet {[/PDF/Text/ImageB/ImageC/ImageI]} 

347 } 

348 foreach type [array names A] { 

349 lappend call [name_obj $type] 

350 if {$type == "ProcSet"} then { 

351 lappend call [eval [linsert $A(ProcSet) 0 array_obj]] 

24


(Resources/〈type〉) 

pdf::begin_contents 

(proc) 

pdf::end_contents (proc) 

352 } else { 

353 lappend call [eval [linsert $A($type) 0 dict_obj]] 

354 } 

355 } 

356 eval $call 

357 } 

When a content stream is being written to, the resources dictionary data of that 

stream is kept in the main array of that PDF file. The entry formats are the same 

as when kept in a separate array, but the entry names are prefixed by Resources/ 

to prevent name clashes. 

The begin_contents and end_contents procedures are specialised forms of 

begin_stream and end_stream that, in addition to delimiting the creation of 

a stream object, manage the associated resources dictionary. 

The syntax for begin_content is 

pdf::begin_contents {resources-array} {file} {reference label} {key} 

{value} ∗ 

where all arguments except {resources-array} are as for begin_stream. If this 

extra argument is nonempty then it is the name in the local context of the caller 

of an array representing a resources dictionary; the procedure copies the contents 

of that array to the current resources dictionary for this file. If {resources-array} 

is empty then the current resources dictionary is set to being empty. 

358 proc pdf::begin_contents {arr F label args} { 

359 eval [list begin_stream $F $label] $args 


361 array unset A Resources/* 

362 if {[string length $arr]} then { 

363 upvar 1 $arr B 

364 foreach type [array names B] { 

365 set A(Resources/$type) $B($type) 

366 } 

367 } 

368 } 

The end_contents procedure has the syntax 

pdf::end_contents {resources-array} {file} 

It copies the current resources dictionary data for the {file} to the {resources-array} 

(variable name in the local context of the caller) and then calls end_stream to 

end the current contents stream. 

369 proc pdf::end_contents {arr F} { 


371 if {![info exists A(current_stream)]} then { 

372 error "There is no stream to end." 

373 } 

25

pdf::has_resource? 

(proc) 

374 upvar 1 $arr B 

375 foreach index [array names A Resources/*] { 

376 set type [string range $index 10 end] 

377 set B($type) $A($index) 

378 } 

379 end_stream $F 

380 } 

The has_resource? procedure can be used to query whether a particular resource 

is present in the current resources dictionary. The syntax is 

pdf::has_resource? {file} {type} {object} {name-var} ? 

and the return value is 1 if the {object} is one of the objects listed under the 

{type} in the current dictionary of the file {file} and 0 otherwise. If a {name-var} 

is specified and the return value is 1 then that variable in the local context of the 

caller will be set to the PDF name object associated with the given {object}. 

381 〈∗obsolete〉 

382 proc pdf::has_resource? {F type obj {namevar {}}} { 


384 if {![info exists A(Resources/$type)]} then {return 0} 

385 if {$type == "ProcSet"} then { 

386 if {[lsearch -exact $A(Resources/$type) $obj] >= 0} then { 

387 if {[string length $namevar]} then { 

388 uplevel 1 [list ::set $namevar $obj] 

389 } 

390 return 1 

391 } else { 

392 return 0 

393 } 

394 } 

395 foreach {name resobj} $A(Resources/$type) { 

396 if {[string equal $resobj $obj]} then { 

397 if {[string length $namevar]} then { 

398 uplevel 1 [list ::set $namevar $name] 

399 } 

400 return 1 

401 } 

402 } 

403 return 0 

404 } 

405 〈/obsolete〉 

pdf::name_resource (proc) The name_resource procedure provides a name object referring to an object and 

(if necessary) adds that object to the current resources dictionary of the file. The 

syntax is 

pdf::name_resource {var-name} {file} {type} {object} {suggested 

name} ? 

26

where {var-name} is the name of a variable in the local context of the caller that 

will be set to the name object referring to the specified resuource. The result is 0 

if the resource was already present and 1 if an entry for it was added. 

The {file} is the identifier of the PDF file in which the stream is located for 

which this resource is going to be made available. The {type} is the name (slash 

not included) of the resource dictionary entry where this resource should be placed, 

e.g. Font, XObject, etc. The {object} is the object that constitutes the resource to 

name. The {suggested name} argument can be used to request a particular name 

for the resource; it should be the PDF name object to give the resource. An error 

will be raised if that name is already used for some other resource of that type. 

The {type} must not be ProcSet. 

406 proc pdf::name_resource {varname F type obj {name {}}} { 


408 switch -- $type ColorSpace { 

409 set short_type /CS 

410 } XObject { 

411 set short_type /XO 

412 } ExtGState { 

413 set short_type /GS 

414 } Font { 

415 set short_type /F 

416 } Pattern { 

417 set short_type /Pat 

418 } ProcSet { 

419 error {If you really think you need to bother about procsets,\ 

then access the array directly.} 

421 } Properties { 

422 set short_type /Prop 

423 } Shading { 

424 set short_type /Sh 


426 set short_type /$type 

427 } 

428 if {![info exists A(Resources/$type)]} then { 

429 if {![string length $name]} then { 

430 set name ${short_type}0 

431 } 

432 set A(Resources/$type) [list $name $obj] 

433 uplevel 1 [list ::set $varname $name] 

434 return 1 

435 } 

436 if {[string length $name]} then { 

437 foreach {key val} $A(Resources/$type) { 

438 if {[string equal $key $name]} then { 

439 if {![string equal $obj $val]} then { 

440 error "Name already in use for: $val" 

441 } 


443 return 0 

27

pdf::require_procsets 

(proc) 

444 } 

445 } 

446 lappend A(Resources/$type) $name $obj 


448 return 1 

449 } 

450 set name "${short_type}[expr {[llength $A(Resources/$type)]/2}]" 

451 regsub -all {[\[\]?*\\]} $short_type {\\&} pattern 

452 append pattern * 

453 set free 1 

454 foreach {key val} $A(Resources/$type) { 

455 if {[string equal $val $obj]} then { 

456 uplevel 1 [list ::set $varname $key] 

457 return 0 

458 } 

459 if {[string equal $key $name]} then {set free 0} 

460 if {[string match $pattern $key]} then { 

461 set Used([string range $key [string length $short_type] end])\ 

{} 

462 } 

463 } 

464 if {!$free} then { 

465 set n [expr {[llength $A(Resources/$type)]/2}] 

466 while {[info exists Used($n)]} {incr n} 

467 set name ${short_type}$n 

468 } 

469 lappend A(Resources/$type) $name $obj 


471 return 1 

472 } 

The require_procsets procedure is called to make sure that certain ProcSets 

are listed the current resources dictionary. The syntax is 

pdf::require_procsets {file} {name obj } ∗ 

where {file} is the relevant file and the {name obj }s are the PDF name objects of 

the required ProcSets. 

473 〈∗obsolete〉 

474 proc pdf::require_procsets {F args} { 


476 if {![info exists A(Resources/ProcSet)]} then { 

477 set A(Resources/ProcSet) $args 

478 } else { 

479 set A(Resources/ProcSet) [lsort -dictionary -unique [ 

480 concat $A(Resources/ProcSet) $args 

481 ]] 

482 } 

483 } 

484 〈/obsolete〉 

28

3.2 Formatting content 

pdf::sprintf (proc) The sprintf procedure formats data for writing to a PDF contents stream. The 

syntax is 

pdf::sprintf {format list} {data} ∗ 

and the return value is the resulting PDF code. 

The {format list} is similar to the formatting string of format, but every 

conversion specifier must be a separate list element. List elements that are not 

conversion specifiers are copied verbatim to the result. Material from different list 

elements are always separated by whitespace in the result. 

As with format, the first character of a conversion specifier is always a ‘%’. 

The exact format is 

%〈char〉 〈count〉(.〈precision〉) ? ? 

(a 〈precision〉 field requires specifying a 〈count〉 because the conversion specifiers 

are parsed using scan). The 〈count〉 defaults to 1 and specifying a non-unit 〈count〉 

is equivalent to specifying that many separate conversion specifiers in sequence. 

The 〈precision〉 is only used by real and length conversions. 

The conversion character 〈char〉 specifies how the {data} should be converted. 

The basic conversions are 

b Boolean, to be formatted by boolean_obj. 

i Integer, to be formatted by int_obj. 

l Length, to be formatted by length_obj. This consumes two {data} arguments: 

one for the value and one for the unit. 

n String, to be formatted by name_obj. 

o Already formatted PDF object. 

r Real number, to be formatted by real_obj (with default precision according 

to the precision variable). 

s PDF string, to be formatted by string_obj. 

In addition, the corresponding upper case letters select the same formatting, but 

the (first) {data} argument is interpreted as a list of things to process in the 

specified way. Finally, if the character is an & then the {data} is interpreted as a 

list 

{format list} {data} ∗ 

which will be formatted by a recursive sprintf call and inserted into the result 

at that position. This is intended to simplify encoding structured data. 

485 proc pdf::sprintf {format args} { 

486 variable precision 

29

487 set items [list] 

488 set n 0 

489 foreach spec $format { 

490 set count 1 

491 set prec $precision 

492 if {![scan $spec {%%%[bilnorsBILNORS&]%d.%d} code count prec]}\ 

then { 

494 lappend items $spec 

495 } else { 

496 for {} {$count>=1} {incr count -1; incr n} { 

497 set datum [lindex $args $n] 

498 switch -- $code "b" { 

499 lappend items [boolean_obj $datum] 

500 } "i" { 

501 lappend items [int_obj $datum] 

502 } "l" { 

503 lappend items [ 

504 length_obj $datum [lindex $args [incr n]] $prec 

505 ] 

506 } "n" { 

507 lappend items [name_obj $datum] 

508 } "o" { 

509 lappend items $datum 

510 } "r" { 

511 lappend items [real_obj $datum $prec] 

512 } "s" { 

513 lappend items [string_obj $datum] 

514 } "B" { 

515 foreach d $datum {lappend items [boolean_obj $d]} 

516 } "I" { 

517 foreach d $datum {lappend items [int_obj $d]} 

518 } "L" { 

519 set unit [lindex $args [incr n]] 

520 foreach d $datum { 

521 lappend items [length_obj $d $unit $prec] 

522 } 

523 } "N" { 

524 foreach d $datum {lappend items [name_obj $d]} 

525 } "O" { 

526 eval [list lappend items] $datum 

527 } "R" { 

528 foreach d $datum { 

529 lappend items [real_obj $d $prec] 

530 } 

531 } "S" { 

532 foreach d $datum {lappend items [string_obj $d]} 

533 } "&" { 

534 lappend items [eval [linsert $datum 0 sprintf]] 


536 error "Bad pdf::sprintf format specifier ‘$spec’." 

30

537 } 

538 } 

539 } 

540 } 

541 join $items 

542 } 

pdf::printf (proc) The printf procedure is an extension of sprintf that immediately writes the 

formatted string to a file rather than returning it. The syntax is 

pdf::printf {file} {format list} {data} ∗ 

543 proc pdf::printf {F format args} { 

544 puts $F [eval [list sprintf $format] $args] 

545 } 

546 〈/pkg〉 

3.3 Hello again, World 

The code below is an example that achieves very much the same things as that in 

Subsection 2.3, but this time using the resource management and data formatting 

provided for content streams. 


548 set F [pdf::rewrite_pdf helloagain.pdf] 

549 pdf::put_obj $F "Helvetica" [pdf::dict_obj /Type /Font /Subtype /Type1\ 

/BaseFont /Helvetica /Encoding /MacRomanEncoding] 

(It turns out that the /Name entry, which is included in 〈example1〉, of PDF files 

has been depracated for quite some time, although it is still in the “Hello world” 

example of the PDF 1.5 specification.) 

With resource management, page contents is merely the following. 

552 pdf::begin_contents "" $F "Page 1 contents" 

553 pdf::name_resource Helvetica $F Font [pdf::obj_ref $F "Helvetica"] 

554 pdf::printf $F {BT %o %i Tf %r2 Td %s Tj ET} $Helvetica 24 100 100 \ 

{Hello again, World!} 

Let’s add also some graphics: a green circle with midpoint (200, 200) and radius 

50. PDF doesn’t have circular arcs, but the MetaFont four segment approximation 

should do nicely. This places the control points 4 

√ −1 

3 1 + 2 ≈ 0.552284749831 

of the radius from their nearest knot, and for a radius of 50 that is very nearly 

27.6. 

556 pdf::printf $F {%R rg} {0 1 0} 

557 pdf::printf $F {%R m %R3 c %R3 c %R3 c %R3 c f}\ 

558 {200 150}\ 

559 {227.6 150} {250 172.4} {250 200}\ 

560 {250 227.6} {227.6 250} {200 250}\ 

561 {172.4 250} {150 227.6} {150 200}\ 

562 {150 172.4} {172.4 150} {200 150} 

563 pdf::end_contents Res1 $F 

31


(Pages/〈num〉) 


(Pages/prefix) 


(Pages/arity) 


(Pages/last) 


(Pages/attributes) 

564 pdf::put_obj $F "Page 1" [pdf::dict_obj\ 

565 /Type /Page\ 

566 /Parent [pdf::obj_ref $F "The pages"]\ 

567 /MediaBox [pdf::array_obj [pdf::int_obj 0] [pdf::int_obj 0]\ 

[pdf::int_obj 612] [pdf::int_obj 792]]\ 

569 /Resources [pdf::resource_dict_obj Res1]\ 

570 /Contents [pdf::obj_ref $F "Page 1 contents"]] 

571 pdf::put_obj $F "The pages" [pdf::dict_obj\ 

572 /Type /Pages\ 

573 /Count [pdf::int_obj 1]\ 

574 /Kids [pdf::array_obj [pdf::obj_ref $F "Page 1"]]] 

575 pdf::put_obj $F "The catalog"\ 

[pdf::dict_obj /Type /Catalog /Pages [pdf::obj_ref $F "The pages"]] 

There is really no point in making an /Outlines dictionary that would anyway 

be empty. 

Something there is a point in making is however a document information dictionary. 

578 pdf::put_obj $F "Document info" [pdf::dict_obj\ 

579 /Title [pdf::text_obj "Hello again, world!"]\ 

580 /CreationDate [pdf::date_obj [clock seconds]] ] 

582 pdf::close_pdf $F "The catalog" /Info [pdf::obj_ref $F "Document info"] 


4 Document pages 

4.1 The tree of pages 

One of the quirks of PDF is the (very data structure) requirement that (amongst 

other things) pages have to be organised in a tree structure, where links go not only 

from parent to child, but also from child to parent. This is definitely something 

that programmers shouldn’t have to bother with, so the pdf package can take care 

of generating such a structure when pages are merely sequentially appended to 

the document. 

At the heart of the page tree generation lies the preliminary representations of 

Pages tree nodes that have to be constructed before actual code can be written to 

the file. Every Pages node has an entry in the array of the file, and the contents 

of these entries are lists with the structure 

{kid label} {kid count} + 

where each pair of elements corresponds to one child node. The {kid label} is the 

reference label for this node and the {kid count} is the number of pages in that 

subtree. 

Building a Pages tree necessarily means that Pages nodes, which are indirect 

objects, have to be created. That in turn means that they will have to be assigned 

32

labels, and in order to avoid clashes with labels used elsewhere, the user is required 

to specify a label prefix for the Pages tree system to use. This prefix is stored in 

the Pages/prefix entry of the file array. 

The maximal number of children a node is allowed to have is kept in the 

Pages/arity entry. The number of the most recently created node is kept in the 

Pages/last node. 

The Pages/attributes entry is a list of keys and values to insert into the root 

Pages node. 

pdf::begin_pages (proc) The begin_pages procedure initialises the Pages tree system for a PDF file. The 

syntax is 

pdf::begin_pages {file} {label prefix} {option} {value} ∗ 

where {file} is the identifier of the PDF file and {label prefix} will be used as prefix 

of all reference labels created by the Pages tree system. An {option} {value} is 

either 

-arity {arity} 

or a pair of PDF objects, where the first is a name object. The {arity} is the 

maximal number of children a node is allowed to have; it defaults to 5. The PDF 

object pairs will be inserted into the root Pages node. Additional such items may 

be specified at end_pages. 

584 〈∗pkg〉 

585 proc pdf::begin_pages {F prefix args} { 


587 set A(Pages/arity) 5 

588 set A(Pages/attributes) [list] 

589 set A(Pages/prefix) $prefix 

590 foreach {option value} $args { 

591 switch -glob -- $option -arity { 

592 set A(Pages/arity) $value 

593 } /* { 

594 lappend A(Pages/attributes) $option $value 


596 error "Unknown option: $option" 

597 } 

598 } 

599 set A(Pages/last) 1 

600 set A(Pages/1) [list] 

601 } 

pdf::shipout (proc) This procedure writes a Page object to a file and inserts that into the Pages tree 

of that file after all pages previously inserted. The syntax is 

pdf::shipout {file} {label} {key} {object} + 

where {file} is the PDF file identifier and {label} is the reference label for the page 

object. The {key} and {object} arguments are attributes for the page object (keys 

33

and values for the dicitionary). This should not include the /Type and /Parent 

attributes, which are inserted automatically. 

602 proc pdf::shipout {F label args} { 


604 if {[llength $A(Pages/$A(Pages/last))]/2 >= $A(Pages/arity)} then { 

605 incr A(Pages/last) 

606 set A(Pages/$A(Pages/last)) [list] 

607 } 

608 put_obj $F $label [eval [linsert $args 0 dict_obj /Type /Page\ 

/Parent [obj_ref $F $A(Pages/prefix)$A(Pages/last)]]] 

610 lappend A(Pages/$A(Pages/last)) $label 1 

611 } 

pdf::end_pages (proc) The end_pages procedure completes the Pages tree for a PDF file and returns a 

reference to the root object of that tree. The syntax is 

pdf::make_pages_nodes 

(proc) 

pdf::end_pages {file} 〈attributes〉 

where the {file} is the PDF file identifier and 〈attributes〉 are attributes to insert 

into the root node of the Pages tree. 

The make_pages_nodes procedure takes a list of numbers of Pages nodes that 

have not yet been written to file and writes objects for these nodes to file. The 

syntax is 

pdf::make_pages_nodes {file} {node-list} {parent} ? 

where {file} is the identifier of the PDF file and {node-list} is the list of node 

numbers. If there is a {parent} argument then the Pages node with this number 

will be made the parent of the listed nodes, and the return value is the list of 

reference labels and page counts that need to be included in the Pages/〈parent〉 

entry of the file’s array. If there is not a {parent} argument then the procedure 

allocates a new Pages node and makes that the parent of the listed nodes; the 

result is then the number of the newly allocated parent. 

612 proc pdf::make_pages_nodes {F nodeL {parent -1}} { 


614 if {$parent < 0} then { 

615 set p [incr A(Pages/last)] 

616 } else { 

617 set p $parent 

618 } 

619 set res [list] 

620 set parent_obj [obj_ref $F $A(Pages/prefix)$p] 

621 foreach i $nodeL { 


623 set kids [list array_obj] 

624 foreach {label c} $A(Pages/$i) { 

625 lappend kids [obj_ref $F $label] 

626 incr count $c 

34

627 } 

628 set label $A(Pages/prefix)$i 

629 lappend res $label $count 

630 put_obj $F $label [dict_obj /Type /Pages /Kids [eval $kids]\ 

/Count [int_obj $count] /Parent $parent_obj] 

632 } 

633 if {$parent < 0} then { 

634 set A(Pages/$p) $res 

635 return $p 

636 } else { 


638 } 

639 } 

The basic problem in end_pages is to construct the actual tree so that it is 

reasonably well balanced. The approach used below is to build the tree from 

the leaves to the root, always collect as many children as possible into each new 

node, and move nodes up (well, towards the root; there is some disagreement as 

to whether that is up or down) one level in the tree if the number of nodes in the 

current level is not divisible by the tree arity. 

By allowing nodes to migrate to higher levels, one creates a risk that the tree 

becomes unbalanced. This is managed in the procedure below by keeping track of 

nodes that are saturated, i.e., nodes that have leaves at different depths in their 

subtrees. By not allowing saturated nodes to migrate to a higher level, one can 

ensure that the trees that are constructed are balanced. It is furthermore fairly 

easy to keep track of this, because one can choose nodes for migration in such a 

way that the only node in a level that may be saturated is the last one. This is 

possible because the maximal number of nodes that one may need to migrate is 

one less than the arity, and thus the nodes that migrated to the previous level and 

the saturated nodes in the previous level are always few enough that the last node 

of the new level can be parent of them all. 

640 proc pdf::end_pages {F args} { 


642 array set Attr $A(Pages/attributes) 

643 array set Attr $args 

In the first level of Pages nodes to creat, there are some special complications one 

has to deal with, so on a first read-through, it is better to start with the main 

case. 

In the first level, one faces two additional complication that are not present in 

the main case. The first is that the child nodes are Page nodes rather than Pages 

nodes; this means one cannot move them up to the forrest list being constructed. 

The second complication is that the parents of the Page nodes were fixed before 

all of their children had been created. This requires some special handling of the 

last node: if it does not have a full set of children, then it will have to be moved 

up in a slightly unconventional manner. 

644 set limit $A(Pages/last) 

35

645 if {[llength $A(Pages/$limit)]/2 >= $A(Pages/arity)} then { 

646 set saturated 0 

647 } else { 

648 set d [expr {[llength $A(Pages/$limit)]/2}] 

649 set L [list] 

650 while {$d < $A(Pages/arity) && [incr limit -1]>=1} { 

651 set L [linsert $L 0 $limit] 

652 incr d 

653 } 

654 set last $A(Pages/last) 

655 set A(Pages/$last)\ 

[concat [make_pages_nodes $F $L $last] $A(Pages/$last)] 

657 incr limit -1 


659 } 

660 set forrest [list] 


662 for {set n 1} {$n = $A(Pages/arity)} then { 

665 lappend forrest [make_pages_nodes $F $L] 


667 } 

668 } 

669 if {[llength $L]} then {eval [list lappend forrest] $L} 

670 if {$saturated} then {lappend forrest $last} 

In the main case, the numbers those Pages nodes that have not yet been given 

a parent are kept in the forrest list. The basic approach is to build the next 

level starting from the left of this list, assigning as many of nodes as allowed to 

each new parent node that is created. 

The first complication is that the length of forrest need not be divisible by 

the specified tree arity. In this case, some number of nodes (those that are in 

L below when the entire forrest has been processed) are simply moved up to 

the next level. This leads however to the next complication: if the last node in 

forrest is saturated, then it may not be moved up. The limit variable is used 

for reserving those nodes that will be made siblings of this last node. 

671 while {[llength $forrest] >= $A(Pages/arity)} { 

672 set newforrest [list] 

673 set limit\ 

[expr {[llength $forrest] - ($saturated ? $A(Pages/arity) : 0)}] 


676 foreach n $forrest { 

677 lappend L $n 

678 if {[llength $L] >= $A(Pages/arity)} then { 

679 lappend newforrest [make_pages_nodes $F $L] 


681 } 

682 if {[incr limit -1]

683 } 

684 if {[llength $L]} then {eval [list lappend newforrest] $L} 

685 if {$saturated} then { 

686 lappend newforrest [make_pages_nodes $F [lrange $forrest\ 

[format end-%d [expr {$A(Pages/arity)-1}]] end]] 

688 } elseif {[llength $L]} then { 


690 } 

691 set forrest $newforrest 

692 } 

Here starts the endgame. The root node is special in that it has no parent but 

may recieve many additional attributes. 

693 if {[llength $forrest] > 1} then { 

694 set root [make_pages_nodes $F $forrest] 

695 } else { 

696 set root [lindex $forrest 0] 

697 } 


699 set kids [list array_obj] 

700 foreach {label c} $A(Pages/$root) { 

701 lappend kids [obj_ref $F $label] 

702 incr count $c 

703 } 

704 set res $A(Pages/prefix)$root 

705 set Attr(/Count) [int_obj $count] 

706 set Attr(/Kids) [eval $kids] 

707 set Attr(/Type) /Pages 

708 put_obj $F $res [eval [list dict_obj] [array get Attr]] 


710 } 

Although the above algorithm generates balanced trees of minimal size (minimal 

number of nodes), it does not always generate trees of minimal height—the 

height may be one more than the minimum. What decides this is surprisingly 

enough a kind of odd/even phenonemon: the remainder class modulo the arity 

minus one of the total number of pages! If one is lucky with this, the tree height 

attains the minimum, and if one is unlucky, it comes out one larger than the 

possible minimum. 

The reason that the arity minus one turns up is that every node reduces the 

number of nodes without a parent by precisely one less than the number of children 

of that node. The algorithm keeps assigning the maximal number of children to 

each node, until the level is so small that all nodes can be made children of the 

root node. The catch in that is that the number of children of the root node is 

decided by the remainder class modulo the arity minus one of the total number 

of pages, and this may turn out to be too small to fit in the necessary number of 

pages unless the tree height is allowed to exceed the theoretical minimum. 

Experiments indicate that by placing the node with the least number of children 

at the first level instead, it is always possible to fit the tree within the minimal 

37

height (while keeping balance and minimal size), but this is a bit tricky to do when 

one does not know final number of pages from the start, and therefore the simpler 

algorithm above was chosen instead. 

4.2 Lengths and rectangles 

The default “user space” coordinate system in a PDF file, which is also the coordinate 

system used for e.g. links and destinations, uses the Postscript (or “big”) 

point as length unit. Since this is not the unit which most people are most comfortable 

with, it is useful to provide conversion from other units. 

pdf::unit_factor (array) The unit_factor array is indexed by names of length units. Its entries are the 

lengths of these units in terms of Postscript points. The conversion factors are 

those of TEX [3, Ch. 10]. 

711 namespace eval pdf { 

712 set unit_factor(bp) 1.0 

713 set unit_factor(in) 72.0 

714 set unit_factor(pt) [expr {$unit_factor(in) / 72.27}] 

715 set unit_factor(pc) [expr {$unit_factor(pt) * 12}] 

716 set unit_factor(cm) [expr {$unit_factor(in) / 2.54}] 

717 set unit_factor(mm) [expr {$unit_factor(in) / 25.4}] 

718 set unit_factor(dd) [expr {$unit_factor(pt) * 1238 / 1157}] 

719 set unit_factor(cc) [expr {$unit_factor(dd) * 12}] 

720 } 

Additional units could be added, if need be. For example in a context where the 

size of a screen pixel can be determined (and this size is unique, i.e., Tk is not 

operating against multiple screens with possibly different resolutions), it may be 

convenient to define a px or pixel entry for this unit. 

pdf::length (proc) This procedure handles conversion from a physical unit to PDF units. The syntax 

is 

pdf::length {value} {unit} 

where {unit} is a unit that has an entry in the unit_factor array and {value} is 

the numeric value in that unit. 

721 proc pdf::length {value unit} { 

722 variable unit_factor 

723 return [expr {$value * $unit_factor($unit)}] 

724 } 

pdf::length_obj (proc) This procedure combines the unit conversion of the length procedure with the 

formatting of real_obj. The syntax is 


where {unit} is a unit that has an entry in the unit_factor array, {value} is the 

numeric value in that unit, and {precision} is as for real_obj. 

725 proc pdf::length_obj {value unit args} { 

38

726 if {[llength $args]==0} then { 

727 real_obj [length $value $unit] 

728 } elseif {[llength $args]==1} then { 

729 real_obj [length $value $unit] [lindex $args 0] 

730 } else { 

731 error "Too many arguments." 

732 } 

733 } 

A data structure that is common in PDF documents is the rectangle. Below 

are some commands for operating on these in the form of a four element list 

{left} {bottom} {right} {top} 

pdf::rect_obj (proc) This procedure returns the PDF object (a PDF array) for a rectangle. The syntax 

is 


and the rectangle coordinates are encoded using real_obj with the default precision. 

734 proc pdf::rect_obj {R} { 

735 array_obj [real_obj [lindex $R 0]] [real_obj [lindex $R 1]]\ 

[real_obj [lindex $R 2]] [real_obj [lindex $R 3]] 

737 } 

pdf::int_rect_obj (proc) This procedure returns the PDF object (a PDF array) for a rectangle, after having 

rounded its coordinates to integers. The syntax is 


and the rectangle coordinates are encoded using int_obj. 

738 proc pdf::int_rect_obj {R} { 

739 array_obj [int_obj [expr {round([lindex $R 0])}]]\ 

[int_obj [expr {round([lindex $R 1])}]]\ 

[int_obj [expr {round([lindex $R 2])}]]\ 

[int_obj [expr {round([lindex $R 3])}]] 

743 } 

pdf::make_rect (proc) The make_rect procedure is a generic tool for making rectangles with specified 

dimensions. The syntax is 

pdf::make_rect {option} {value} {unit} ? + 

where {option} is one of the following: 

-width Distance from left to right 

-height Distance from bottom to top 

-left left 

-right right 

39

-top top 

-bottom bottom 

-ll {left bottom} 

-lr {right bottom} 

-ul {left top} 

-ur {right top} 

-center midpoint 

-midx x-coordinate of midpoint 

-midy y-coordinate of midpoint 

The way it works is that the list of options is processed left to right, every 

option contributes some information about the wanted rectangle, and when all 

four coordinates are known the rectangle is returned. The {value} is, depending 

on the option, either a number or a point (list of two numbers). The {unit} is the 

unit of the {value}; it defaults to bp if omitted. 

In the first processing step, horizontal and vertical information is separated 

and values are converted to bp units. Information is collected in two arrays X and 

Y, where the entries have the following meanings 

lo low coordinate (left or bottom) 

hi high coordinate (right or top) 

mid midpoint coordinate 

sz size (width or height) 

744 proc pdf::make_rect {args} { 

745 variable unit_factor 

746 lappend args -break 

747 set i 0 

748 foreach a $args { 

749 if {[array size X]>=2 && [array size Y]>=2} then {break} 

750 if {$i == 0} then { 

751 set option $a 

752 } elseif {$i == 1} then { 

753 set value $a 

754 } else { 

755 if {[info exists unit_factor($a)]} then { 

756 set factor $unit_factor($a) 

757 } else { 

758 set i 0 

759 set factor 1.0 

760 } 

761 switch -- $option { 

762 -width {set X(sz) [expr {$value * $factor}]} 

763 -height {set Y(sz) [expr {$value * $factor}]} 

764 -left {set X(lo) [expr {$value * $factor}]} 

765 -right {set X(hi) [expr {$value * $factor}]} 

766 -bottom {set Y(lo) [expr {$value * $factor}]} 

767 -top {set Y(hi) [expr {$value * $factor}]} 

40

768 -midx {set X(mid) [expr {$value * $factor}]} 

769 -midy {set Y(mid) [expr {$value * $factor}]} 

770 -center { 

771 set X(mid) [expr {[lindex $value 0] * $factor}] 

772 set Y(mid) [expr {[lindex $value 1] * $factor}] 

773 } 

774 -ll { 

775 set X(lo) [expr {[lindex $value 0] * $factor}] 

776 set Y(lo) [expr {[lindex $value 1] * $factor}] 

777 } 

778 -lr { 

779 set X(hi) [expr {[lindex $value 0] * $factor}] 

780 set Y(lo) [expr {[lindex $value 1] * $factor}] 

781 } 

782 -ul { 

783 set X(lo) [expr {[lindex $value 0] * $factor}] 

784 set Y(hi) [expr {[lindex $value 1] * $factor}] 

785 } 

786 -ur { 

787 set X(hi) [expr {[lindex $value 0] * $factor}] 

788 set Y(hi) [expr {[lindex $value 1] * $factor}] 

789 } 

790 -end { 

791 error "Insufficient information" 

792 } 

793 default { 

794 error "Unknown option: $option" 

795 } 

796 } 

797 if {$i == 0} then { 

798 set option $a 

799 } else { 

800 set i -1 

801 } 

802 } 

803 incr i 

804 } 

In the second processing step, the two pieces of information that have been specified 

are used for computing the ones that are needed. 

805 if {[array size X] > 2} then { 

806 error "More than two horizontal data given." 

807 } 

808 if {[array size Y] > 2} then { 

809 error "More than two vertical data given." 

810 } 

811 foreach a {X Y} { 

812 switch -- [lsort [array names $a]] {lo sz} { 

813 set ${a}(hi) [expr {[set ${a}(lo)] + [set ${a}(sz)]}] 

814 } {hi sz} { 

41

815 set ${a}(lo) [expr {[set ${a}(hi)] - [set ${a}(sz)]}] 

816 } {lo mid} { 

817 set ${a}(hi) [expr {2*[set ${a}(mid)] - [set ${a}(lo)]}] 

818 } {hi mid} { 

819 set ${a}(lo) [expr {2*[set ${a}(mid)] - [set ${a}(hi)]}] 

820 } {mid sz} { 

821 set ${a}(lo) [expr {[set ${a}(mid)] - 0.5*[set ${a}(sz)]}] 

822 set ${a}(hi) [expr {[set ${a}(mid)] + 0.5*[set ${a}(sz)]}] 

823 } 

824 } 

825 return [list $X(lo) $Y(lo) $X(hi) $Y(hi)] 

826 } 

pdf::standard_rect (proc) The standard_rect procedure exchanges high and low coordinates of a rectangle 

as needed to ensure that height and width are non-negative. The syntax is 

pdf::standard_rect {rect} 

and the return value is the standardized rectangle. 

827 proc pdf::standard_rect {R} { 

828 foreach {l b r t} $R {break} 

829 if {$l > $r} then {foreach {l r} [list $r $l] {break}} 

830 if {$b > $t} then {foreach {b t} [list $t $b] {break}} 

831 return [list $l $b $r $t] 

832 } 

pdf::inset_rect (proc) The inset_rect procedure moves the sides of a rectangle by specified lengths. 

There are three syntaxes 

pdf::inset_rect {rect} {amount} {unit} 

pdf::inset_rect {rect} {dx} {dy} {unit} 

pdf::inset_rect {rect} {dl} {db} {dr} {dt} {unit} 

where {rect} is the rectangle to inset and {unit} is the length unit in which the 

inset amount is specified. Positive amounts make the rectangle smaller, negative 

amounts make it larger. The result in the new rectangle. 

In the first form, all sides are moved by the same {amount}. In the second 

form, the left and right sides are moved by {dx} and the top and bottom sides 

are moved by {dy}. In the third form, the left, bottom, right, and top sides are 

moved by {dl}, {db}, {dr}, and {dt} respectively. 

833 proc pdf::inset_rect {R args} { 

834 if {[llength $args] != 2 && [llength $args] != 3 && [llength $args]\ 

!= 5} then { 

836 error "Wrong number of arguments" 

837 } 

838 set factor [length 1 [lindex $args end]] 

839 set args [lrange $args 0 end-1] 

840 set D [lrange [concat $args $args $args $args] 0 3] 


42

842 foreach a $R da $D sign {1 1 -1 -1} { 

843 lappend res [expr {$a + $da*$factor*$sign}] 

844 } 


846 } 

pdf::offset_rect (proc) The offset_rect procedure moves a rectangle in the plane, but preserves its 

width and height. The syntax is 

pdf:offset_rect {rect} {dx} {dy} {unit} ? 

where {rect} is the rectangle, {dx} and {dy} are the horizontal and vertical displacement 

amounts, and {unit} is the unit (which defaults to bp) of these amounts. 

The return value is the offset rectangle. 

847 proc pdf::offset_rect {R dx dy {unit bp}} { 

848 set factor [length 1 $unit] 


850 foreach {x y} $R { 

851 lappend res [expr {$x + $factor*$dx}] [expr {$y + $factor*$dy}] 

852 } 


854 } 

pdf::wh_rect (proc) This procedure returns the list 

{left} {bottom} {width} {height} 

that corresponds to a rectangle. The syntax is 

pdf::wh_rect {rect} 

This procedure may be used to convert a rectangle to the list of operands required 

by the re PDF operator. 

855 proc pdf::wh_rect {rect} { 

856 list [lindex $rect 0] [lindex $rect 1]\ 

[expr {[lindex $rect 2] - [lindex $rect 0]}]\ 

[expr {[lindex $rect 3] - [lindex $rect 1]}] 

859 } 

4.3 Paper sizes 

pdf::paper_rect (array) It is convenient to have some standard paper sizes readily available as rectangles. 

The paper_rect array is initialised with a couple of these. 

860 namespace eval pdf { 

861 set paper_rect(A4) [make_rect -ll {0 0} -width 210 mm -height 297 mm] 

863 set paper_rect(A4R)\ 

[make_rect -ll {0 0} -width 297 mm -height 210 mm] 

865 set paper_rect(letter)\ 

[make_rect -ll {0 0} -width 8.5 in -height 11 in] 

43

867 set paper_rect(legal)\ 

[make_rect -ll {0 0} -width 8.5 in -height 14 in] 

869 } 

870 〈/pkg〉 

4.4 A multi-page example 

The purpose of the following is mainly to generate a multipage document to test 

the page tree generation. Hence the actual document length (in pages) is factored 

out as a parameter set in the first line. 


872 set document_pages 19 

873 set F [pdf::rewrite_pdf {pages.pdf}] 

The next couple of lines determine the page layout. The rectangle paper determines 

the page size. Every page contains as graphic the rectangle frame. foot_x 

and foot_y are coordinates for the page foot. 

874 set paper $pdf::paper_rect(A4) 

875 set frame [pdf::inset_rect $paper 41 60 41 30 mm] 

876 set foot_y [expr {[lindex $frame 1] - [pdf::length 36 pt]}] 

877 set foot_x [expr {0.5*[lindex $frame 0] + 0.5*[lindex $frame 2]}] 

This is preparation for writing the page numbers. First, a font is needed. Second, 

I want the page numbers to be centered. This means I need to measure the width 

of the string to show before showing it. Luckily the digits in Times-Roman are all 

half an em wide. The 0.25*$size is thus half the width of a digit. 

878 pdf::put_obj $F "Times" [pdf::dict_obj /Type /Font /Subtype /Type1\ 

/Name /F1 /BaseFont /Times-Roman /Encoding /MacRomanEncoding] 

881 proc put_page_no {F num} { 

882 global foot_x foot_y 

883 pdf::name_resource Times $F Font [pdf::obj_ref $F "Times"] 

884 set size [pdf::length 10 pt] 

885 set thepage [format %d $num] 

886 pdf::printf $F {BT %o %r Tf 1 0 0 1 %r2 Tm %s Tj ET} $Times $size\ 

[expr {$foot_x - 0.25*$size*[string length $thepage]}] $foot_y\ 

$thepage 

889 } 

890 pdf::begin_pages $F "Pages\#" /MediaBox [pdf::rect_obj $paper] 

891 array unset Rez 

892 for {set page 1} {$page


(Outlines/prefix) 


(Outlines/last) 


(Outlines/stack) 


(Outline/〈string〉) 


(Outline/parent) 


(Outline/first) 


(Outline/last) 


(Outline/count) 


(Outline/prev) 


(Outline/open) 



904 /Pages [pdf::obj_ref $F $Pages]] 



5 Document outline 

The “outline” of a PDF document is the table of contents that one often sees in a 

separate pane next to the pane actually showing some page of the document. The 

procedures below handle building the data structure encoding this, while leaving 

it to the user to provide the links to actual document content. 

5.1 Low-level stuff 

As with the Pages tree, building an outline tree involves automatically creating 

nodes for the tree. (This node creation could have been made explicit, but there 

doesn’t seem to be much point in that.) To prevent that the labels of these clash 

with the labels of other objects, each outline node has a special prefix which 

is stored in the Outlines/prefix entry of the file array. The rest of the label 

is a decimal number which is assigned sequentially. The most recently assigned 

number is kept in the Outlines/last entry. 

The information kept track of for the building of an outline tree is distinguished 

by scope as belonging to one of two scopes. Things that are relevant only to the 

current position in the tree are kept in Outline/〈string〉 entries, whereas things 

that are more generally relevant are kept in Outlines/〈string〉 entries (note the 

extra s). There is a stack in the Outlines/stack entry onto which the current 

position can be pushed and later popped off. This stack is a list where the last 

element is topmost. The elements themselves are the results of an array get for 

all Outline/〈string〉 entries in the file array. 

The current state of the tree construction is, in a sense, located slighly below the 

level where nodes are being added. The links between this level and its parent are 

stored in the Outline/parent, Outline/first, and Outline/last entries in the 

file array. All three are numbers which when appended to the prefix produce the 

node labels. 

Outline/parent is the parent node, Outline/first is the first child of the 

parent, and Outline/last is the (currently) last child of the parent. 

Outline/count is the number of children of the parent, including any children 

of open child nodes. If this is zero then the current level in the outline hierarchy 

is empty, which amongst other things implies that Outline/first and 

Outline/last has not been initialised. 

Outline/prev is, if it is set, the number of the predecessor (in the same level) 

of the node currently being constructed. It should not be set when the node is the 

first node on that level. 

45


(Outline//〈name〉) 

pdf::put_outline_node 

(proc) 

pdf::outline_node_set 

(proc) 

Outline/open is a boolean for whether the current node should be open (i.e., 

its children, if it will get any, will by default be visible). 

Explicit PDF object for outline dictionaries are also stored in Outline/ entries 

of the file array. In this case, the index suffix is the PDF name object for the 

dictionary key. 

The put_outline_node procedure outputs the current node of an outline to file. 

The syntax is 

pdf::put_outline_node {file} {option} {value} ∗ 

where {file} is the identifier of the PDF file. An {option} {value} is a pair of PDF 

objects, where the first is a name object. These objects will be placed in the PDF 

dictionary object for this node, possibly overriding a previously specified pair with 

the same {option}. There is no particular return value. 

The procedure clears the Outline//〈name〉 part of the file array. It does 

not generate any /First, /Last, or /Count items. It does not increment 

Outline/count, because that is the responsibility of the procedure that allocated 

a node number for this node. 

907 〈∗pkg〉 

908 proc pdf::put_outline_node {F args} { 


910 foreach name [array names A Outline//*] { 

911 set N([string range $name 8 end]) $A($name) 

912 } 

913 foreach {name value} $args { 

914 if {[string match /* $name]} then { 

915 set N($name) $value 

916 } else { 

917 error "Bad option ’$name’" 

918 } 

919 } 

920 if {[info exists A(Outline/prev)]} then { 

921 set N(/Prev) [obj_ref $F $A(Outlines/prefix)$A(Outline/prev)] 

922 } 

923 set N(/Parent) [obj_ref $F $A(Outlines/prefix)$A(Outline/parent)] 

924 put_obj $F $A(Outlines/prefix)$A(Outline/last) [ 

925 eval [linsert [array get N] 0 dict_obj] 

926 ] 

927 array unset A Outline//* 

928 } 

The outline_node_set procedure sets fields for the current outline node. The 

syntax is one of 

pdf::outline_node_set {file} {args} 

pdf::outline_node_set {file} {option} {value} ∗ 

46

where {file} is the identifier of the PDF file. The first form is merely a variant 

on the second form, where the {args} is treated as a list of the arguments that 

should have followed the {file}. 

An {option} {value} is either a pair of PDF objects, where the first is a name 

object, or 


The -open option sets the open state of the current node. Other options set an 

entry in the dictionary object for the current node. There is no particular return 

value. 

929 proc pdf::outline_node_set {F args} { 


931 if {[llength $args] == 1} then {set args [lindex $args 0]} 

932 foreach {option value} $args { 

933 switch -glob -- $option /* { 

934 set A(Outline/$option) $value 

935 } -open { 

936 set A(Outline/open) $value 


938 error "Bad option ’$option’" 

939 } 

940 } 

941 } 

pdf::outline_item (proc) The outline_item procedure creates a new outline node at the current level. If 

there already was a current outline node then that is output first. The syntax is 

pdf::outline_item {file} {title} {option} {value} ∗ 

where {file} is the identifier of the PDF file and {title} is the title of the new 

outline node. An {option} {value} is either a pair of PDF objects, where the first 

is a name object, or 


The -open option sets the open state of the new child node. The default for this 

option is 0. The PDF objects will be placed in the dictionary object for the new 

child node. There is no particular return value. 

942 proc pdf::outline_item {F title args} { 


The first step deals with whatever should hold the link to the new node, usually 

the previous current node, which will be output. This involves allocating a number 

for the new node and therefore also incrementing Outline/count. 

944 incr A(Outlines/last) 

945 if {$A(Outline/count)} then { 

946 put_outline_node $F /Next\ 

[obj_ref $F $A(Outlines/prefix)$A(Outlines/last)] 

47

pdf::outline_begingroup 

(proc) 

pdf::outline_endgroup 

(proc) 

948 set A(Outline/prev) $A(Outline/last) 

949 } else { 

950 set A(Outline/first) $A(Outlines/last) 

951 } 

952 incr A(Outline/count) 

The second step is merely some entry initialisation for the new node. 

953 set A(Outline/last) $A(Outlines/last) 

954 set A(Outline//Title) [text_obj $title] 

955 set A(Outline/open) 0 

956 outline_node_set $F $args 

957 } 

The outline_begingroup procedure pushes the current state onto the stack and 

makes the current node the parent for the new current state. The syntax is 

pdf::outline_begingroup {file} {option} {value} ∗ 

where {file} is the identifier of the PDF file. An {option} {value} is either a pair 

of PDF objects, where the first is a name object, or 


The -open option sets the open state of the parent node. The default for this 

option is 0. The PDF objects will be placed in the dictionary object for the 

parent node. There is no particular return value. 

958 proc pdf::outline_begingroup {F args} { 


960 if {!$A(Outline/count)} then { 

961 error "There is no current node to make the parent of a new\ 

group." 

963 } 


965 lappend A(Outlines/stack) [array get A Outline/*] 

966 set parent $A(Outline/last) 

967 array unset A Outline/* 

968 set A(Outline/parent) $parent 

969 set A(Outline/count) 0 

970 } 

The outline_endgroup procedure ends the current level of outline nodes and pops 

one element off the stack, thus turning the current parent back into the current 

node, as it was before the matching outline_endgroup. The syntax is 

pdf::outline_endgroup {file} {option} {value} ∗ 

where {file} is the identifier of the PDF file. An {option} {value} is either a pair 

of PDF objects, where the first is a name object, or 


48


(Outlines/levels) 

pdf::outline_heading 

(proc) 

The -open option can be used to override the open/closed state of the node, and 

can thus control whether the level of outline items that was ended will be open by 

default. The PDF objects will be placed in the dictionary object for the current 

node popped off the stack, i.e., the previous parent node. 

971 proc pdf::outline_endgroup {F args} { 


973 set count $A(Outline/count) 

974 if {$count} then { 

975 put_outline_node $F 

976 lappend args /First [ 

977 obj_ref $F $A(Outlines/prefix)$A(Outline/first) 

978 ] /Last [ 

979 obj_ref $F $A(Outlines/prefix)$A(Outline/last) 

980 ] 

981 } 

982 array unset A Outline/* 

983 array set A [lindex $A(Outlines/stack) end] 

984 set A(Outlines/stack) [lreplace $A(Outlines/stack) end end] 


986 if {$count} then { 

987 if {$A(Outline/open)} then { 

988 set A(Outline//Count) [int_obj $count] 

989 incr A(Outline/count) $count 

990 } else { 

991 set A(Outline//Count) [int_obj [expr {-$count}]] 

992 } 

993 } 

994 } 

5.2 An outline of headings 

One of the most common models for document structuring is to have a family of 

commands which say “make a level n heading” and are supposed to be used at the 

beginning of each section/subsection/. . . in the document. This model is useful 

also for constructing a table of contents such as the outline. 

The Outlines/levels entry of the file array is the list of heading levels nested 

around the current outline node, with the last element being the level of that node. 

The list is empty before the first node has been inserted. Apart from that situation, 

the list length should always be one greater than that of the Outlines/stack entry. 

The outline_heading procedure adds a new heading to the document outline. 

The syntax is 

pdf::outline_heading {file} {level} {title} {option} {value} ∗ 

where {file} is the identifier of the PDF file, {level} is the nominal level of this 

item, and {title} is the title. An {option} {value} is either a pair of PDF objects, 

where the first is a name object, or 

49


The -open option controls whether this item will be open by default, i.e., if its 

subitems (if there will be any) should be shown. It defaults to false (closed). 

The PDF objects will be placed in the dictionary object for the new item. These 

are what one should use to specify a destination or equivalent for the outline item. 

The {level} is relative, and can be an arbitrary string. The way it is used 

is that if {level} is greater than the current level, then a new level is begun. 

Else if {level} is greater than the previous level, the item is a sibling of the last 

item and the current level is updated. Otherwise the current level is ended and 

the issue is reexamined. This dynamically adapts to the set of {level}s actually 

used in a document, even if these are not consecutive. It also gracefully copes 

with inconsistencies such as forgetting some heading level at the beginning of a 

document. 

There is no particular return value. 

995 proc pdf::outline_heading {F level title args} { 


997 if\ 

{[llength $A(Outlines/levels)] > [llength $A(Outlines/stack)] + 1}\ 

then { 

999 set A(Outlines/levels)\ 

[lrange $A(Outlines/levels) 0 [llength $A(Outlines/stack)]] 

1001 } 

1002 while { 

1003 $level 1 

1005 } { 

1006 outline_endgroup $F 

1007 set A(Outlines/levels) [lreplace $A(Outlines/levels) end end] 

1008 } 

1009 if {$A(Outline/count) && $level > [lindex $A(Outlines/levels) end]}\ 

then { 

1011 lappend A(Outlines/levels) $level 

1012 outline_begingroup $F 

1013 } else { 

1014 set A(Outlines/levels)\ 

[lreplace $A(Outlines/levels) end end $level] 

1016 } 

1017 eval [linsert $args 0 outline_item $F $title] 

1018 } 

pdf::begin_outline (proc) The begin_outline procedure initialises the outline system for a PDF file. The 

syntax is 

pdf::begin_outline {file} {prefix} 

where {file} is the identifier of the PDF file and {prefix} is a prefix that will be 

used for all labels for indirect objects that the outline system creates. There is no 

particular return value. 

1019 proc pdf::begin_outline {F prefix} { 

50


1021 set A(Outlines/prefix) $prefix 

1022 set A(Outlines/last) 1 

1023 set A(Outlines/stack) [list] 

1024 set A(Outlines/levels) [list] 

1025 set A(Outline/parent) 1 

1026 set A(Outline/count) 0 

1027 } 

pdf::end_outline (proc) The end_outline procedure finishes off the outline tree for a PDF file and returns 

the label of the root node. The syntax is 

pdf::end_outline {file} 

where {file} is the identifier of the PDF file. 

1028 proc pdf::end_outline {F} { 


1030 while {[llength $A(Outlines/stack)]} { 

1031 outline_endgroup $F 

1032 } 

1033 put_outline_node $F 

1034 set label "$A(Outlines/prefix)1" 

1035 set call [list dict_obj /Type /Outlines] 

1036 if {[info exists A(Outline/first)]} then { 

1037 lappend call /First [ 

1038 obj_ref $F $A(Outlines/prefix)$A(Outline/first) 

1039 ] /Last [ 

1040 obj_ref $F $A(Outlines/prefix)$A(Outline/last) 

1041 ] /Count [int_obj $A(Outline/count)] 

1042 } 

1043 put_obj $F $label [eval $call] 

1044 return $label 

1045 } 

1046 〈/pkg〉 

5.3 An outline example 

The purpose of the following is to test the outline generation. The structure, 

which is perhaps somewhat atypical, is to first generate all the document contents 

and then generate an outline with links into the document. 


1048 set F [pdf::rewrite_pdf {outline.pdf}] 

The idea for the page contents is that this should consist of the numbers 1–12, 

each rather large, on a page of its own, and in a different font. 

1049 pdf::begin_pages $F "Pages\#"\ 

1050 /MediaBox [pdf::rect_obj $pdf::paper_rect(A4)] 

1051 set page 1 

1052 foreach font { 

51

1053 Times-Roman Helvetica Courier 

1054 Times-Bold Helvetica-Bold Courier-Bold 

1055 Times-Italic Helvetica-Oblique Courier-Oblique 

1056 Times-BoldItalic Helvetica-BoldOblique Courier-BoldOblique 

1057 } { 

1058 pdf::put_obj $F $font [pdf::dict_obj /Type /Font /Subtype /Type1\ 

/BaseFont [pdf::name_obj $font] /Encoding /MacRomanEncoding] 

1061 pdf::begin_contents "" $F "Page $page contents" 

1062 pdf::name_resource fid $F Font [pdf::obj_ref $F $font] 

1063 pdf::printf $F {BT %o %r Tf 1 0 0 1 %r2 Tm %s Tj ET} $fid\ 

[pdf::length 10 cm] [pdf::length 5 cm] [pdf::length 10 cm] $page 

1067 pdf::end_contents Rez $F 

1068 pdf::shipout $F "Page $page" /Contents\ 

[pdf::obj_ref $F "Page $page contents"] /Resources\ 

[pdf::resource_dict_obj Rez] 

1071 unset Rez 

1072 incr page 

1073 } 

1074 set Pages [pdf::end_pages $F] 

1075 pdf::begin_outline $F "TOC\#" 

1076 pdf::outline_heading $F 1 "Numeric" /Dest [ 

1077 pdf::array_obj [pdf::obj_ref $F "Page 1"] /Fit 

1078 ] 

1079 for {set page 1} {$page

1104 pdf::array_obj [pdf::obj_ref $F "Page $page"] /XYZ\ 

[pdf::null_obj] [pdf::null_obj] [pdf::real_obj $page] 

1106 ] 


1108 } 

1109 pdf::outline_heading $F 1 "Russian" /Dest [ 

1110 pdf::array_obj [pdf::obj_ref $F "Page 1"] /FitV\ 

[pdf::length_obj 5 cm] 

1112 ] 

1113 set page 1 

1114 foreach {Ruslish name} { 

1115 Odin \u041E\u0434\u0438\u043D 

1116 Dva \u0414\u0432\u0430 

1117 Tri \u0422\u0440\u0438 

1118 !Cetyre \u0427\u0435\u0442\u044B\u0440\u0435 

1119 P!ath \u041F\u044F\u0442\u044C 

1120 !Sesth \u0428\u0435\u0441\u0442\u044C 

1121 Semh \u0421\u0435\u043C\u044C 

1122 Vosemh \u0412\u043E\u0441\u0435\u043C\u044C 

1123 Dev!ath \u0414\u0435\u0432\u044F\u0442\u044C 

1124 Des!ath \u0414\u0435\u0441\u044F\u0442\u044C 

1125 Odinnadcath 

1126 \u041E\u0434\u0438\u043D\u043D\u0430\u0434\u0446\u0430\u0442\u044C 

1127 Dvenadcath 

1128 \u0414\u0432\u0435\u043D\u0430\u0434\u0446\u0430\u0442\u044C 

1129 } { 

1130 pdf::outline_heading $F 2 $name /Dest [ 

1131 pdf::array_obj [pdf::obj_ref $F "Page $page"] /XYZ\ 

[pdf::null_obj] [pdf::null_obj] [pdf::null_obj] 

1133 ] 


1135 } 

1136 set outline [pdf::end_outline $F] 



1139 /Pages [pdf::obj_ref $F $Pages]\ 

1140 /PageMode /UseOutlines\ 

1141 /Outlines [pdf::obj_ref $F $outline]] 



References 

[1] Adobe Systems Incorporated: Portable Document Format Reference 

Manual, version 1.3 (second edition), Addison–Wesley, 1999; ISBN 0- 

201-61588-6; http://partners.adobe.com/public/developer/en/pdf/ 

PDFReference13.pdf. 

53

[2] Adobe Systems Incorporated: PDF Reference, fourth edition: Adobe 

Portable Document Format version 1.5.; http://partners.adobe.com/ 

public/developer/en/pdf/PDFReference15 v5.pdf. 

[3] Donald E. Knuth, Duane Bibby (illustrations): The TEXbook, Addison-Wesley, 

1991, ISBN 0-201-13448-9; also volume A of Computers and typesetting, 

ISBN 0-201-13447-0. 

Index 

All numbers in this index are page numbers. Underlined entries refer to places 

where the item in question is defined. 

A 

array_obj (proc), pdf namespace 4, 15 

B 

begin_contents (proc), pdf namespace 

. . . . . . . . . . . . . . . . 5, 25 

begin_outline (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 6, 50 

begin_pages (proc), pdf namespace 6, 33 

begin_stream (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 4, 18 

boolean_obj (proc), pdf namespace 4, 12 

C 

close_pdf (proc), pdf namespace 2, 21 

D 

date_obj (proc), pdf namespace . 4, 16 

dict_obj (proc), pdf namespace . 4, 15 

E 

end_contents (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 5, 25 

end_outline (proc), pdf namespace 6, 51 

end_pages (proc), pdf namespace 6, 34 

end_stream (proc), pdf namespace 4, 18 

F 

file〈num〉 (array), pdf namespace . 17 

?〈reference label〉 . . . . . . . . . . 18 

!〈reference label〉 . . . . . . . . . . 17 

backlog . . . . . . . . . . . . . . . . 19 

current_stream . . . . . . . . . . . 18 

last_object_num . . . . . . . . . . 17 

Outline//〈name〉 . . . . . . . . . 46 

Outline/count . . . . . . . . . . . 45 

54 

Outline/first . . . . . . . . . . . 45 

Outline/last . . . . . . . . . . . . 45 

Outline/open . . . . . . . . . . . . 45 

Outline/parent . . . . . . . . . . . 45 

Outline/prev . . . . . . . . . . . . 45 

Outline/〈string〉 . . . . . . . . . . 45 

Outlines/last . . . . . . . . . . . 45 

Outlines/levels . . . . . . . . . . 49 

Outlines/prefix . . . . . . . . . . 45 

Outlines/stack . . . . . . . . . . . 45 

Pages/arity . . . . . . . . . . . . . 32 

Pages/attributes . . . . . . . . . 32 

Pages/last . . . . . . . . . . . . . . 32 

Pages/prefix . . . . . . . . . . . . 32 

Pages/〈num〉 . . . . . . . . . . . . . 32 

Resources/〈type〉 . . . . . . . . . . 25 

H 

has_resource? (proc), pdf namespace 26 

hexstring_obj (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 3, 13 

I 

inset_rect (proc), pdf namespace 10, 42 

int_obj (proc), pdf namespace . . 3, 12 

int_rect_obj (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 11, 39 

L 

length (proc), pdf namespace . . . 9, 38 

length_obj (proc), pdf namespace 9, 38 

M 

make_pages_nodes (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . 34 

make_rect (proc), pdf namespace 10, 39

N 

name_obj (proc), pdf namespace . 4, 14 

name_resource (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 5, 26 

null_obj (proc), pdf namespace . 4, 16 

O 

obj_ref (proc), pdf namespace . . 2, 17 

offset_rect (proc), pdf namespace . 

. . . . . . . . . . . . . . . . . . . . 10, 43 

outline_begingroup (proc), pdf 

namespace . . . . . . . . . . . . 7, 48 

outline_endgroup (proc), pdf namespace 

. . . . . . . . . . . . . . . . 7, 48 

outline_heading (proc), pdf namespace 

. . . . . . . . . . . . . . . . 7, 49 

outline_item (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 7, 47 

outline_node_set (proc), pdf namespace 

. . . . . . . . . . . . . . . . 7, 46 

P 

paper_rect (array), pdf namespace . 

. . . . . . . . . . . . . . . . . . . . 11, 43 

precision (var.), pdf namespace . 3, 12 

printf (proc), pdf namespace . . . 8, 31 

put_obj (proc), pdf namespace . . 2, 19 

55 

put_outline_node (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . 46 

R 

real_obj (proc), pdf namespace . 3, 12 

rect_obj (proc), pdf namespace . 11, 39 

require_procsets (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . 28 

resource_dict_obj (proc), pdf namespace 

. . . . . . . . . . . . . . . . 5, 24 

rewrite_pdf (proc), pdf namespace 2, 20 

S 

shipout (proc), pdf namespace . . 6, 33 

sprintf (proc), pdf namespace . . 8, 29 

standard_rect (proc), pdf namespace 

. . . . . . . . . . . . . . . . . . . . 11, 42 

string_obj (proc), pdf namespace 3, 12 

T 

text_obj (proc), pdf namespace . 4, 14 

U 

unit_factor (array), pdf namespace 38 

W 

wh_rect (proc), pdf namespace . . 11, 43

A basic PDF writer in Tcl - Index of

Create successful ePaper yourself

Delete template?

Save as template?