Examples
Every document below is written by one example script of the source tree — make examples builds all of them, and make publish-examples puts the results here. The PDFs are the untouched output of the current trunk: what the package writes is what you download. Each row links the finished PDF and the script that wrote it; the scripts are the tutorial, commented for reading.
93 documents from 84 scripts, and six of them depend on the machine that builds them rather than on the package: 11.01-tk-canvas needs Tk, which is not a prerequisite of tclpdf; 02.18-noto-color-emoji needs the 25 MB Noto Color Emoji face, which carries a licence of its own and is therefore neither shipped nor versioned here; 02.18-apple-color-emoji is written from Apple Color Emoji, which ships with macOS and exists nowhere else; and the three timestamp examples 08.06 to 08.08 ask a timestamp authority — a public one over the network, or, offline, a throwaway one built with openssl, so only a machine with neither skips the stamps, and 08.08 needs openssl in any case for its signature. Each of them prints one line, writes no document and lets the run go on — the same rule as everywhere in this tree: a missing thing is a skip, never a failure. A machine without any of them builds 87.
| what it shows | script | |
|---|---|---|
| 00.01-hello-world.pdf | the smallest complete program | 00.01-hello-world.tcl |
| 00.02-hello-world-svg.pdf | the same, with a drawing on the page - vectors, not pixels | 00.02-hello-world-svg.tcl |
| 00.03-error-codes.pdf | what the package refuses, and how a script handles it | 00.03-error-codes.tcl |
| 01.01-shapes.pdf | shapes, lines, arcs and clipping | 01.01-shapes.tcl |
| 01.02-colour.pdf | colour spaces | 01.02-colour.tcl |
| 01.03-text-layout.pdf | text layout | 01.03-text-layout.tcl |
| 01.04-attachments.pdf | attachments | 01.04-attachments.tcl |
| 01.05-forms.pdf | form XObjects: draw once, place many times | 01.05-forms.tcl |
| 01.06-stamp.pdf | a diagonal stamp | 01.06-stamp.tcl |
| 01.07-extension.pdf | extending the package from outside | 01.07-extension.tcl |
| 01.08-textflow.pdf | text that flows | 01.08-textflow.tcl |
| 01.09-text-on-path.pdf | text along a path | 01.09-text-on-path.tcl |
| 01.10-hyphen-and-leader.pdf | soft hyphens and leader rows | 01.10-hyphen-and-leader.tcl |
| 01.11-type-area.pdf | the type area, and text that reaches the end of a page | 01.11-type-area.tcl |
| 01.12-render-modes.pdf | filled, outlined, both, or drawn nowhere at all | 01.12-render-modes.tcl |
| 01.13-layers.pdf | one sheet that is two invoices, and a draft stamp over both | 01.13-layers.tcl |
| 01.14-hyphenation.pdf | the same paragraph twice, justified, with hyphenation off and on | 01.14-hyphenation.tcl |
| 01.15-text-fit.pdf | the same line fitted into four different boxes | 01.15-text-fit.tcl |
| 01.16-prepress-control.pdf | a press control strip, and the overprint switch no reader shows | 01.16-prepress-control.tcl |
| 02.01-embedding.pdf | embedding a TrueType face | 02.01-embedding.tcl |
| 02.02-languages-embedded.pdf | the twelve lines set in DejaVu Sans, embedded and subset | 02.02-languages.tcl |
| 02.02-languages-small.pdf | the same lines in Roboto - a fifth of the font file, and no line lost | 02.02-languages.tcl |
| 02.02-languages-standard.pdf | the same lines in Helvetica, a standard face: what 256 characters through WinAnsiEncoding cannot reach | 02.02-languages.tcl |
| 02.03-font-families.pdf | five families in one document | 02.03-font-families.tcl |
| 02.04-missing-glyphs.pdf | when the face has no glyph for a character | 02.04-missing-glyphs.tcl |
| 02.05-kerning.pdf | pair kerning | 02.05-kerning.tcl |
| 02.06-ligatures.pdf | standard ligatures | 02.06-ligatures.tcl |
| 02.07-type1.pdf | embedding a Type 1 font | 02.07-type1.tcl |
| 02.08-opentype.pdf | embedding an OpenType font with CFF outlines | 02.08-opentype.tcl |
| 02.09-writing-systems.pdf | writing systems, symbols and a colour font that is not | 02.09-writing-systems.tcl |
| 02.10-variable-fonts.pdf | one variable font, many instances | 02.10-variable-fonts.tcl |
| 02.11-type3.pdf | a font whose glyphs are drawn: the check boxes are text | 02.11-type3.tcl |
| 02.12-vocalised-rtl.pdf | Hebrew with nikud and Arabic with harakat, each mark on its anchor | 02.12-vocalised-rtl.tcl |
| 02.13-marks-on-a-path.pdf | combining marks that stay on their letters along a curve | 02.13-marks-on-a-path.tcl |
| 02.14-colour-font.pdf | a COLR colour font, drawn as a Type 3 font and set like text | 02.14-colour-font.tcl |
| 02.15-vertical-writing.pdf | Japanese set downwards, one column per call | 02.15-vertical-writing.tcl |
| 02.16-bare-cff.pdf | a bare CFF face, with no sfnt wrapper around it | 02.16-bare-cff.tcl |
| 02.17-colour-font-v1.pdf | COLR version 1: a paint graph per glyph, with gradients and compositing | 02.17-colour-font-v1.tcl |
| 02.18-noto-color-emoji.pdf | an emoji face off the shelf, and the character sequences it draws as one glyph each | 02.18-noto-color-emoji.tcl |
| 02.18-apple-color-emoji.pdf | the same three pages in Apple Color Emoji: pictures for paths, morx for GSUB | 02.18-noto-color-emoji.tcl |
| 03.01-images.pdf | images, gradients and patterns | 03.01-images.tcl |
| 03.02-gradients.pdf | gradients and tiling patterns | 03.02-gradients.tcl |
| 03.03-svg.pdf | SVG as real vectors | 03.03-svg.tcl |
| 03.04-barcodes.pdf | barcodes through tzint | 03.04-barcodes.tcl |
| 03.05-svg-text.pdf | text inside a drawing, in an embedded face | 03.05-svg-text.tcl |
| 03.06-image-icc.pdf | the ICC profile inside a picture, kept and dropped | 03.06-image-icc.tcl |
| 03.06-image-icc-pdfa.pdf | a colour photograph under a grey PDF/A intent | 03.06-image-icc.tcl |
| 03.07-image-masks.pdf | one picture painted in three colours, and a photograph faded by another | 03.07-image-masks.tcl |
| 03.07-image-masks-pdfa.pdf | a stencil under a grey PDF/A intent | 03.07-image-masks.tcl |
| 03.08-image-tiff.pdf | TIFF as a third image format, one compression per strip | 03.08-image-tiff.tcl |
| 03.08-image-tiff-pdfa.pdf | the same pictures in an archivable document | 03.08-image-tiff.tcl |
| 03.09-image-fit.pdf | a picture fitted into a box: contain and cover, with the anchors | 03.09-image-fit.tcl |
| 03.10-svg-clip.pdf | clip paths and masks in a drawing | 03.10-svg-clip.tcl |
| 04.01-table-basics.pdf | table basics | 04.01-table-basics.tcl |
| 04.02-table-paging.pdf | a table across pages | 04.02-table-paging.tcl |
| 04.03-table-spans.pdf | spans, column widths, horizontal breaking | 04.03-table-spans.tcl |
| 04.04-table-hyphenation.pdf | a narrow column with and without hyphenation, every figure read back from the layout | 04.04-table-hyphenation.tcl |
| 05.01-zugferd-minimum.pdf | a ZUGFeRD invoice, profile MINIMUM | 05.01-zugferd-minimum.tcl |
| 05.02-zugferd-en16931.pdf | a ZUGFeRD invoice, profile EN 16931 | 05.02-zugferd-en16931.tcl |
| 05.03-navigation.pdf | links and bookmarks | 05.03-navigation.tcl |
| 05.04-pdfa.pdf | PDF/A on its own, without an invoice | 05.04-pdfa.tcl |
| 05.05-tagged.pdf | a tagged document | 05.05-tagged.tcl |
| 05.06-lists-and-artifacts.pdf | lists, and what does not belong in the tree | 05.06-lists-and-artifacts.tcl |
| 05.07-accessible.pdf | a document that may call itself accessible | 05.07-accessible.tcl |
| 05.08-ua2-wtpdf.pdf | PDF/UA-2 and Well-Tagged PDF, on the 2.0 path | 05.08-ua2-wtpdf.tcl |
| 05.09-pdfa-cmyk.pdf | PDF/A with a CMYK output intent | 05.09-pdfa-cmyk.tcl |
| 05.10-pdfa-grey.pdf | PDF/A with a grey output intent | 05.10-pdfa-grey.tcl |
| 05.11-pdfa-srgb-openicc.pdf | the same page under the default sRGB profile (OpenICC) | 05.11-pdfa-srgb-openicc.tcl |
| 05.12-pdfa-srgb2014.pdf | the same page under the ICC's sRGB2014 profile | 05.12-pdfa-srgb2014.tcl |
| 05.13-order-x.pdf | an Order-X purchase order, profile COMFORT | 05.13-order-x.tcl |
| 05.14-weakly-structured.pdf | the generic H: a weakly structured document | 05.14-weakly-structured.tcl |
| 06.01-pdf-import.pdf | a page of an existing PDF, taken over as a form | 06.01-pdf-import.tcl |
| 06.02-incremental-update.pdf | a finished file continued twice, byte for byte intact | 06.02-incremental-update.tcl |
| 06.03-pdf-info.pdf | what a finished file says about itself | 06.03-pdf-info.tcl |
| 07.01-encryption.pdf | encryption | 07.01-encryption.tcl |
| 07.02-permissions.pdf | a document that opens for everyone and still says no | 07.02-permissions.tcl |
| 08.01-signature.pdf | a digital signature, made while the document was written | 08.01-signature.tcl |
| 08.01-signature-two-stage.pdf | the same signature, prepared here and made elsewhere | 08.01-signature.tcl |
| 08.02-signature-visible.pdf | a signature you can see: field and appearance | 08.02-signature-visible.tcl |
| 08.02-signature-visible-two-stage.pdf | the visible one, prepared here and signed elsewhere | 08.02-signature-visible.tcl |
| 08.03-second-signature.pdf | one document, two signatures, the first still valid | 08.03-second-signature.tcl |
| 08.04-zugferd-signed.pdf | an electronic invoice, approved and countersigned | 08.04-zugferd-signed.tcl |
| 08.05-signature-accessible.pdf | a visible signature inside the structure tree of a PDF/UA-1 document | 08.05-signature-accessible.tcl |
| 08.06-doctimestamp.pdf | a document timestamp (RFC 3161) - it proves when, not who | 08.06-doctimestamp.tcl |
| 08.07-pdfa-doctimestamp.pdf | the stamped archive file: still PDF/A-3B, because the stamp only adds | 08.07-pdfa-doctimestamp.tcl |
| 08.08-signature-doctimestamp.pdf | signed, then stamped: the token fixes the moment by which the signature existed | 08.08-signature-doctimestamp.tcl |
| 09.01-form-fields.pdf | the first interactive form: text fields, single and multi-line | 09.01-form-fields.tcl |
| 09.02-form-application.pdf | a complete fillable form of every field type there is | 09.02-form-application.tcl |
| 09.02-form-application-record.pdf | the same sheet filled in, read-only, as an archivable record | 09.02-form-application.tcl |
| 09.03-form-read.pdf | the other direction: what stands in a finished form, read in pure Tcl | 09.03-form-read.tcl |
| 09.04-form-design.pdf | the same field types in an appearance of their own - the standard fixes none of it | 09.04-form-design.tcl |
| 10.01-annotations.pdf | notes, stamps and the four ways of marking a passage | 10.01-annotations.tcl |
| 11.01-tk-canvas.pdf | what stands on a Tk canvas, put on paper as paths rather than as a picture of the screen | 11.01-tk-canvas.tcl |
The hybrid invoices (05.01, 05.02, 05.13 and the signed one, 08.04) carry their machine-readable XML as an attachment — save the file and look, the XML layer is the point.
The signed examples
Eight of the documents above carry a digital signature, and every reader will report the same thing about all eight: the document has not been changed since it was signed, and the issuer of the certificate is not trusted. Both statements are correct. The certificates are made by the example itself, in a temporary directory, and deleted the moment it is done — there is no authority behind them and there is not meant to be. What the files demonstrate is the mechanism, not an identity: /ByteRange covering the whole file except the signature, the digest over exactly those bytes, and the signature written into the space reserved for it.
Two pairs and four singles: the pairs differ in when the key is used. 08.01-signature.pdf and 08.02-signature-visible.pdf are signed while they are written; their -two-stage counterparts are written with the room still empty and signed afterwards, the way a card reader, an HSM or a signing service works. The visible pair additionally shows the field itself: the mark in it is the signature of the German identity card specimen, an official work and free of copyright, drawn as vectors rather than pasted as a picture. The remaining two go further: 08.03-second-signature.pdf carries a second signature appended as an incremental update, so the first one keeps every byte it covers, and 08.04-zugferd-signed.pdf is the electronic invoice, approved and countersigned. 08.05-signature-accessible.pdf is the third single: a visible signature in a tagged PDF/UA-1 document, its widget described by /TU and /Contents and enclosed in a Form structure element, joined to the widget by an object reference and a /StructParent back to it. It is the rectangle that decides that, not the claim: an invisible signature — /Rect [0 0 0 0], which is what 08.01 writes — stays out of the tree and is an artifact wherever the document is tagged at all, as ISO 14289-2 (8.9.2.4.13) requires of a widget without extent. 08.01 itself is untagged and carries no structure tree, so there is nothing there to be an artifact in; the contrast is between the two rectangles, not between the two files. The fourth single, 08.08-signature-doctimestamp.pdf, belongs to the timestamps below.
Three documents carry a document timestamp besides: 08.06-doctimestamp.pdf is nothing but the stamp — no key of the author's involved, the token proves when the bytes existed and deliberately not who wrote them; 08.07-pdfa-doctimestamp.pdf is the stamped archive file, still PDF/A-3B; and 08.08-signature-doctimestamp.pdf carries the stamp on top of its signature, so the token also fixes the moment by which that signature existed — the base pattern of long-term validation. The published files are stamped by Open TSA, a public RFC 3161 authority: pdfsig lists the stamp field and its coverage, and openssl ts -verify checks the token itself.
Check any of them yourself:
pdfsig 08.01-signature.pdf
qpdf --check 08.02-signature-visible.pdf
pdfsig 08.08-signature-doctimestamp.pdf
The passwords of the encrypted examples
Two of the documents above are encrypted, and both print their passwords on the page — an example nobody can open is an example nobody reads. A real document does not carry them.
| Document | user password | owner password | what it shows |
|---|---|---|---|
07.01-encryption.pdf |
read |
full |
both passwords set: the file asks for one before it opens |
07.02-permissions.pdf |
(empty) | full |
the pattern outgoing documents use: it opens without asking, and still refuses to be changed |
Try them with qpdf --password=full --show-encryption <file>, or read the text without any password at all from the second one: pdftotext 07.02-permissions.pdf -. That difference is the lesson of the pair — a file that opens for everyone hands its key to everyone, and its permission bits are a statement of intent a conforming reader honours, not a lock.
The embedding of Apple Color Emoji
02.18-apple-color-emoji.pdf is written from face 0 of /System/Library/Fonts/Apple Color Emoji.ttc, and it embeds that face under the rule the face itself states: its OS/2 fsType is 4, bit 2 of the OpenType specification, which the package puts into words as preview and print only — embedded for viewing and printing, the document counting as read-only, no editing. What the file carries are the PNG strikes of that face, one bitmap per glyph, set as a Type 3 font; no outline is embedded. The other half of the pair, 02.18-noto-color-emoji.pdf, is written from Noto Color Emoji, which is under the SIL Open Font License 1.1.