---
name: "PDF::Builder::Content::Column_docs"
section: "3pm"
platform: "linux"
package: "perl-pdf-builder"
version: "3.028-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/PDF::Builder::Content::Column_docs"
---

# PDF::Builder::Content::Column\_docs(3pm)

## NAME

PDF::Builder::Content::Column\_docs -- column text formatting system

## PDF::Builder::Content::Text/column and related routines

These routines form a sub-library for support of complex columnar output with  high level markup languages. Currently, a single rectangular layout may be  defined on a page, to be filled by user-defined content. Any content which could not be fit within the column confines is returned in an internal array format, and may be passed to the next `column()` call to finish the formatting.

Future plans call for non-rectangular columns to be definable, as well as flow from one column to another on a page, and column balancing. Other  possible enhancements call for support of non-Western writing systems  (e.g., bidirectional text, using the HarfBuzz library), proper  word-splitting and paragraph shaping (possibly using the Knuth-Plass  algorithm), and additional markup languages.

### column

```
    ($rc, $next_y, $unused) = $text->column($page, $text, $grfx, $markup, $txt, %opts)
```

This method fills out a column of text on a page, returning any unused portion that could not be fit, and where it left off on the page.

Tag names, CSS entries, markup type, etc. are case-sensitive (usually  lower-case letters only). For example, you cannot give a \<P\> paragraph in HTML or a **P** selector in CSS styling.

**$page** is the page context. Currently, its only use is for page annotations for links ('md1' \[\]() and 'html' \<a\>), so if you're not using those,  you may pass anything such as `"undef"` for `$page` if you wish.

**$text** is the text context, so that various font and text-output operations may be performed. It is often, but not necessarily always, the same as the object containing the "column" method.

**$grfx** is the graphics (gfx) context. It may be a dummy (e.g., undef) if *no* graphics are to be drawn, but graphical items such as the column outline  ('outline' option) and horizontal rule (\<hr\> in HTML markup) use it.  Currently, *text-decoration* underline (default for links, 'md1' `"[]()"` and  'html' `"<a>"`) or line-through or overline use the text context, but may in the future require a valid graphics context. Images (when implemented) will require a graphics context.

**$markup** is information on what sort of *markup* is being used to format and lay out the column's text:

- 'pre'

  The input material has already been processed and is already in the desired form. `$txt` is an array reference to the list of hashes. This *must* be used  when you are calling `column()` a second (or later) time to output material left over from the first call. It may also be used when the caller application has already processed the text into the appropriate format, and other markup isn't being used.

- 'none'

  If *none* is specified, there is no markup in use. At most, a blank line or a new text array element specifies a new paragraph, and that's it. `$txt` may be a single string, or an array (list) of strings.

  The input **txt** is a list (anonymous array reference) of strings, each  containing one or more paragraphs. A single string may also be given. An empty  line between paragraphs may be used to separate the paragraphs. Paragraphs may  not span array elements.

- 'md1'

  This specifies a certain flavor of Markdown compatible with Text::Markdown.  See the full description below.

  There are other flavors of Markdown, so other md*n* flavors *may* be defined  in the future, such as POD from Perl code.

- 'html'

  This specifies that a large subset of HTML markup is used, along with some  attributes and CSS.

  Numeric entities (decimal &#nnn; and hexadecimal &#xnnn;) are supported,  as well as named entities (&mdash; for example).

  The input **txt** is a list (anonymous array reference) of strings, each  containing one or more paragraphs and other markup. A single string may also be  given. Per normal HTML practice, paragraph tags should be used to mark paragraphs. *Note that HTML::TreeBuilder is configured to automatically* *mark top body-level text with paragraph tags, in case you forget to do so,* *although it is probably better to do it yourself, to maintain more control* *over the processing.* Separate array elements will first be glued together into a single string  before processing, permitting paragraphs to span array elements if desired.

- Other input formats

  There are other markup languages out there, such as HTML-like Pango,  nroff-like man page, Markdown-like wikimedia, and Perl's POD, that  might be supported in the future (provided there are supported Perl libraries for them). It is very unlikely that TeX or LaTeX will  ever be supported, as they both already have excellent PDF output.

  PDF::Builder currently only supports the markup languages described above. If you want to use something else (e.g., Perl's POD, or *man* format, or even  MS Word or some other WYSIWYG format), you will need to find a converter  utility to convert it to a supported flavor of Markdown or HTML. Many such  converters already exist, so take a look (although you may well have to do some  cleanup before `column()` accepts the resulting HTML as input).

  Perhaps in the future, PDF::Builder will directly support additional formats,  but no promises.

**$txt** is the input text: a string, an array reference to multiple strings, or an array reference to hashes. See `$markup` for details.

**%opts** Options -- a number of these are, despite the name, mandatory.

- 'rect' =\> \[x, y, width, height\]

  This defines a column as a rectangular area of a given width and height (both in points) on the current page. *In the future, it is expected that more* *elaborate non-rectangular areas will be definable, but for now, a simple* *rectangle is all that is permitted.* The column's upper left coordinate is `"x, y"`.

  The top text baseline is assumed to be relative to the UL corner (based on the determined line height), and the column outline clips that baseline, as it does additional baselines down the page (interline spacing is `"leading"` multiplied by the largest `"font_size"` or image height needed on that line).

  *Currently, 'rect' is required, as it is the only column shape supported.*

- 'relative' =\> \[ x, y, scale(s) \]

  `'relative'` defaults to `"[ 0, 0, 1, 1 ]"`, and allows a column outline (currently only 'rect') to be either absolute or relative. `"x"` and `"y"` are added to each `"x,y"` coordinate pair, *after* scaling. Scaling values:

  - (none) The scaling defaults to 1 in both x and y dimensions (no change).

    - scale (one value) The scaling in both the x (width) and y (height) dimensions uses this value.

    - scale\_x, scale\_y (two values) There are two separate scaling factors for the x dimension (width) and y dimension (height).

    This permits a generically-shaped outline to be defined, scaled (perhaps not preserving the aspect ratio) and placed anywhere on the page. This could save you from having to define similarly-shaped columns from scratch multiple  times. If you want to define a relative outline, the lower left corner (whether or not it contains a point, and whether or not it's the first one listed) would  usually be `"0, 0"`, to have scaling work as expected. In other works, your outline template should be in the lower left corner of the page.

- 'start\_y' =\> $start\_y

  If omitted, it is assumed that you want to start at the top of the defined column (the maximum `"y"` value minus the maximum vertical extent of this line). If used, the normal value is the `"next_y"` returned from the previous  `column()` call. It is the deepest extent reached by the previous line (plus leading), and is the top-most point of the new first line of this `column()` call.

  Note that the `"x"` position will be determined by the column shape and size (the left-most point of the baseline), so there is no place to explicitly set  an `"x"` position to start at.

- 'font\_size' =\> $font\_size

  This is the starting font size (in points) to be used. Over the course of the text, it may be modified by markup. The default is 12pt. It is in turn overridden by any CSS or HTML font size-settings.

  The starting font size may be set in a number of ways. It may be inherited from a previous `"$text->font(..., font-size)"` statement; it may be set via the `"font_size"` option (overriding any font method inheritance); it may default to  12pt (if neither explicit way is given). For HTML markup, it may of course be  modified by the `"font"` tag or by CSS styling `"font-size"`. For Markdown, it may be modified by CSS styling.

- 'font\_info' =\> $string

  This permits the user to specify the starting font used in `column()` (body font-family, font-style, font-weight, color). `column()` will pick up any  font already loaded (`"$text->font($font, $size);"`, or using FontManager), and use that  as the "current" font. If no font has been loaded, and no other instructions are given, the FontManager default (core Times-Roman) will be used.

  The `"font_info"` option for `column()` may be given to override either of the two above methods. You may specify a `$string` of **'-fm-'** to instruct `column()` to use the FontManager "default" font (Times face core font). Or, you may pick a font face *known* to FontManager (added by user code if not one of the 28 core  fonts), and optionally give it style and weight: `$string` of  **'face:style:weight:color'**. The style defaults to 'normal' (non-italic), or  'normal' or '0' may be given. For italics, use 'italic' or '1'. The weight  defaults to 'normal' (unbolded weight), or 'normal' or '0' may be given. For  bold (heavy) text, use 'bold' or '1'. Finally, a color may be given.

  Finally, the `"style"` option for `column()` may be given to override any of  the above settings, e.g., **'style'=\>{ body { font-family:... }** and set the initial current font. Remember that, as with anything font-related that `column()` does, the 'face' (family) used must already be known to FontManager (explicitly loaded with `add_font()` if not one of the 28 core fonts).  Remember that the first 14 fonts are standard PDF, and the second 14 are  normally supplied with Windows (but not always with other operating systems).

- 'marker\_width' =\> $marker\_width

  - 'marker\_gap' =\> $marker\_gap

  This is the width of the gutter to the left of a list item, where (for the first line of the item) the marker lives. The marker contains the symbol (for bulleted/unordered lists) or formatted number and "before" and "after" text (for numbered/ordered lists). Both have a single space (marker\_gap = 1em) before the item text starts. The number is a length, in points.

  The default is 1 em (1 times the font\_size passed to `column()`), and is not  adjusted for any changes of font\_size in the markup, so that lists are indented *consistently*. This is usually fine for unordered (bulleted) lists and single digit ordered (numbered) lists, although you may need to make it wider for  two or three digit numbered lists. An explicit value passed  in is also not changed -- the gutter width for the marker will be the same in  all lists (keeping them aligned). If you plan to have exceptionally long  markers, such as an ordered list of years in Roman numerals, e.g.,  **(MCMXCIX)**, you may want to make this gutter a bit wider.

  A value may be given for the marker\_gap, which is the gap between the  (`$marker_width` wide) *marker* and the start of the list item's text.  The default is `$fs` points (1 em), set by the font\_size in the markup.

  The `"list-style-position"` CSS property may be given as the standard 'outside' (the default) or 'inside', or (extension to CSS) to indent the left side of second, third, etc. \<li\> lines to somewhere between the 'inside' and 'outside' positions. Be sure to consider the `"_marker-align"` extended  property to left, center, or right (default) align the marker within the  `"marker_gutter"`.

- 'leading' =\> $leading

  This is the leading *ratio* used throughout the column text. The `"$x, $y"` position through `"$x + width"` is assumed to be the first text baseline. The next line down will be `"$y - $leading*$font_size"`. If the font\_size changes for any reason over the course of the column, the baseline spacing (leading \* font\_size) will also change. The **default** leading ratio is 1.125 (12.5% added to font).

- 'para' =\> \[ $indent, $top-margin \]

  When starting a new paragraph, these are the *default* indentation (in points), and the extra vertical spacing for a top margin on a paragraph. Otherwise, the  default is `"[ 1*$font_size, 0 ]"` (1em indent, 0 additional vertical space). Either may  be overridden by the appropriate CSS settings. An *outdent* may be defined  with a negative indentation value. These apply to all `$markup` types.

  At the top of a column, any top margin (not just for paragraphs) is ignored.

- 'outline' =\> "color string"

  You may optionally request that the column be outlined in a given color, to aid in debugging fitting problems. This will require that the graphics context be provided to `column()`.

- 'color' =\> "color string"

  The color to draw the text (or rule or other graphic) in. The default is  black (#000000).

- 'style' =\> "CSS styling"

  You may define CSS (selectors and properties lists) to override the built-in CSS defaults. These will be applied for the entire `column()` call. You can use this, or `"style"` tags in 'html', but for 'none' or 'md1', you will need to use this method to set styling. See also the `"font_info=>"` option to set initial font settings.

  Note that, unlike the `"style="` *attribute* in HTML tags, the `"style=>"` option is formatted like a \<style\> *tag* -- that is, with **selector {** *property*: *value*;... **}**. If you want to set *global* values, use the **body** selector.

- 'substitute' =\> \[ \[ 'char or string', 'before', 'replace', 'after'\],... \]

  When a certain Unicode code point (character) or string is found, insert  *before* text before the character, replace the character or string with *replace* text, and insert *after* text after the character. This may make it easier to insert HTML code (font, color, etc.) into Markdown text, if the desired settings and character can not be produced by your Markdown editor. This applies both to 'md1' and 'html' markup. Multiple substitutions may be  defined via multiple array elements. If you want to leave the original character or string *itself* unchanged, you should define the *replace* text to be the same as `'char or string'`.  'before' and/or 'after' text may be empty strings if you don't want to insert some sort of markup there.

  Example: to insert a red cross (X-out) and green tick (check) mark

  ```
      'substitute' => [
        [ '%cross%', '<font face="ZapfDingbats" color="red">', '8', '</font>' ],
        [ '%tick%', '<font face="ZapfDingbats" color="green">', '4', '</font>' ],
      ]
  ```

  should change `"%cross%"` in Markdown text ('md1') or HTML text ('html') to `"<font face="ZapfDingbats" color="green">8</font>"`  and similarly for `"%tick%"`. This is done *after* the Markdown is converted  to HTML (but before HTML is parsed), so make sure that your macro text (e.g.,  `"%tick%"`) isn't something that Markdown will try to interpret by itself! Also,  Perl's regular expression parser seems to get upset with some characters, such  as `"|"`, so don't use them as delimiters (e.g., `"|cross|"`). You don't *have*  to wrap your macro name in delimiters, but it can make the text structure clearer, and may be necessary in order not to do substitutions in the wrong  place.

- 'state' =\> \\%state

  This is the state of processing, including (in particular), information on all the requested references (\<a\>, \<\_ref\>) and targets (\<\_reft\> and specific id's).  Before use, it must be created and initialized. During multiple passes across multiple **column()** calls, 'state' preserves all the link information. It can even preserve information across the creation of multiple related PDFs, though this may require writing and reading back from a file. There is no information in 'state' that is likely to be of interest to a user (i.e., all internal data). If 'state' is not given, it will (in most cases) be impossible to define various kinds of links (including cross references). A URL link to a browser does not need `'state'`, but all other kinds of links to this or other PDF files do.

- 'page' =\> \[ $ppn, $extfile, $fpn, $LR, $bind \]

  This array of values gives `column()` information needed for generating links (both *goto* and *pdf* annotations), and (TBD) left- and right-hand page processing, including how much to shift `column()` definitions to the outside of the page for binding purposes (TBD). The link information is as follows:

  - $ppn

    This is the Physical Page Number of the page currently being generated. It is  always an integer greater than 0, and takes a value 1,2,3,... It is needed if this page is used as the target for an external (across PDFs) link, using a physical page number and not a Named Destination.  Remember to increment it every time the code calls the `page()` method.  It may be left undefined if you are sure you're never going to generate a link  (via `"pdf"` call, not using a Named Destination) to this PDF file from another  PDF.

  - $extfile

    This describes the external path, filename, and extension of **this** PDF being created. It is needed if this page is used as the target for an external  (across PDFs) link. Remember that this is the *final* location and name of where this file will live when in use, not necessarily where it is being *created* at this moment! It may be left undefined or a random name if you are sure you're never going to  generate a link (via `"pdf"` call) to *this* PDF file from another PDF.

  - $fpn

    This is the *Formatted* Page Number of the page being generated. In the  simplest case, it is equal to the Physical Page Number, but often you will want to "get fancy" with numbering, such as a prefix for an appendix ('C-2', 'Glossary-5', etc.), lowercase Roman numerals in the front matter, etc. You might even want to carry one single sequence of decimal page numbers across  multiple PDFs, thus starting at other than "1". If you leave it undefined, certain kinds of links and cross reference formats (where the formatted page number is shown) will not be possible.

  - $LR

    This says whether it's a left-hand page or a right-hand page, for purposes of formatting layout and shifting the `column()` outline left or right (towards the "outside" of the page) to allow binding space. If undefined, it defaults to an 'R' right-hand page. This ability is currently unused.

  - $bind

    This is the number of points to shift the `column()` coordinates towards the "outside" of the page for purposes of binding multiple pages together, whether left-right alternation or all right-hand pages (e.g., punched for a notebook or spiral binding, or just stapled on the inside, or glued or sewn into a  paperback or hard-cover binding). If undefined, the default is 0. This ability  is currently unused.

- 'restore' =\> flag

  This integer flag determines what sort of cleanup `column()` will do upon exit, to restore (or not) the font state (face, bold or normal weight,  italic or normal style, size, and color).

  - for rc = 0 (all input markup was used up, without running out of column)

    - restore =\> 0

      This is the **default**. Upon exiting, `column()` will attempt to restore the  state to what one would see if there was yet more text to be output. Note that this is *not* necessarily what one would see if the entire state was restored to entry conditions. The intent is that another `column()` call can be  immediately made, using whatever font state was left by the previous call, as though the two calls' markup inputs were concatenated.

    - restore =\> 1

      This value of `"restore"` commands that *no* change be made to the font state, that is, `column()` exits with the font state left in the last text output. This may or may not be desirable, especially if the last text output left the text in an unexpected state.

    - restore =\> 2

      This value of `"restore"` attempts to bring the font state all the way back to what it was upon *entry* to the routine, as if it had never been called. Note that if `column()` was called with no global font settings, that can not be undone, although the color *can* be changed back to its original state,  usually black.

      **CAUTION:** The Font Manager is not synchronized with whatever state the font is returned to. You should not request the 'current' font, but should instead explicitly set it to a specific face, etc., which resets 'current'.

  - for rc = 1 (ran out of column space before all the input markup was used up)

    - restore =\> 0

      This is the **default**. Upon exiting, no changes will be made to the font state. As the code will be in the middle of some output, the font state is kept the same, so the next `column()` call (for the overflow) can pick up  where the previous call left off, with regards to the font state.

      It is equivalent to `"restore = 1"`.

    - restore =\> 1

      This is the same as `"restore = 0"`.

    - restore =\> 2

      This value of `"restore"` attempts to bring the font state all the way back to what it was upon *entry* to the routine, as if it had never been called. Note that if `column()` was called with no global font settings, that can not be undone, although the color *can* be changed back to its original state,  usually black.

      **CAUTION:** The Font Manager is not synchronized with whatever state the font is returned to. You should not request the 'current' font, but should instead explicitly set it to a specific face, etc., which resets 'current'.

**Data returned by this call**

If there is more text than can be accommodated by the column size, the unused portion is returned, with a return code of 1. It is an empty list if all the  text could be formatted, and the return code is 0. `"next_y"` is the y coordinate where any additional text (`column()` call)  could be added to a column (as `"start_y"`) that wasn't completely filled. This would be at the starting point of a new column (i.e., the last paragraph is ended). Note that the application code should check if this position is too far down the page (in the bottom margin) and not blindly use it! Also, as 'md1' is first converted to HTML, any unused portion will be  returned as 'pre' markup, rather than Markdown or HTML. Be sure to specify  'pre' for any continuation of the column (with one or more additional  `column()` calls), rather than 'none', 'md1', or 'html'.

- $rc

  The return code.

  - '0'

    A return code of 0 indicates that the call completed, while using up all the input `$txt`. It did *not* run out of defined column space.

    **NOTE:** if `"restore"` has a value of 1, the `column()` call makes no effort  to "restore" conditions to any starting values. If your last bit of text left the "current" font with some "odd" face/family, size, *italicized*, **bolded**, or colored; that will be what is used by the next column call (or other PDF::Builder text calls). This is done in order to allow you to easily chain from one column to the next, without having to manually tell the system what font, color, etc. you want to return to. On the other hand, in some cases you may want to start from the same initial conditions as usual. You may want to add `get_font()`, `font()`, `fillcolor()`, and `strokecolor()` calls as necessary before the next text output, to get the expected text characteristics. Or, you can simply let `"restore"` default to 0 to get the same effect.

  - '1'

    A return code of 1 indicates that the call completed by filling up the defined column space. It did *not* run out of input `$txt`. You will need to make one or more calls with empty column space (to fill), to use up the remaining input text (with "pre" *$markup*).

    If `"restore"` defaults to 0 (or is set to 1), the text settings in the  "current" font are left as-is, so that whatever you were doing when you ran out of defined column (as regards to font face/family, size, italic and bold states, and color) should automatically be the same when  you make the next `column()` call to make more output.

  Additional return codes *may* be added in the future, to indicate failures of one sort or another.

- $next\_y

  The next page "y" coordinate to start at, if using the same column definition as the previous `column()` definition did (i.e., you didn't completely fill the column, and received a return code of 0). In that case, `$next_y` would give the page "y" coordinate to pass to `column()` (as `"start_y"`) to start a  new paragraph at.

  If the return code `$rc` was 1 (column was used up), the `$next_y` returned will be -1, as it would be meaningless to use it.

- $unused

  This is the unused portion of the input text (return code `$rc` is 1), in a  format ("pre" `$markup`) suitable for input as `$txt`. It will be a *reference* to an array of hashes.

  If `$rc` is 0 (all input was used up), `$unused` is an empty anonymous array. It contains nothing to be used.

*Special notes on saving and restoring the font*

It is important to let `column()` know what font face (font-family), weight, and style to use, so it can switch between normal, bold, and italic as desired. There are several methods to *explicitly select* a font face (font-family) and its variants (weight, style) upon entry to `column()`. One is to use the `"font_info"` option to `"column"`, including "-fm-" (default) to use  FontManager's default font (core Times-Roman). Another is to use the `"style"`  option to `column()` to override the **body** default CSS. A third, if using  HTML or Markdown, is to add a \<style\> tag to the beginning of the text  markup, in order to set the **body** CSS (as with `"style"`). All of these  methods will set the **body**'s font.

If nothing special is done, the font selection upon entry to `column()` will  default to using the default FontManager settings (core Times-Roman, equivalent to `'font_info'=>'-fm-'`). `"font_info"` may also be explicitly set to  specify the body text font-family (optionally also style, weight, and color).  `'font_info'=>'-ext-'` may be given to tell FontManager to pick up an  already-loaded font in this text context. It will label that font  **-external-** and use it as the current font. *However*, be aware that if  doing this, `column()` will **not** know the actual face (font-family) of  whatever font this is, and thus can not change the font-weight (bold) or  font-style (italic). These change requests will be ignored. If no font is  already loaded, the FontManager's default font (`"-fm-"` core Times-Roman) will  be selected (and no "-external-" font defined). Whatever way is used to specify he body font-family on the command line, it may be overridden by a  `"<style>"` tag or `"'style'=>"` command line CSS specification.

Once `column()` has already been called within a given text context, whatever font is in force at the end of the call will be preserved by the text context, available to be picked up by the next `column()` call with  `'font_info'=>'-ext'` within *this* text context. ***column()*** *will still* ***not*** *know the font-family, since this information is not carried in the text* *context!* Note that a text context is limited to a single page of a PDF, at  most (it must be defined by the `"$page->text()"` call, and is reset with each new page). The user code may of course choose to load a  new font externally to `column()`, in order to use that one upon entry. An `"-external-"` font still cannot change style or weight.

Any font "face" used must be first registered with FontManager. The standard core fonts (as well as Windows extensions) are preregistered. If user code loads an arbitrary font outside of `column()`, it will only be known as "-external-" (as described above). `column()` calls (including CSS font-family) only recognize registered faces, so it knows where to find the font file and other information, and can cache the loaded font. It can keep track of which font is currently being used, and know how to set bold and italic variants.

When the end of the defined column is reached (before the text source is exhausted), all open tags are preserved, so that the next `column()` call  (with *pre* formatting) can pick up with the same font settings as before. However, this works only as long as the complete font description is set in the tags (including the face). If the font face is not given in the tags, it will not be known, and bold and italic will likely not work at the next change.  If the text is in the middle of a highlighted phrase (e.g., bold or italic, or  a different font), that particular font should be picked up again. However, the  **body** font face and variant may not be correctly resumed if it is assumed  that the proper font has been inherited by the next `column()` call.  Explicitly setting the **body** font should allow the font to return to a known  starting condition, although it is possible that (based on nesting of font  changes at the column break) other aspects might be incorrect.

To summarize, the best practice is to register (`"add_font"`) to FontManager any fonts you wish to use, and then explicitly use `"font_info"` or `"style"` to let `column()` know what the base font is for your text. This is better than externally loading a font, and depending on its being inherited from the text context, which may in turn may leave it in some other state after a `column()` call, as well as not being able to change bold and italic.

### Markup supported

*pre (already formatted from another format)*

This is an internal format, essentially the output from HTML::TreeBuilder. As this data is consumed by output, it is removed from the array. If any is left over when the column is filled, it is returned to the user, and may be used in a 'pre' format call to `column()` to finish the job.

If you wish to manually generate 'pre' format data, you may do so, although it is usually easier to use a higher level markup such as 'md1' or 'html'.

*none*

This format simply has empty lines separating paragraphs. Otherwise it has no markup.

*md1 (Markdown)*

This is the version of the Markdown language supported by the Text::Markdown  library. It is converted into the equivalent HTML and then processed by HTML::TreeBuilder.

Standard Markdown

- •

  \* or \_ produces italic text

- •

  \*\* produces bold text

- •

  \*\*\* produces bold+italic text

- •

  \* (in column 1) produces a bulleted list

- •

  1\. (2., 3., etc. if desired) in column 1 produces a numbered list 1., 2., etc.

- •

  \# produces a level 1 heading. ## produces a level 2 heading, etc. (up to ###### level 6 heading)

- •

  \---, ===, or \_\_\_ produces a horizontal rule

- •

  \~~ enclose a section of text to be line-through'd (strike-out)

- •

  \[label\](URL) external links (to HTML page or within this document, see '\<a\>' for URL/href formats)

- •

  \[label\]\[n\] reference-style links **NOT** currently supported

- •

  \[label\]\[^n\] footnote-style links **NOT** currently supported

- •

  \` (backticks) enclose a "code" format phrase

- •

  \`\`\` (backticks) enclose a "code" format *block*, **NOT** currently supported

- •

  !\[alt text\](path\_to\_image) image, **NOT** currently supported

- •

  table entries with \| and - (or HTML tags) **NOT** currently supported

- •

  superscripts (^) and subscripts (~) (or HTML tags) **NOT** currently supported

- •

  definition lists with : **NOT** currently supported

- •

  task lists - \[ \] **NOT** currently supported

- •

  emojis will **NEVER** be supported. We have a perfectly good alphabet.

- •

  highlighting (inline == or HTML \<mark\>) **NOT** currently supported

HTML (see below) may be mixed in as desired (although not within "code" blocks  marked by backticks, where \<, \>, and & get turned into HTML  entities, disabling the intended tags). Markdown will be converted into HTML, which will then be interpreted into PDF. *Note that Text::Markdown may produce HTML for certain features, that is not*  *yet supported by HTML processing (see 'html' section below). Let us know if*  *you need such a feature!*

The input **txt** is a list (anonymous array reference) of strings, each  containing one or more paragraphs and other markup. A single string may also be  given. Per Markdown formatting, an empty line between paragraphs may be used to  separate the paragraphs. Separate array elements will first be glued together  into a single string before processing, permitting paragraphs to span array  elements if desired.

Extended Markdown

CSS (Cascading Style Sheets) may be defined for resulting HTML tags (or "body"  for global settings), via the `"style=>"` `column()` option. You may also prepend a `"<style>"` HTML tag, with CSS markup, to your Markdown source.

Standard Markdown permits an 'id' to be defined in a heading, by suffixing the text with `"{#id_name}"`. This is equivalent to `"id="id_name""` in HTML markup. Although Text::Markdown does not currently support it, `column()` implements this way of defining a target's id, and in fact extends it to permit an id to  be defined for any tag with child text.

Markdown is further extended by `column()` to permit a 'title' to be defined for any tag with child text, by use of `"{^title_text}"`. Note that this 'title' is the *link title* to be used, **not** browser style "hover" popup text. It is the equivalent of `"title="title_text""` in \<a\> or \<\_ref\> HTML markup.  Any link tag may define the PDF "fit" to use at the target, by  `"{%fit_type,parm(s)}"` or `"fit="fit_type,parm(s)""` in \<a\> or \<\_ref\>  HTML markup.

There are other HTML equivalents defined by Standard Markdown which may not be implemented (converted) by Text::Markdown. Among these are `"~~"` line-through (strike-out) and `"==="` horizontal rule, which have been fixed with  post-processing of the generated HTML. Let us know if you find any more such cases, and we may be able to extend the functionality of 'md1' formatting, or  if necessary, implement 'md2' format to use a different library. By default,  Text::Markdown disables extended \<\_tagname\> calls, but these all should be handled properly in post-processing. There are also Markdown features that may be implemented by Text::Markdown, but the resulting HTML is not supported by `column()` (yet). If you are missing a needed feature, ask about our moving it up on the priority list.

*html (HTML)*

This is the HTML language to be processed by the HTML::TreeBuilder library. It  is processed into an array of tags and text strings ('pre' format), which is  interpreted by `column()`. A substantial subset of CSS (Cascading Style Sheets) is also interpreted by `column()`, although selectors are primitive compared to what a browser supports.

Standard HTML tags

A good many HTML tags are implemented, although not all of them:

- •

  **\<i\> or \<em\>** produces italic or slanted/oblique text, where available through FontManager

- •

  **\<b\> or \<strong\>** produces bold text, where available through FontManager

- •

  **\<s\>, \<strike\>, and \<del\>** produce text line-through (strike-out or strike-through)

- •

  **\<u\> and \<ins\>** produce underlined text

- •

  **\<code\>** produce 'code'-style fixed-pitch text

- •

  **\<h1\> through \<h6\>** produce level 1 through 6 headings and subheadings

- •

  **\<hr\>**  produce a horizontal rule

  The `"width="length""` attribute gives a length (width, in pixels) less than the full column width, and `"size="height""` attribute gives the height (thickness) of the rule. CSS properties `"width"` and `"height"` are the equivalent, permitting other units of measure.

  The default `"width"` is the full column, and `"size"` (thickness) of the line is 0.5pt.

  Note that most browsers default to *center* alignment if the width is less than the full column, which is the default here.  The **align** attribute is available here to specify *left* alignment of the rule, *center* alignment (default), or *right* alignment. Note that this attribute is deprecated in the HTML standard, however, PDF::Builder does not yet support the suggested CSS methods (properties) for doing this.

- •

  **\<blockquote\>** produces a quotation block, a paragraph indented on both sides and of smaller font size

- •

  **\<p\>** produces a paragraph

- •

  **\<font face="font-family" color="color" size="font-size"\>** as selecting font face, color, and size (considered better to use CSS)

- •

  **\<span\>** needs a style= attribute with CSS to do anything useful

- •

  **\<ul\>** produces an unordered (bulleted) list. The `"type"` attribute to override the default marker is supported

- •

  **\<ol\>** produces an ordered (numbered) list. `"start="`, `"type="`, and `"reverse="` attributes are supported to override the default starting count, format, and direction

- •

  **\<li\>** adds a list item to a list (ul, ol, or \_sl). The `"value="` attribute may be given to override the ordered list counter, and the `"type="` attribute may be given to override the default marker type

- •

  **\<a href="URL"\>**  produces a link to a browser URL or to this or another PDF document. "URL" is anchor/link, web page URL or this document target `"#p[-x-y[-z]]"` (p is physical page number), or path to external PDF document before the #. ##NamedDest and extPDF##NamedDest are supported. Otherwise treat as an "id" (id=).

  - •

    **href="protocol://..."** a link will be generated to an HTML browser or (for protocol "mailto") an email client. The tag remains \<a\> and a's CSS properties are used. Otherwise, internally the tag will be changed to \<\_ref\>, whose CSS properties will be used

  - •

    **href="#p" or "#p-x-y" or "#p-x-y-zoom"** a link will be generated to a physical page number "p" in this document. Optionally, an x-y location on the page (for fit="xyz") may be given with an optional zoom factor

  - •

    **"PDF\_document\_path#p" etc.** a link will be generated to a physical page number "p" in an external document. Note that the path and filename must point to either an absolute address or to one relative to where this PDF will be located

  - •

    **"##Named\_destination"** a link will be generated to a Named Destination in this document (see \<\_nameddest\>). Note that the Named Destination itself will define the "fit" to be used

  - •

    **"PDF\_document\_path##Named\_destination"** a link will be generated to a Named Destination defined in an external document. Note that the path and filename must point to either an absolute address or to one relative to where this PDF will be located, and that the Named Destination itself will define the "fit" to be used

  - •

    **"#id\_name" or "id\_name"** a link will be generated to the "id" of given name, which may be in this PDF document or another (if processed in the same run). If a "#" is used, the name must **not** be all decimal digits, or all decimal digits followed by a "-" and other parts, as this will be interpreted as a "#p" physical page link!

  The link's child text, if not empty, will be used for the resulting link. If there is none, any "title" attribute or `"{^title text}"` provided with the target (such as \<\_reft\>) will be used. Finally, any native "child text" (e.g., a heading's text content) will be used.

  If using HTML markup, any tag with an id= may be a target. Especially for Markdown use, any tag with child text (not just a heading's text) may include `"{#idname}"` to be parsed out as `"id="idname""` (and thus usable as a target).

  An explicit "fit=" attribute may be given in the \<a\> tag, to specify the page fit used by the PDF Reader at the target location. For example, fit="xyz,45,600,1.5" to place the window upper left corner at 45,600 and 150% zoom factor. For Markdown usage, {%xyz,45,600,1.5} in the link text (title) would be the equivalent (xyz fit, at 45,600, zoom 1.5). For a page number target (#p), -x-y (and optionally -zoom) may be added for the same effect (xyz fit). "null" or "undef"  may be used for undefined items. For any fit, `%x` and `%y` may be used for the  target's x and y location, to use the actual target location and not a fixed  location on a page.

- •

  **In plan, but not yet implemented**

  - •

    'pre' (preformatted blocks),

  - •

    'cite', 'q', 'samp', 'var', 'kbd' (various highlights),

  - •

    'big', 'bigger', 'small', 'smaller' (various font sizes),

  - •

    'img' (image display),

  - •

    'br', 'nobr' (line break, line break suppression),

  - •

    'sup', 'sub' (superscript and subscript),

  - •

    'dl', 'dt', 'dd' (definition lists),

  - •

    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td' (tables),

  - •

    'mark' (highlighting... requires ability to set background color),

  - •

    'div' (handle div's in some manner),

  - •

    'center',

  - •

    'caption', 'figure', 'figcap' (optional sub- and super-sections)

  - •

    'nav', 'header', 'footer', 'address', 'article', 'aside', 'canvas', 'section', 'summary' (possibly some sectioning)

*Numbered* (decimal and hexadecimal) entities are supported, as well as *named* entities (e.g., `"&mdash;"`). Lists get a "gutter" (for the marker) of *marker\_width* points wide, and a "gap" between the marker's field and the start of the item's text (*marker\_gap* points wide), so list alignments are consistent over the call.

Extended HTML tags

A number of HTML-like tags, whose names start with an underscore "\_", have been implemented to perform various tasks. These include:

- •

  **\<\_ref\>** defines an *alternative* form of a link to this or another PDF document (not for URLs to HTML or email; for that, use \<a\>). The attribute `"tgtid="` is required, and equivalent to \<a\>'s `"href="`. The attribute `"title="` is optional, and provides title text for the link. The attribute `"fit="` is optional, and provides a non-default "fit" for the target page (note that a Named Destination target provides its own "fit"). For a 'fit' of 'xyz', you may use '%x' for the x value and '%y' for the y value to use the current positions, rather than fixed values. Note that any \<a\> link *not* to a browser or email client will be internally converted to \<\_ref\>, so CSS for formatting the link text (title) will be defined under '\_ref'

- •

  **\<\_reft\>** defines a target id for a link (via the `"id="` attribute), especially if an existing id is not conveniently at hand. See `"id="` attributes in most HTML tags, and `"{#id_name}"` for many Markdown "tags". An optional attribute `"title="` may be given to provide a default link text for the link (\<a\> or \<\_ref\>) referring to this id

- •

  **\<\_nameddest\>** defines a Named Destination within this document, accessible via a "##" format link href, or from some PDF Readers on the command line (one or more of `"#ND_name"`, `"#name=ND_name"`, or `"#nameddest=ND_name"` will usually work, when appended to the PDF file path and name, just like with HTML anchor id's). The attribute `"name="ND_name""` is required, to globally name this Destination (the character set allowed and maximum length vary among Readers!). The optional attribute `"fit="fit_info""` may be give to specify a non-default "fit" when invoked. It is the type of fit (e.g., "xyz", "fith", etc.) followed by any location values required by that fit, all separated by commas. `"xyz,%x-100,$y+100,null"` is the default fit

- •

  **\<\_marker\>** provides a place to specify, via CSS, on a *per list item basis*, overrides to default marker settings (see also `"_marker-*"` CSS extensions below). If omitted, the same HTML list markers and CSS properties are used for each list item (per usual practice). The intent of this tag is to permit styling changes such as font, color, and alignment to an individual list item (\<li\>). This tag is placed immediately *before* the \<li\> it applies to

- •

  **\<\_move\>** provides a way to explicitly move the current write point left or right. Attribute `"x="value""` is an absolute move (in points), while attribute `"dx="value""` is a relative move from the current write point. Along with the "text-align" CSS property, this can provide a way to fine tune text position within a column line.

  An x value that is a bare number (no units) is assumed to specify *points*, equivalent to units of `"pt"`. The unit may also be `"%"`, where 0% is the left end of the column, 50% is the center, and 100% is the right end. A dx value that is a bare number (no units) is assumed to specify *points*, equivalent to units of `"pt"`. The unit may also be `"%"`, a fraction of the column width to move (+ right, - left). Note that results are unpredictable if you move beyond the edge of the column in either direction

- •

  **\<\_sl\>** provides a *simple list*, very similar to an *unordered list*, except for no list markers

- •

  **In plan, but not yet implemented**

  - •

    '\_k' (manual kerning control)

  - •

    '\_ovl' (overline, similar to underline and line-through)

  - •

    '\_lig' (specify a particular ligature to use here)

  - •

    '\_nolig' (suppress ligatures by HarfBuzz)

  - •

    '\_swash' and '\_altg' (specify a particular alternate glyph to use here)

  - •

    '\_sc' (specify "small caps" font variant, with forced end after N words)

  - •

    '\_pc' (specify "petite caps" font variant, with forced end after N words)

  - •

    '\_dc' (specify "dropped cap" font variant in some manner, also CSS)

  - •

    ? (specify conditional and unconditional page breaks)

Standard CSS properties and values

CSS (Cascading Style Sheets) may be defined for HTML tags (or "body"  for global settings), via the `"style=>"` `column()` option. You may also add one or more `"<style>"` HTML tags, with CSS markup, to your HTML  source. Such entries will be combined into a global style section.

\<style\> tags may be placed in an optional \<head\> section, or within the \<body\>. In the latter case, style tags will be pulled out of the body and added (in order) on to the end of any style tag(s) defined in  a head section. Multiple style tags will be condensed into a single collection  (later definitions of equal precedence overriding earlier). These stylings will have global effect, as though they were defined in the head. As with normal CSS, the hierarchy of a given property (in decreasing precedence) is

```
    appearance in a style= tag attribute
    appearance in a tag attribute (possibly a different name than the property)
    appearance in a #IDname selector in a <style>
    appearance in a .classname selector in a <style>
    appearance in a tag name selector in a <style>
```

Selectors are quite simple: a single tag name (e.g., **body**), a single class (.cname), or a single ID (#iname).  There are *no* combinations (e.g.,  `"p.abstract"` or `"ol, ul"`), hierarchies (e.g., `"ol > li"`), specified  number of appearance, pseudotags, or other such complications as found in a  browser's CSS. Sorry!

Length Measures

Property values which are lengths (including `"font-size"`) may have units of **pt**  (points, 72 to the inch), **px** (pixels, currently fixed at 78 to the inch),  **in** (inches), **cm**, **mm**, **em** (equal to font-size), **en** (0.5em), and **ex** (currently  0.5em, but in the future may be able to query the font's actual x-height).  % (percentage) of the current font-size (in most cases, unless otherwise noted) is allowed, although some properties may in the future support % of the enclosing object size.  Sizes may be negative numbers (useful only for margins).

- •

  For property  *list-style-position*, % is relative to the marker width+gap, not font-size (and pt values may be given, where "inside" = 0% and "outside" = 100% of marker width+gap). The standard 'outside' (default) and 'inside' values may also be given.

- •

  For the *\<hr*\> tag, the "width" and "size" attributes are in points. For the CSS "width"  property, absolute units may be given, or % of available column width. For the CSS "height" property, absolute units may be given.

**Note** that eventually we may support `"li::marker"`, which is now standard CSS, but there does not appear to be a way to support changes via `"style="`, because the same property names (e.g., *color*) would apply to both the marker and the list item text. This will require extensive changes to CSS style to permit  complex selectors, which `column()` does not currently offer. Even doing that, we may retain the current "marker" tags and CSS introduced here. I think W3C may have missed the boat by not doing something like an optional `"_marker"` to  permit normal properties for markers alone, but configurable in-line with `"style="`.

Supported CSS properties:

- •

  **color** (foreground color, in standard PDF::Builder formats)

- •

  **display** (*inline* or *block*)

- •

  **font-family** (name as defined to FontManager, e.g. Times)

- •

  **font-size** (length measure)

  Note that **body** `"font-size"` is the starting point, and so if given, must be a bare number (greater than 0) or number + 'pt'. `"font-size"`s for other tags may be given as % of inherited font-size or em (100% of font-size), en (50%), or ex (currently fixed at 50%).

  Unless otherwise prohibited, any tag's CSS may first change the font-size, and then properties such as margins defined as % of font-size will be calculated using the new font-size, rather than the inherited one.

- •

  **font-style** (*normal* or *italic*)

- •

  **font-weight** (*normal* or *bold*)

- •

  **height** (pt, bare number)

  Thickness (height) of **horizontal rule**. The HTML attribute is `"size"`.

- •

  **list-style-position** (outside, inside, **extension:** number pt or % to indent)

- •

  **list-style-type** (marker description, see also \_marker-text/before/after)

- •

  **margin-top/right/bottom/left** (length measure)

  Note that adjacent bottom and top margins will be collapsed to use the  *larger* amount of the two. Negative margin values ("pulling" objects towards each other) are allowed, and positive margin values "push" objects away from each other.

- •

  **text-decoration** (none, underline, line-through, overline)

  May use more than one value (except 'none') separated by spaces.

  **Note 1:** various HTML tags (such as *u*, *ins*, *del*, *s*) make use of  this CSS property, and may of course be changed in the styling.

  **Note 2:** both *underline* and *overline* are solid lines, which will collide with glyph descenders and ascenders respectively. We are investigating means of implementing something like the CSS *text-decoration-skip-ink: auto* property.  PDF does not appear to currently define a way of doing this (to be handled by the Reader). *line-through* is  also a solid line that collides with glyph strokes, but the usual intent *is*  to obscure the text, so there are no plans to change this default behavior.

  **Note 3:** these decorations are made as escapes within the text object, rather than within the graphics object. We reserve the right to (in the future) change  this to require a graphics object to draw them. Some lead time will be given so that you have a chance to update your code.

  **Note 4:** *line-through* uses a fixed % of ascender height, rather than of *ex* height. In some fonts, this may result in a *line-through* "floating" above the bulk of the characters (intersecting only ascenders), i.e., it is above the x-height. It's on the "to do" list to address this.

- •

  **line-height** (leading, as ratio of baseline-spacing to font-size).

  Currently, percentage of font-size and absolute units (e.g., pt) are **not** supported.  The default value is 1.125 (18pt line-to-line for font-size 16).

  **Note:** **text-height**, the former *incorrect* name for this property, is  still supported (as an alias for **line-height**) through release 3.029, but may  be withdrawn as soon as release 3.030. Update your code if you use it!

- •

  **text-indent** (length measure)

  For paragraph indentation.

- •

  **text-align** (left/center/right justify at current text position)

  **Note:** if center or right justified, you should keep the text short enough to fit within the left and right bounds of the column. Center and right justification need an explicit position defined (usually via \<\_move\>) and will  not properly wrap to a new line.

- •

  **width** (length measure) width (length) of **horizontal rule**

  Currently only used for \<hr\>. In the future it may be expanded to other object types. \<hr\> may be permitted in the future to be a percentage of the enclosing parent's width.

- •

  **height** (length measure) height (thickness) of **horizontal rule**

  Currently only used for \<hr\>. In the future it may be expanded to other object types. \<hr\> may be permitted in the future to be a percentage of the enclosing parent's height.

  The equivalent HTML attribute is `"size"`.

- •

  **In plan, but not yet implemented**

  - •

    white-space (treatment of line-ends and various spaces),

  - •

    /\* and \*/ comments in CSS

  - •

    border and border-\* (border properties),

  - •

    padding and padding-\* (padding properties),

  - •

    list-style-image (use an image as a list bullet),

  - •

    margin (update the four `"margin-*"` properties in one setting, add 'auto' value)

  - •

    background-color (also for \<mark\> tag),

See the "Length Measures" section to see what measurements are allowed.

**CAUTION:** comments /\* and \*/ are NOT currently supported in CSS -- perhaps in the future.

Extended CSS properties and values

A number of additional (non-standard) CSS properties and/or values have been defined for additional functionality for `column()`. Note that if you set \_marker-\* properties in a list, all nested lists will, as usual, inherit these properties. If you don't want that, you will need to cancel the new settings by resetting them to standard values in the nested \<ul\> or \<ol\> tag's style.

- •

  **\_marker-before** (constant text to insert *before* an \<ol\> marker, default nothing)

- •

  **\_marker-after** (constant text to insert *after* an \<ol\> marker, default period ".")

- •

  **\_marker-text** (define text to use as marker instead of the system-generated text)

- •

  **\_marker-color** (change color from default, such as color-coded \>ul\> bullets)

- •

  **\_marker-font** (change marker font face (font-family))

- •

  **\_marker-style** (change marker font style, e.g., italic)

- •

  **\_marker-size** (change marker font size)

- •

  **\_marker-weight** (change marker font weight)

- •

  **\_marker-align** (left/center/right justify within marker\_width gutter)

- •

  **list-style-position** standard (inside or outside) or numeric (points or percentage of marker\_width gutter + marker\_gap)

There are additional non-standard CSS "properties" that you would normally  **not** set in CSS. They are internal state trackers:

- •

  **\_parent-fs** (current running font size, in points)

  This is actually the parent of this tag's font-size, which the current tag inherits and may set to a new value if desired (with `"font-size"` property).

- •

  **\_href** (URL for \<a\>, normally provided by href= attribute)

- •

  **\_left** (running number of points to indent on the left, from margin-left and list nesting)

- •

  **\_left\_nest** (amount to indent next nested list)

- •

  **\_right** (running number of points to indent on the right, from margin-right)

### General Comments

The Font Manager system is used to supply the requested fonts, so it is up to the application to preload the desired font information *before* `column()` is called. Any request to change the encoding within `column()` will be ignored, as the fonts have already been specified for a specific encoding. Needless to say, the encoding used in creating the input text needs to match the specified font encoding.

Absent any markup changing the font face or styling, whatever is defined by Font Manager as the *current* font will be what is used. This way, you may inherit the font from the previous `column()`, or call  `"$text-"`font($pdf-\>**get\_font()**, size)\> to set both the font and size, or  just call `"$pdf-"`**get\_font()**\> to set only the font, relying on the `"font_size"`  option or CSS markup to set the size.

Line fitting (paragraph shaping) is currently quite primitive. Words will not be split (hyphenated).  *It is planned to eventually add Knuth-Plass*  *paragraph shaping, along with proper language-dependent hyphenation.*

Each change of font automatically supplies its maximum ascender and minimum descender, the **extents** above and below the text line's baseline. Each block of text with a given face and variant, or change of font size, will be given the same *vertical* extents -- the extents are font-wide, and not determined  on a per-glyph basis. So, unfortunately, a block of text "acemnorsuvwz" will  have the same vertical extents as a block of text "bdfghijklpqty". For a given line of text, the highest ascender and the lowest descender (plus leading) will be used to position the line at the appropriate distance below the previous  line (or the top of the column). No attempt is made to "fit" projections into recesses (jigsaw-puzzle like). If there is an inset into the side of a column, or it is otherwise not a straight vertical line, so long as the baseline fits within the column outline, no check is made  whether descenders or ascenders will fall outside the defined column (i.e.,  project into the inset). We suggest that you try to keep font sizes fairly consistent, to keep reasonably consistent text vertical extents.

### init\_state

```
    %state = PDF::Builder->init_state(%lists)
    %state = PDF::Builder->init_state()
```

This method is used in PDF::Builder::Content::Text to create and initialize  the hash structure that permits transfer of data between `column()` calls, as well as accumulating link information to build intra- and inter-PDF file jumps for a variety of uses.

**%lists** is optional, and allows the user to define tags (which have an id= ) lists for various purposes. These are anonymous lists. Element '\_reft' is  predefined for cross reference targets, and already includes the \<\_reft\> tag  as '\_reft'. **Do not add '\_reft' to the '\_reft' list!** The user may wish to add  other tags (which have id= ) to be used, and define other lists to be  accumulated. For example,

```
    {'_reft' => [ 'h1', 'h2', 'h3', 'h4' ],
     'TOC'   => [ '_part', '_chap', 'h1', 'h2', 'h3' ], }
```

adds the top 4 heading levels to cross references ('\_reft' is already there),  and creates a 5-level list of tags to build a Table of Contents. Additional lists might include for an Index, glossary, List of Tables, List of Figures (Illustrations, Photos), List of Equations, etc. *TOC, Index, etc. have not* *yet been implemented, but are planned for the near future!*

If no `%lists` parameter is given, you will be limited to cross references from \<\_reft\> only, and no entries specifically for TOC etc. will be defined. Remember, only tags with `"id="`s in your markup will be used as link targets.

If you are using \*\*markdown\*\* for your source, you may not be able to define `"id="`s for all your "tags" (HTML tags produced after translation from  markdown), and thus will need to use `"<_reft>"`s as link targets, which  should be passed through to HTML. For applications such as a TOC, you *may*  be able to postprocess the \_reft list to separate out (based on id given) this  large group of target ids into groups for specific purposes, such as a TOC.

```
    %state = PDF::Builder->init_state(%lists)
```

This creates the state structure (hash) to be passed to `column()` calls, and it saves information from invocation to invocation. It must be initialized *before* the first pass of the loop which invokes one or more `column()`  formatting calls at each pass (for a different part of the document).

It is defined in PDF::Builder (Builder.pm) as PDF::Builder::init\_state,  rather than here in PDF::Builder::Content::Text, because `$text` does not  yet exist when it needs to be called.

### pass\_start\_state

```
    $rc = $pdf->pass_start_state($pass_count, $max_passes, \%state)
```

This does whatever is necessary at the *start* of a pass (number `$pass_count`). Currently, this is resetting the 'changed\_target' hash list.

It is defined in PDF::Builder (Builder.pm) as  PDF::Builder::pass\_start\_state, rather than here in  PDF::Builder::Content::Text, because `$text` does not yet exist when it  needs to be called.

### pass\_end\_state

```
    $rc = $text->pass_end_state($pass_count, $max_passes, $pdf, $state, %opts)
```

This examines the state structure (hash), resolves any content changes that need to be made, and builds a list of all refs (by target id `"tgtid"`) which are still changing at this pass. If any have changed, a non-zero return code (number of cases) is returned, but if everything has settled down, the return code is 0.

- $pass\_count

  What pass number we are on. Start at 1, and must be no greater than  `"max_passes"`.

- $max\_passes

  The pass number of the last permitted pass, if reached. We may exit before this if things settle down quickly enough. If

  - 1\.

    page numbers are not output in link text (`"page_numbers == 0"`) \_and\_

  - 2\.

    `"title="` is given in all '\_ref' tags, \_or\_ all \_ref's without title  attributes are backwards references (all forward \_ref's have a title)

  you may often be able to get away with a single pass (`"max_passes == 1"`). You still may be informed that not all cross references have settled.

- $pdf

  The PDF object.

- $state

  Hashref to state structure, which includes, among other things, lists of link sources (\_ref tags) and link targets (\_reft and other listed tags).

- %opts

  Options.

  - 'debug' =\> 1

    Draw a border around the link text (the source, not the target), so you can see where a click would take effect.

  - 'deltas' =\> \[ 20, 20 \]

    To show some context around the target text (if *xyz* fit is used without a specific x and y), the upper left corner of the target window is placed these amounts (units *points*) from the left (delta x) and top (delta y) edges of  the target text. The default is 20 (points) each, roughly a couple of lines'  worth. The left side is limited to the page edge, and the top side is limited to the page top.

    Note that the upper edge of the text is where the *previous* line left off,  so if there is a top margin on the target text (e.g., it's a heading), the offset will be from there, not the text itself, and the view window may  therefore be up higher on the page than you would otherwise expect. This has been known to confuse users with a PDF Reader which displays a fixed-size popup  window showing the target a link will go to, which might even miss the target  text entirely if the deltas are too large.

If all references include their own title string and do **not** show a page  (only the title string as the annotation link text), a document should take  only one pass. Often two passes are enough to resolve even forward references which need to pick up text from later in the document, but sometimes (especially if special formatting of page numbers is involved), a target may move back and forth between two pages and not settle down. In such cases, you may need to simplify or rearrange the text, such as moving a target back from the end of a page, or changing from specialty formats (such as "on following page" to a fixed "on page N".

**Fields in %state structure:**

```
    settings       = hold settings between column() calls
      TBD
    xrefs          = source of link (<_ref>) info needed
      [  ]           = array of each link source
        id             = target's id, tag that defines a target
        fit            = any fit information provided
        tfn            = target filename (FINAL position and name) used for
                         external links
        tppn           = target physical page number (integer > 0)
        sppn           = source physical page number (integer > 0)
        other_pg       = text for "other page" if page_numbers > 0
         prev_other_pg  = previous value (to detect change)
        tfpn           = formatted page number (string, may be '')
        tx,ty          = coordinates of target on page (used for fit)
        title          = text for link. if not defined in <_ref>, use one
                         in <_reft> (if defined), else "natural text" such
                         as heading <hX> child text
         prev_title     = previous value (to detect change)
        tag            = tag that produced this target (useful for formatting,
                         e.g., indenting TOC entries based on hX level)
        click          = [ ] of one or more click areas, each element is
                         [sppn, [x,y, x,y]]
    xreft          = tag that created a target for a link (<_reft> et al.)
      _reft          = entries for cross reference targets (_reft list)
        id
          tfn        = filepath for external links
          tppn       = target physical page number
          tfpn       = target formatted page number
          tx,ty      = coordinates of target on page
          title      = title, defaulting to "natural text", to update source
          tag        = tag type that produced this entry
      $another_list  = other tag list name list of targets (e.g., TOC)
        id...
      etc.
    changed_target = hash of tgtids (in xrefs id) that changed AFTER link text
                     and page text output, requiring another pass
    tag_lists      = anon list of tags (with id) to put in various lists.
                     see 'init_state()' for building tag lists
      _reft          = [ ] predefined for cross references, may add more (such
                       as hX heading tags)
      TOC            = [ ] NOT predefined, add if desired ...TBD
      Index          = [ ] NOT predefined, add if desired, etc. ...TBD
   nameddest = hash of named destinations to be defined
      $name  = name of the destination
        fit  = fit information (location, parms)
        ppn  = physical page number in this PDF
        x,y  = x and y coordinates on page
```

Note that the link text ('title') and any page information ('on page X') need to be output at each pass, to determine where everything is, while other information is stored until the last pass, to actually generate the annotation links. The "last pass" will be either when it is found that all link information has "settled down", or the `"max_passes"` limit is reached.

### unstable\_state

```
    @list = $text->unstable_state(\%state)
```

This returns a list (array) of string target ids (tgtid) which appear to still be changing at the end of the loop, i.e., have not settled down.

If this method is called when `check_state()` returned a 0, the list will be empty. It may also be called at each pass, for diagnostic purposes.