view release on metacpan or  search on metacpan

lib/PDF/Builder/Content/Column_docs.pm  view on Meta::CPAN

=item *

![alt text](path_to_image) image, B<NOT> currently supported

=item *

table entries with | and - (or HTML tags) B<NOT> currently supported

=item *

superscripts (^) and subscripts (~) (or HTML tags) B<NOT> currently supported

=item *

definition lists with : B<NOT> currently supported

=item *

task lists - [ ] B<NOT> currently supported

=item *

emojis will B<NEVER> be supported. We have a perfectly good alphabet.

=item *

highlighting (inline == or HTML E<lt>mark>) B<NOT> currently supported

=back

HTML (see below) may be mixed in as desired (although not within "code" blocks 
marked by backticks, where E<lt>, E<gt>, and E<amp> get turned into HTML 
entities, disabling the intended tags).
Markdown will be converted into HTML, which will then be interpreted into PDF.
I<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 B<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.  

=head4 Extended Markdown

CSS (Cascading Style Sheets) may be defined for resulting HTML tags (or "body" 
for global settings), via the C<style=E<gt>> C<column()> option. You may also
prepend a C<E<lt>styleE<gt>> 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 C<{#id_name}>. This is equivalent to C<id="id_name"> in HTML markup.
Although Text::Markdown does not currently support it, C<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 C<column()> to permit a 'title' to be defined
for any tag with child text, by use of C<{^title_text}>. Note that this 'title'
is the I<link title> to be used, B<not> browser style "hover" popup text. It is
the equivalent of C<title="title_text"> in E<lt>a> or E<lt>_ref> HTML markup. 
Any link tag may define the PDF "fit" to use at the target, by 
C<{%fit_type,parm(s)}> or C<fit="fit_type,parm(s)"> in E<lt>a> or E<lt>_ref> 
HTML markup.

There are other HTML equivalents defined by Standard Markdown which may not
be implemented (converted) by Text::Markdown. Among these are C<~~> line-through
(strike-out) and C<===> 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 E<lt>_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
C<column()> (yet). If you are missing a needed feature, ask about our moving it
up on the priority list.

=head3 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 C<column()>. A substantial subset of CSS (Cascading Style Sheets)
is also interpreted by C<column()>, although selectors are primitive compared
to what a browser supports.

=head4 Standard HTML tags

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

=over

=item *

B<E<lt>iE<gt> or E<lt>emE<gt>>
produces italic or slanted/oblique text, where available through FontManager

=item *

B<E<lt>bE<gt> or E<lt>strongE<gt>>
produces bold text, where available through FontManager

=item *

B<E<lt>sE<gt>, E<lt>strikeE<gt>, and E<lt>delE<gt>>
produce text line-through (strike-out or strike-through)

=item *

B<E<lt>uE<gt> and E<lt>insE<gt>>
produce underlined text

=item *

B<E<lt>codeE<gt>>
produce 'code'-style fixed-pitch text

=item *

B<E<lt>h1E<gt> through E<lt>h6E<gt>>
produce level 1 through 6 headings and subheadings

lib/PDF/Builder/Content/Column_docs.pm  view on Meta::CPAN

=item $pass_count

What pass number we are on. Start at 1, and must be no greater than 
C<max_passes>.

=item $max_passes

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

=over

=item 1.

page numbers are not output in link text (C<page_numbers == 0>) _and_

=item 2.

C<title=> is given in all '_ref' tags, _or_ all _ref's without title 
attributes are backwards references (all forward _ref's have a title)

=back

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

=item $pdf

The PDF object.

=item $state

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

=item %opts

Options.

=over

=item 'debug' => 1

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

=item 'deltas' => [ 20, 20 ]

To show some context around the target text (if I<xyz> fit is used without a
specific x and y), the upper left corner of the target window is placed these
amounts (units I<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 I<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.

=back

=back

If all references include their own title string and do B<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".

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