App-Basis-ConvertText2
view release on metacpan or search on metacpan
docs/README.html view on Meta::CPAN
<li><a href='#12.2_ean8'> 12.2 EAN8</a></li>
<li><a href='#12.3_ean13'> 12.3 EAN13</a></li>
<li><a href='#12.4_coop2of5'> 12.4 COOP2of5</a></li>
<li><a href='#12.5_iata2of5'> 12.5 IATA2of5</a></li>
<li><a href='#12.6_industrial2of5'> 12.6 Industrial2of5</a></li>
<li><a href='#12.7_itf'> 12.7 ITF</a></li>
<li><a href='#12.8_matrix2of5'> 12.8 Matrix2of5</a></li>
<li><a href='#12.9_nw7'> 12.9 NW7</a></li>
<li><a href='#12.10_qr_code'> 12.10 QR code</a></li>
<li><a href='#13_yaml_convert_to_json'>13 YAML convert to JSON</a></li>
<li><a href='#14_table'>14 Table</a></li>
<li><a href='#15_links'>15 Links</a></li>
<li><a href='#16_version_table'>16 Version table</a></li>
<li><a href='#17_start_a_new_page_-_page'>17 Start a new page - page</a></li>
<li><a href='#18_gle_/_glx'>18 Gle / glx</a></li>
<li><a href='#19_gnuplot'>19 Gnuplot</a></li>
<li><a href='#20_gotchas_about_variables'>20 Gotchas about variables</a></li>
<li><a href='#21_using_ct2_script_to_process_files'>21 Using ct2 script to process files</a></li>
</ul>
</div>
<div class='content'>
<p>This document may not be easily readable in this form, try <a href="docs/README.pdf">pdf</a> or <a href="docs/README.html">HTML</a> as alternatives. These have been generated from this file and the software provided by this distribution.</...
<p>This is a perl module and a script that makes use of App::Basis::ConvertText2</p>
<p>This is a wrapper for <a href="http://johnmacfarlane.net/pandoc">pandoc</a> 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 i...
<p>HTML templates can also be used to control the layout of your documents.</p>
<p>The fenced code block handlers are implemented as plugins and it is a simple process to add new ones.</p>
<p>There are plugins to handle</p>
<ul>
<li>ditaa</li>
<li>mscgen</li>
<li>graphviz</li>
<li>uml</li>
<li>gnuplot</li>
<li>gle</li>
<li>sparklines</li>
<li>charts</li>
<li>barcodes and qrcodes</li>
<li>and many others</li>
</ul>
<p>As a perl module you can obtain it from https://metacpan.org/pod/App::Basis::ConvertText2 or install</p>
<pre><code>cpanm App::Basis::ConvertText2</code></pre>
<p>Alternatively it is available from</p>
<p>You will then be able to use the <a href="#using-ct2-script-to-process-files">ct2</a> script to process files</p>
<h2 id="document-header-and-variables"><a name='1_document_header_and_variables'>1 Document header and variables</a></h2>
<p>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.</p>
<p><strong>Example</strong></p>
<pre><code>title: App::Basis::ConvertText2
format: pdf
date: 2014-05-12
author: Kevin Mulholland
keywords: perl, readme
template: coverpage
version: 5</code></pre>
<p>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.</p>
<ul>
<li><em>format</em> shows what output format we should default to.</li>
<li><em>template</em> shows which template we should use</li>
</ul>
<p>The keys may be used as variables in your document or in the template, by upper-casing and prefixing and postfixing percent symbols ‘%’</p>
<p><strong>Example</strong></p>
<pre><code>version as a variable %VERSION%</code></pre>
<p>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.</p>
<p><strong>Example</strong></p>
<pre><code>%TITLE%</code></pre>
<p><strong>Output</strong></p>
<p>App::Basis::ConvertText2</p>
<h2 id="table-of-contents"><a name='2_table_of_contents'>2 Table of contents</a></h2>
<p>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.</p>
<p><strong>Example</strong></p>
<pre><code>%TOC% will show</code></pre>
<p><p>Contents</p>
<ul>
<li><a href='#1_document_header_and_variables'>1 Document header and variables</a></li>
<li><a href='#2_table_of_contents'>2 Table of contents</a></li>
<li><a href='#3_fenced_code-blocks'>3 Fenced code-blocks</a></li>
<li><a href='#4_buffering_data_for_later_use'>4 Buffering data for later use</a></li>
<li><a href='#5_sparklines'>5 Sparklines</a></li>
<li><a href='#6_charts'>6 Charts</a></li>
<li><a href='#6.1_pie_chart'> 6.1 Pie chart</a></li>
<li><a href='#6.2_bar_chart'> 6.2 Bar chart</a></li>
<li><a href='#6.3_mixed_chart'> 6.3 Mixed chart</a></li>
<li><a href='#7_message_sequence_charts_-_mscgen'>7 Message Sequence Charts - mscgen</a></li>
<li><a href='#8_diagrams_through_ascii_art_-_ditaa'>8 DIagrams Through Ascii Art - ditaa</a></li>
<li><a href='#9_uml_diagrams'>9 UML Diagrams</a></li>
<li><a href='#10_graphviz'>10 Graphviz</a></li>
<li><a href='#11_venn_diagram'>11 Venn diagram</a></li>
<li><a href='#12_barcodes'>12 Barcodes</a></li>
<li><a href='#12.1_code39'> 12.1 Code39</a></li>
<li><a href='#12.2_ean8'> 12.2 EAN8</a></li>
<li><a href='#12.3_ean13'> 12.3 EAN13</a></li>
<li><a href='#12.4_coop2of5'> 12.4 COOP2of5</a></li>
<li><a href='#12.5_iata2of5'> 12.5 IATA2of5</a></li>
<li><a href='#12.6_industrial2of5'> 12.6 Industrial2of5</a></li>
<li><a href='#12.7_itf'> 12.7 ITF</a></li>
<li><a href='#12.8_matrix2of5'> 12.8 Matrix2of5</a></li>
<li><a href='#12.9_nw7'> 12.9 NW7</a></li>
<li><a href='#12.10_qr_code'> 12.10 QR code</a></li>
<li><a href='#13_yaml_convert_to_json'>13 YAML convert to JSON</a></li>
<li><a href='#14_table'>14 Table</a></li>
<li><a href='#15_links'>15 Links</a></li>
<li><a href='#16_version_table'>16 Version table</a></li>
<li><a href='#17_start_a_new_page_-_page'>17 Start a new page - page</a></li>
<li><a href='#18_gle_/_glx'>18 Gle / glx</a></li>
<li><a href='#19_gnuplot'>19 Gnuplot</a></li>
<li><a href='#20_gotchas_about_variables'>20 Gotchas about variables</a></li>
<li><a href='#21_using_ct2_script_to_process_files'>21 Using ct2 script to process files</a></li>
</ul>
</p>
<p>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.</p>
<h2 id="fenced-code-blocks"><a name='3_fenced_code-blocks'>3 Fenced code-blocks</a></h2>
<p>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 <a href="http://johnmacfarlane.net/pandoc">pandoc</a> is no exception) to highlight program code.</p>
<p>code-blocks take the form</p>
<p><strong>Example</strong></p>
<pre><code>~~~~{.tag argument1='fred' arg2=3}
contents ...
~~~~</code></pre>
<p>code-blocks <strong>ALWAYS</strong> 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 b...
<p>We use this construct to create our own handlers to generate HTML or markdown.</p>
<p>Note that only code-blocks described in this documentation have special handlers and can make use of extra features such as buffering.</p>
<h2 id="buffering-data-for-later-use"><a name='4_buffering_data_for_later_use'>4 Buffering data for later use</a></h2>
<p>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 .</p>
<p>To store data we use the <strong>to_buffer</strong> argument to any code-block.</p>
<p><strong>Example</strong></p>
<pre><code>~~~~{.buffer to_buffer='spark_data'}
1,4,5,20,4,5,3,1
~~~~</code></pre>
<p>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 <strong>no_output</strong> argument.</p>
<p><strong>Example</strong></p>
<pre><code>~~~~{.sparkline title='green sparkline' scheme='green'
from_buffer='spark_data' to_buffer='greenspark' no_output=1}
~~~~</code></pre>
<p>We can also have the content of a code-block replaced with content from a buffer by using the <strong>from_buffer</strong> argument. This is also displayed in the example above.</p>
<p>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.</p>
<p><strong>Example</strong></p>
<pre><code>%SPARK_DATA% has content 1,4,5,20,4,5,3,1
%GREENSPARK% has a generated image <img src='/tmp/kmulholland/cache/ct2/1f38c66e765de08fb292e4e410263519.png' alt='green sparkline' height='20' width='80' /></code></pre>
<p>Buffering also allows us to add content into markdown constructs like bullets.</p>
<p><strong>Example</strong></p>
<pre><code>* %SPARK_DATA%
* %GREENSPARK%</code></pre>
<p><strong>Output</strong></p>
<ul>
<li>1,4,5,20,4,5,3,1</li>
<li><img src='/tmp/kmulholland/cache/ct2/1f38c66e765de08fb292e4e410263519.png' alt='green sparkline' height='20' width='80' /></li>
</ul>
<h2 id="sparklines"><a name='5_sparklines'>5 Sparklines</a></h2>
<p>Sparklines are simple horizontal charts to give an indication of things, sometimes they are barcharts but we have nice smooth lines.</p>
<p>The only valid contents of the code-block is a single line of comma separated numbers.</p>
<p>The full set of optional arguments is</p>
<ul>
<li>title
<ul>
<li>used as the generated images ‘alt’ argument</li>
</ul></li>
<li>bgcolor
<ul>
<li>background color in hex (123456) or transparent</li>
</ul></li>
<li>line
<ul>
<li>color or the line, in hex (abcdef)</li>
</ul></li>
<li>color
<ul>
<li>area under the line, in hex (abcdef)</li>
</ul></li>
<li>scheme
<ul>
<li>color scheme, only things in red blue green orange mono are valid</li>
</ul></li>
<li>size
<ul>
<li>size of image, default 80x20, widthxheight</li>
</ul></li>
</ul>
<p><strong>Example</strong></p>
<pre><code>~~~~{.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'}
~~~~</code></pre>
<p><strong>Output</strong></p>
<p>here is a standard sparkline</p>
<p><img src='/tmp/kmulholland/cache/ct2/c9a9b4c7e6f8cb1089d82d00ff3eb216.png' alt='basic sparkline' height='20' width='80' /></p>
( run in 1.874 second using v1.01-cache-2.11-cpan-39bf76dae61 )