$width = $content->text_left($text, %opts)

Alias for "text". Implemented for symmetry, for those who use a lot of "text_center" and "text_right", and desire a matching "text_left".

Adds text to the page (left justified), at the current position. Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the right! The width used (in points) is returned.

    $width = $content->text_center($text, %opts)

As "text", but centered on the current point.

Adds text to the page (centered). The width used (in points) is returned.

    $width = $content->text_right($text, %opts)

As "text", but right-aligned to the current point.

Adds text to the page (right justified). Note that there is no maximum width, and nothing to keep you from overflowing the physical page on the left! The width used (in points) is returned.

    $width = $content->text_justified($text, $width, %opts)

As "text", but stretches text using "wordspace", "charspace", and (as a last resort) "hscale", to fill the desired (available) $width. Note that if the desired width is less than the natural width taken by the text, it will be condensed to fit, using the same three routines.

The unchanged $width is returned, unless there was some reason to change it (e.g., overflow).

Options:

'nocs' => value

If this option value is 1 (default 0), do not use any intercharacter spacing. This is useful for connected characters, such as fonts for Arabic, Devanagari, Latin cursive handwriting, etc. You don't want to add additional space between characters during justification, which would disconnect them.

Word (interword) spacing values (explicit or default) are doubled if nocs is 1. This is to make up for the lack of added/subtracted intercharacter spacing.

'wordsp' => value

The percentage of one space character (default 100) that is the maximum amount to add to (each) interword spacing to expand the line. If "nocs" is 1, double "value".

'charsp' => value

If adding interword space didn't do enough, the percentage of one em (default 100) that is the maximum amount to add to (each) intercharacter spacing to further expand the line. If "nocs" is 1, force "value" to 0.

'wordspa' => value

If adding intercharacter space didn't do enough, the percentage of one space character (default 100) that is the maximum additional amount to add to (each) interword spacing to further expand the line. If "nocs" is 1, double "value".

'charspa' => value

If adding more interword space didn't do enough, the percentage of one em (default 100) that is the maximum additional amount to add to (each) intercharacter spacing to further expand the line. If "nocs" is 1, force "value" to 0.

'condw' => value

The percentage of one space character (default 25) that is the maximum amount to subtract from (each) interword spacing to condense the line. If "nocs" is 1, double "value".

'condc' => value

If removing interword space didn't do enough, the percentage of one em (default 10) that is the maximum amount to subtract from (each) intercharacter spacing to further condense the line. If "nocs" is 1, force "value" to 0.

If expansion (or reduction) wordspace and charspace changes didn't do enough to make the line fit the desired width, use hscale() to finish expanding or condensing the line to fit.

    ($width, $leftover) = $content->text_fill_left($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and outputs it left justified. The width actually used, and the leftover text (that didn't fit), are returned.

    ($width, $leftover) = $content->text_fill($string, $width, %opts)

Alias for text_fill_left().

    ($width, $leftover) = $content->text_fill_center($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and outputs it centered. The width actually used, and the leftover text (that didn't fit), are returned.

    ($width, $leftover) = $content->text_fill_right($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and outputs it right justified. The width actually used, and the leftover text (that didn't fit), are returned.

    ($width, $leftover) = $content->text_fill_justified($string, $width, %opts)

Fill a line of 'width' with as much text as will fit, and outputs it fully justified (stretched or condensed). The width actually used, and the leftover text (that didn't fit), are returned.

Note that the entire line is fit to the available width via a call to "text_justified". See "text_justified" for options to control stretch and condense. The last line is unjustified (normal size) and left aligned by default, although the option

Options:

'last_align' => place

where place is 'left' (default), 'center', or 'right' (may be shortened to first letter) allows you to specify the alignment of the last line output.

    ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts)
    ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, %opts)
    $overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts)
    $overflow_text = $txt->paragraph($text, $width,$height, %opts)

Print a single string into a rectangular area on the page, of given width and maximum height. The baseline of the first (top) line is at the current text position.

Apply the text within the rectangle and return any leftover text (if could not fit all of it within the rectangle). If called in an array context, the unused height is also returned (may be 0 or negative if it just filled the rectangle).

$continue is optional, with a default value of 0. An %opts list may be given after the fixed parameters, whether or not $continue is explicitly given.

If $continue is 1, the first line does not get special treatment for indenting or outdenting, because we're printing the continuation of the paragraph that was interrupted earlier. If it's 0, the first line may be indented or outdented.

Options:

'pndnt' => $indent

Give the amount of indent (positive) or outdent (negative, for "hanging") for paragraph first lines). This setting is ignored for centered text.

'align' => $choice

$choice is 'justified', 'right', 'center', 'left'; the default is 'left'. See "text_justified" call for options to control how a line is expanded or condensed if $choice is 'justified'. $choice may be shortened to the first letter.

'last_align' => place

where place is 'left' (default), 'center', or 'right' (may be shortened to first letter) allows you to specify the alignment of the last line output, but applies only when "align" is 'justified'.

'underline' => $distance

'underline' => [ $distance, $thickness, ... ]

If a scalar, distance below baseline, else array reference with pairs of distance and line thickness.

'spillover' => $over

Controls if words in a line which exceed the given width should be "spilled over" the bounds, or if a new line should be used for this word.

$over is 1 or 0, with the default 1 (spills over the width).

Example:

    $txt->font($font,$fontsize);
    $txt->leading($leading);
    $txt->translate($x,$y);
    $overflow = $txt->paragraph( 'long paragraph here ...',
                                 $width,
                                 $y+$leading-$bottom_margin );

Note: if you need to change any text treatment within a paragraph (bold or italicized text, for instance), this can not handle it. Only plain text (all the same font, size, etc.) can be typeset with paragraph(). Also, there is currently very limited line splitting (hyphenation) to better fit to a given width, and nothing is done for "widows and orphans".

    ($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts)
    $overflow_text = $txt->section($text, $width,$height, $continue, %opts)

The $text contains a string with one or more paragraphs $width wide, starting at the current text position, with a newline \n between each paragraph. Each paragraph is output (see "paragraph") until the $height limit is met (a partial paragraph may be at the bottom). Whatever wasn't output, will be returned. If called in an array context, the unused height and the paragraph "continue" flag are also returned.

$continue is 0 for the first call of section(), and then use the value returned from the previous call (1 if a paragraph was cut in the middle) to prevent unwanted indenting or outdenting of the first line being printed.

For compatibility with recent changes to PDF::API2, paragraphs is accepted as an alias for "section".

Options:

'pvgap' => $vertical

Additional vertical space (unit: pt) between paragraphs (default 0). Note that this space will also be added after the last paragraph printed.

See "paragraph" for other %opts you can use, such as "align" and "pndnt".

Alternate name: paragraphs

This is for compatibiity with PDF::API2.

    $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)

Place a line of text at an arbitrary "[$x,$y]" on the page, with various text settings (treatments) specified in the call.

$font

A previously created font.

$size

The font size (points).

$text

The text to be printed (a single line).

Options:

'rotate' => $deg

Rotate $deg degrees counterclockwise from due East.

'color' => $cspec

A color name or permitted spec, such as "#CCE840", for the character fill.

'strokecolor' => $cspec

A color name or permitted spec, such as "#CCE840", for the character outline.

'charspace' => $cdist

Additional distance between characters.

'wordspace' => $wdist

Additional distance between words.

'hscale' => $hfactor

Horizontal scaling mode (percentage of normal, default is 100).

'render' => $mode

Character rendering mode (outline only, fill only, etc.). See "render" call.

'left' => 1

Left align on the given point. This is the default.

'center' => 1

Center the text on the given point.

'right' => 1

Right align on the given point.

'align' => $placement

Alternate to left, center, and right. $placement is 'left' (default), 'center', or 'right'.

Other options available to "text", such as underlining, can be used here.

The width used (in points) is returned.

    ($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:

    * or _ italics, ** bold, *** bold+italic; 
    bulleted list *, numbered list 1. 2. etc.; 
    #, ## etc. headings and subheadings; 
    ---, ===, ___ horizontal rule;
    [label](URL) external links (to HTML page or within this document, see 'a')
    ` (backticks) enclose a "code" section
    

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.

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 subset of HTML markup is used, along with some attributes and CSS. Currently, standard HTML tags

    'i'/'em' (italic), 'b'/'strong' (bold), 
    'p' (paragraph),
    'font' (font face->font-family, color, size->font-size), 
    'span' (needs style= attribute with CSS to do anything useful), 
    'ul', 'ol', 'li' (bulleted, numbered lists), 
    'img' (TBD, image, empty. hspace->margin-left/right, 
           vspace->margin-top/bottom, width, height), 
    'a' (anchor/link, web page URL or this document target #p[-x-y[-z]]), 
    'pre', 'code' (TBD, preformatted and code blocks),
    'h1' through 'h6' (headings)
    'hr' (horizontal rule)
    'br' (TBD, line break, empty)
    'sup', 'sub' (TBD superscript and subscript)
    's', 'strike', 'del' (line-through)
    'u', 'ins' (underline)
    'blockquote' (block quote)
    

and non-standard HTML "tags" (extensions)

    '_marker' (gives ability to modify list markers. if given, must be 
           immediately before a <li> tag. attributes: style). the marker text
           will be filled in for you (if given as empty or blank), and an end 
           tag is optional if the marker text is empty.
    '_move' (gives ability to move anywhere on the current baseline.
           useful for positioning before centering and right-aligning with 
           the text-align CSS property.
           attributes: x = N bare number (pts), Npt, or N% 0/0% = left end,
                        50% = center, 100% = right end set new x position
                        relative to line start and width
                       dx = N, Npt, or N% distance to move right + or left -
                        relative to current position if 'x' not given, or 
                        where 'x' setting left you
           Warning: if you move beyond the baseline in either direction,
                    results are unpredictable)
    '_sl' (simple list, like 'ul' but no marker)
    '_ovl' (TBD -- overline similar to underline/strike-through)
    '_k' (TBD -- kerning left/right shift). up/down too?
    

are supported (fully or in part unless "TBD"), along with limited CSS for color, font-size, font-family, etc. <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, or other such complications as found in a browser's CSS. Sorry!

Supported CSS properties:

    border-* TBD
    color (foreground color)
    display (inline/block)
    font-family (name as defined to FontManager, e.g. Times)
    font-size (pt, bare number = pt, % of current size)
    font-style (normal/italic) 
    font-weight (normal/bold)
    height (pt, bare number) thickness of horizontal rule
    list-style-position (outside, inside, number [%]) [*]
    list-style-type (marker description, see also _marker-text/before/after)
    list-style-image TBD
    margin-top/right/bottom/left (pt, bare number = pt, % of font-size)
      margin TBD update four margin-* properties
    text-decoration (none, underline, line-through, overline, may use more
      than one (except 'none') separated by spaces)
    text-height (leading, as ratio of baseline-spacing to font-size)
    text-indent (pt, bare number = pt, % of current font-size)
    text-align (left/center/right justify at current text position) [**]
    width (pt, bare number) width of horizontal rule
    

[*] Note on list-style-position: 'outside' (default) = 100 (%) indent, 'inside' = 0 indent, numeric value (explicit %) = percentage between inside/0 and outside/100, or a length in pts. A numeric value is an extension to CSS.

[**] Note on text-align: if center or right justified, keep 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.

Non-standard CSS "properties". You may want to set these in CSS:

    _marker-before (constant text to insert before <ol> marker, default nothing)
    _marker-after (constant text to insert after <ol> marker, default period)
    _marker-text (define text to use as marker instead of default)
    _marker-color (change color from default, such as color-coded ul bullets)
    _marker-font (change marker font face)
    _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)
    list-style-position numeric (see previous notes)
    

There are also "marker_width" and "marker_gap" parameters (see above) which position the first line of the list item in a uniform manner, so that all lists more or less align.

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=".

Non-standard CSS "properties". You normally would not set these in CSS:

    _fs (current running font size, in points, on the properties stack)
    _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)
    

Sizes may be '%' (of font-size), or 'pt' (the default unit). More support may be added over time. CAUTION: comments /* and */ are NOT currently supported in CSS -- perhaps in the future.

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.

At some time in the future, PDF::Builder may support additional extended HTML tags and CSS properties in order to better control document layout, such as controls to force a page break at a desired point under a given condition. Simple (markerless) and definition lists, and at least basic table layout, are under consideration. Additional non-standard CSS may also be added.

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

$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 of course, 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:

'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 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.

'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 before the item text starts. The number is a length, in points.

The default is 2 times the font_size passed to column(), and is not adjusted for any changes of font_size in the markup. 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.

'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. The default is "[ 1*$font_size, 0 ]". 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.

'outline' => "color string"

You may optionaly request that the column be outlined in a given color, to aid in debugging fitting problems.

'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.

'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.

'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).

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.

$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.