pandoc
------

Pandoc_ è il coltellino svizzero dei formati di markup e comprende 
una libreria in haskell ed un programma da riga di comando 
che la usa.
Anche se il suo formato principale è markdown_, pandoc supporta 
documenti scritti in un sottoinsieme di reStructuredText, 
e permette di generare numerosi formati.

.. _Pandoc: http://johnmacfarlane.net/pandoc/
.. _markdown: http://daringfireball.net/projects/markdown/

Il comando pandoc riconosce automaticamente che i file su cui sta 
lavorando sono in reStructuredText se hanno estensione ``.rst``, 
altrimenti lo si può specificare con l'opzione ``-f rst``, ad esempio::

   pandoc some_file.rst -o some_file.html

oppure::

   pandoc -f rst some_file.txt -t html5 -o some_file.html

È anche possibile specificare più di un file, che verrà concatenato::

   pandoc -o some_file.html file_1.rst file_2.rst [...]

Per molti formati è possibile scegliere se generare solo uno snippet 
integrabile in altri file, (default) o un documento completo (``-s``).

Contrariamente a docutils, pandoc tende ad ignorare silenziosamente 
i costrutti che non riconosce, generando documenti che in alcuni 
casi possono essere migliori da leggere, ma rischiando di perdere dati.

Formati Generabili
^^^^^^^^^^^^^^^^^^

HTML
~~~~

Pandoc può generare XHTML o HTML5, mediante le opzioni ``-t  html`` 
o ``-t html5`` rispettivamente, ma anche numerosi formati di 
slide basate su HTML, come:

* `Slidy <http://www.w3.org/Talks/Tools/Slidy2/Overview.html>`_ (``-t slidy``);
* `S5 <http://meyerweb.com/eric/tools/s5/>`_ (``-t s5``);
* `DZSlides <http://paulrouget.com/dzslides/>`_ (``-t dzslides``).

LaTeX e PDF
~~~~~~~~~~~

Pandoc può generare documenti in LaTeX (``-t latex``) e, se ha a 
disposizione una distribuzione di TeX compilarli automaticamente 
in PDF (``-t pdf``) usando uno dei principali motori
(``--latex-engine=pdflatex|lualatex|xelatex``).

Oltre ai comuni documenti, è supportata anche la generazione di slide, 
mediante beamer (``-t beamer``).

EPUB
~~~~

Pandoc permette di `creare ebook`_ in formato EPUB (``-t epub``); 
alcuni metadati vengono estratti automaticamente dal documento, 
altri possono essere aggiunti tramite l'opzione 
``--epub-metadata=metadata.xml``, dove ``metadata.xml`` contiene 
i dati mancanti come `Dublin Core Metadata Elements`_.

.. _`creare ebook`: http://johnmacfarlane.net/pandoc/epub.html
.. _`Dublin Core Metadata Elements`: http://dublincore.org/documents/dces/

Word processor
~~~~~~~~~~~~~~

Pandoc supporta i formati più moderni dei maggiori word processor 
(ODT, ``-t odt`` e docx, ``-t docx``), oltre allo storico rich text 
format (``-t rtf``).

Documentazione
~~~~~~~~~~~~~~

Alcuni formati comunemente usati per scrivere documentazione possono 
essere generati da pandoc:

* DocBook (``-t docbook``);
* GNU TexInfo (``-t texinfo``);
* groff man pages  (``-t man``).

Altri markup
~~~~~~~~~~~~

Pandoc può essere usato per convertire documenti verso altri formati 
di markup leggero:

* markdown (``-t markdown``);
* AsciiDoc (``-t asciidoc``);
* Emacs Org-Mode (``-t org``);
* MediaWiki Markup (``-t mediawiki``);
* Textile (``-t textile``);

Conversione a reStructuredText
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Pandoc è anche utile nel caso in cui si voglia passare a reStructuredText 
da altro formato, convertendo i propri documenti precedenti.

I formati di input supportati, specificati con l'opzione ``-f`` 
sono:

* ``markdown``;
* ``textile``;
* ``html``;
* ``docbook``;
* ``latex``.