Annotations set how a page is first shown and add links and metadata; hidden text is
the text of a scanned page, usually from OCR, laid out so that it can be searched and
selected. The DjVu Reference names these chunks but leaves most of their syntax to
DjVuLibre, whose djvused tool documents it; this page follows both.
Coordinates are in page pixels with the origin at the bottom left.
ANTa and ANTz
ANTa holds annotation text in UTF-8; ANTz holds the same
text compressed with BZZ.
A page’s annotations are those of all its annotation chunks and of the shared
components it includes, taken together. The text is a series of expressions in
parentheses, like Lisp: symbols, numbers and double-quoted strings (with C-style
escapes). Colours are written #RRGGBB. Unknown expressions are
ignored.
| Expression | Values | Meaning |
|---|---|---|
(background #RRGGBB) | a colour | The colour of the viewer around the page. |
(zoom z) | stretch, one2one, width, page, or d and a percentage from 1 to 999 (d150); default | The initial zoom: fill the window, one image pixel per screen pixel, fit width, fit page, or a fixed percentage. |
(mode m) | color, bw, fore, back; default | The initial display mode: everything, the mask only, the foreground only or the background only. |
(align h v) | h: left, center, right; v: top, center, bottom; either may be default | Where to place the page when it is smaller than the window. Centred by default. |
(maparea …) | see below | A hyperlink or a highlighted area. |
(metadata (key "value") …) | pairs | Document metadata. Lower-case keys follow BibTeX (author, title, year); capitalised keys follow PDF’s DocInfo (Title, Author, CreationDate), with dates in RFC 3339 form. |
(xmp "…") | a string | An XMP metadata packet. |
maparea
(maparea url comment area options…)
- url: a string, or
(url "href" "target")to name an HTML-style target frame (default_self). The href is a URL,#plus a page ID or number (#-1and#+1are relative), or?plus arguments for the viewer. An empty string makes a highlight without a link. - comment: a string shown as a tooltip.
- area: one of the shapes below.
| Area | Meaning |
|---|---|
(rect x y w h) | A rectangle from its bottom-left corner. |
(oval x y w h) | An ellipse inside that rectangle. |
(poly x0 y0 x1 y1 …) | A polygon. |
(line x0 y0 x1 y1) | A line, drawn on the page. |
(text x y w h) | A box with the comment written in it, like a sticky note. |
| Option | Shapes | Meaning |
|---|---|---|
(none) | rect, oval, poly, text | No border. |
(xor) | same | A border drawn by inverting pixels. |
(border #RRGGBB) | same | A solid border in that colour. |
(shadow_in n), (shadow_out n), (shadow_ein n), (shadow_eout n) | rect | Bevelled borders, sunken or raised, plain or etched, n pixels thick (1–32). |
(border_avis) | rect, oval, poly, text | Show the border all the time, not only under the mouse. |
(hilite #RRGGBB) | rect | Fill the area with that colour. |
(opacity n) | rect | Opacity of the fill, 0–100, default 50. |
(arrow) | line | An arrowhead at the end. |
(width n) | line | Line width, default 1. |
(lineclr #RRGGBB) | line | Line colour, default black. |
(backclr #RRGGBB) | text | Box background, default transparent. |
(textclr #RRGGBB) | text | Text colour, default black. |
(pushpin) | text | Show a pin icon that opens the text when clicked. |
(background #ffffff)
(zoom page)
(mode color)
(maparea "https://example.org/" "Publisher's site" (rect 120 300 400 60) (xor))
(maparea "#12" "See figure 3" (rect 900 1500 200 40) (border #0000ff) (border_avis))
(metadata (author "H. G. Wells") (title "The Time Machine") (year "1895"))TXTa and TXTz
TXTa is plain and TXTz BZZ-compressed. Once decompressed,
both hold:
| Size | Type | Name | Description |
|---|---|---|---|
| 3 | UInt24 | textLength | The length of the text in bytes. |
textLength | UTF-8 | text | All the page’s text, with separator characters (below) between parts. |
| 1 | UInt8 | version | 1. Optional: when it is missing, there is text but no layout. |
| varies | zone | root | The page zone, with its children nested inside it. |
Zone record
| Size | Type | Name | Description |
|---|---|---|---|
| 1 | UInt8 | type | The zone type, below. A child’s type must be greater than its parent’s. |
| 2 | UInt16 | x | Left edge, stored + 0x8000 (subtract 0x8000 to get a signed value), relative as described below. |
| 2 | UInt16 | y | Vertical position, + 0x8000, relative. |
| 2 | UInt16 | width | Width, + 0x8000. |
| 2 | UInt16 | height | Height, + 0x8000. |
| 2 | UInt16 | textStart | Where the zone’s text starts, + 0x8000, relative. |
| 3 | UInt24 | textLength | How many bytes of text the zone covers. |
| 3 | UInt24 | childCount | How many child zones follow, each a full zone record. |
| Type | Zone | Separator after it in the text |
|---|---|---|
| 1 | Page | – |
| 2 | Column | 0x0B (vertical tab) |
| 3 | Region | 0x1D (group separator) |
| 4 | Paragraph | 0x1F (unit separator) |
| 5 | Line | 0x0A (line feed) |
| 6 | Word | a space |
| 7 | Character | – |
Positions are stored relative to save space:
- The first child of a zone: x is measured from the parent’s left edge;
the zone’s top is y + height below the parent’s top, so its bottom is
parent top − (y + height).
textStartcounts from the parent’stextStart. - A later sibling that is itself a page, paragraph or line zone (stacked under the previous one): x from the previous sibling’s left edge, and bottom = previous bottom − (y + height).
- A later sibling of any other type, in practice a column, word or character (placed beside the previous one): x from the previous sibling’s right edge, y from its bottom.
- For any later sibling,
textStartcounts from the end of the previous sibling’s text.
A page may stop at any depth: only lines, or words, or down to characters.