PDF::Builder::Content::Column_docs3pm

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 mdn 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 (— 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

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., "—"). 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.

    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.