view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

author: Kevin Mulholland
keywords: perl, readme
template: coverpage
version: 5

This document may not be easily readable in this form, try [pdf](docs/README.pdf) or
[HTML](docs/README.html) as alternatives. These have been generated from this file and the software provided by this distribution.

This is a perl module and a script that makes use of %TITLE%

This is a wrapper for [pandoc] implementing extra fenced code-blocks to allow the
creation of charts and graphs etc.
Documents may be created a variety of formats. If you want to create nice PDFs
then it can use [PrinceXML] to generate great looking PDFs or you can use [wkhtmltopdf] to create PDFs that are almost as good, the default is to use pandoc which, for me, does not work as well.

HTML templates can also be used to control the layout of your documents.

The fenced code block handlers are implemented as plugins and it is a simple process to add new ones.

There are plugins to handle

* ditaa
* mscgen
* graphviz
* uml
* gnuplot
* gle
* sparklines
* charts
* barcodes and qrcodes
* and many others

As a perl module you can obtain it from https://metacpan.org/pod/App::Basis::ConvertText2
or install

    cpanm App::Basis::ConvertText2

Alternatively it is available from

You will then be able to use the [ct2](#using-ct2-script-to-process-files) script to process files

## Document header and variables

If you are just creating simple things, then you do not need a document header, but to make full use of the templating system, having header information is vital.

**Example**

    title: App::Basis::ConvertText2
    format: pdf
    date: 2014-05-12
    author: Kevin Mulholland
    keywords: perl, readme
    template: coverpage
    version: 5

As you can see, we use a series of key value pairs separated with a colon. The keys may be anything you like, except for the following which have special significance.

* *format* shows what output format we should default to.
* *template* shows which template we should use

The keys may be used as variables in your document or in the template, by upper-casing and prefixing and postfixing percent symbols '%'

**Example**

    version as a variable _%VERSION%

If you want to display the name of a variable without it being interpreted, prefix it
with an underscore '_', this underscore will be removed in the final document.

**Example**

    _%TITLE%

**Output**

%TITLE%

## Table of contents

As documents are processed, all the HTML headers (H1..H4) are collected together to make a table of contents. This can be used either in your template or document using the TOC variable.

**Example**

    _%TOC% will show

%TOC%

Note that if using a TOC, then the HTML headers are changed to have a number prefixed to them, this helps ensure that all the TOC references are unique.

## Fenced code-blocks

A fenced code-block is a way of showing that some text needs to be handled differently. Often this is used to allow markdown systems (and [pandoc] is no exception) to highlight program code.

code-blocks take the form

**Example**

    ~~~~{.tag argument1='fred' arg2=3}
    contents ...
    ~~~~

code-blocks **ALWAYS** start at the start of a line without any preceding whitespace.
The 'top' line of the code-block can wrap onto subsequent lines, this line is considered complete when the final '}' is seen. There should be only whitespace after the closing '}' symbol before the next line.

We use this construct to create our own handlers to generate HTML or markdown.

Note that only code-blocks described in this documentation have special handlers and
can make use of extra features such as buffering.

## Buffering data for later use

Sometimes you may either want to repeatedly use the same information or may want to use the output from one of the fenced code-blocks .

To store data we use the **to_buffer** argument to any code-block.

**Example**

~~~~{.buffer to_buffer='spark_data'}
1,4,5,20,4,5,3,1
~~~~

    ~~~~{.buffer to_buffer='spark_data'}
    1,4,5,20,4,5,3,1
    ~~~~

If the code-block would normally produce some output that we do not want displayed at the current location then we would need to use the **no_output** argument.

**Example**

~~~~{.sparkline title='green sparkline' scheme='green'
    from_buffer='spark_data' to_buffer='greenspark' no_output=1}
~~~~

    ~~~~{.sparkline title='green sparkline' scheme='green'
        from_buffer='spark_data' to_buffer='greenspark' no_output=1}
    ~~~~

We can also have the content of a code-block replaced with content from a buffer by using the **from_buffer** argument. This is also displayed in the example above.

To use the contents (or output of a buffered code-block) we wrap the name of the buffer
once again with percent '%' symbols, once again we force upper case.

**Example**

    _%SPARK_DATA% has content %SPARK_DATA%
    _%GREENSPARK% has a generated image %GREENSPARK%

Buffering also allows us to add content into markdown constructs like bullets.

**Example**

    * _%SPARK_DATA%
    * _%GREENSPARK%

**Output**

* %SPARK_DATA%
* %GREENSPARK%

## Sparklines

Sparklines are simple horizontal charts to give an indication of things, sometimes they are barcharts but we have nice smooth lines.

The only valid contents of the code-block is a single line of comma separated numbers.

The full set of optional arguments is

* title
    * used as the generated images 'alt' argument
* bgcolor
    * background color in hex (123456) or transparent
* line
    * color or the line, in hex (abcdef)
* color
    * area under the line, in hex (abcdef)
* scheme
    * color scheme, only things in red blue green orange mono are valid
* size
    * size of image, default 80x20, widthxheight

**Example**

    ~~~~{.buffer to_buffer='spark_data'}
    1,4,5,20,4,5,3,1
    ~~~~

    here is a standard sparkline

    ~~~~{.sparkline title='basic sparkline' }
    1,4,5,20,4,5,3,1
    ~~~~

    or we can draw the sparkline using buffered data

    ~~~~{.sparkline title='blue sparkline' scheme='blue' from_buffer='spark_data'}
    ~~~~

**Output**

~~~~{.buffer to_buffer='spark_data'}
1,4,5,20,4,5,3,1