strumenti/docutils: nuovo articolo

1 files changed, 130 insertions, 0 deletions

diff --git a/strumenti/docutils.rst b/strumenti/docutils.rst
new file mode 100644
index 0000000..4e250b6
--- /dev/null
+++ b/strumenti/docutils.rst
@@ -0,0 +1,130 @@
+Docutils
+--------
+
+.. contents::
+
+Docutils_ è una suite per la gestione di documentazione scritta 
+in python; è interamente basata sull'uso di |reST| come formato 
+sorgente e ne comprende le specifiche.
+
+Comprende i moduli python usati dalla maggior parte dei programmi 
+che gestiscono |reST|, ma anche alcuni script usabili per 
+effettuare rapide conversioni da riga di comando.
+
+.. _Docutils: http://docutils.sourceforge.net/index.html
+
+.. |reST| replace:: reStructuredText
+
+Uso
+^^^
+
+Per convertire rapidamente un documento |reST| in ``<formato>`` si usa::
+
+   rst2<formato> [opzioni] [documento [destinazione]]
+
+ad esempio::
+
+   rst2html documento.rst documento.html
+
+L'elenco di opzioni disponibili si ottiene con::
+
+   rst2<formato> --help
+
+e sono documentate in dettaglio nella `configurazione di docutils`_.
+
+.. _`configurazione di docutils`: http://docutils.sourceforge.net/docs/user/config.html
+
+Un semplice esempio di uso dei moduli docutils all'interno di programmi 
+in python è presente nello script ``build.py`` usato per generare 
+questa documentazione; l'equivalente della semplice conversione 
+usata sopra si ottiene con::
+
+   from docutils.core import publish_file
+
+   publish_file(source_path=<documento>,
+                destination_path=<destinazione>,
+                writer_name=<formato>)
+
+ad esempio::
+
+   from docutils.core import publish_file
+
+   publish_file(source_path='documento.rst',
+                destination_path='documento.html',
+                writer_name='html')
+
+Ulteriori dettagli sono ovviamente presenti nella `documentazione 
+di docutils`_
+
+.. _`documentazione di docutils`: http://docutils.sourceforge.net/docs/index.html
+
+Formati generabili
+^^^^^^^^^^^^^^^^^^
+
+HTML
+~~~~
+
+Docutils può ovviamente generare HTML tramite il writer ``html``, 
+usato dal comando ``rst2html``.
+È possibile anche generare delle presentazioni_ compatibili con S5_, 
+un sistema di slideshow in HTML5 e JavaScript; per farlo si usa 
+il comando ``rst2s5`` o il writer ``s5_html``, ad esempio::
+
+   rst2s5 --theme medium-black documento.rst documento.html
+
+Il sito di docutils comprende ulteriore documentazione sugli 
+`strumenti per generare html`_.
+
+.. _S5: http://meyerweb.com/eric/tools/s5/
+.. _presentazioni: http://docutils.sourceforge.net/docs/user/slide-shows.html
+.. _`strumenti per generare html`: http://docutils.sourceforge.net/docs/user/tools.html#html-generating-tools
+
+PDF
+~~~
+
+La generazione di documenti in PDF (ma ovviamente anche PostScript e dvi) 
+è delegata a LaTeX a partire da un ``.tex`` ottenuto dal writer ``latex`` 
+(o dal comando ``rst2latex``). 
+Meglio ancora, specialmente nel caso si usino caratteri di lingue 
+diverse e si voglia ottenere un documento PDF, è usare xeTeX, assieme 
+al writer ``xetex`` o al comando ``rst2xetex``; ad esempio::
+
+   rst2xetex documento.rst documento.tex
+   xelatex documento.tex && xelatex documento.tex && xelatex documento.tex
+
+(dove il comando ``xelatex`` è ripetuto tre volte per essere sicuri 
+che tutti i riferimenti interdocumento siano corretti).
+
+Un problema nel quale si può incappare è che xeTeX non supporta 
+l'inserimento di immagini in svg; per inserire immagini 
+vettoriali è necessario usare PDF.
+
+Sul sito docutils c'è un documento su come `generare LaTeX con docutils`_.
+   
+.. _`generare LaTeX con docutils`: http://docutils.sourceforge.net/docs/user/latex.html
+
+ODT
+~~~
+
+Docutils comprende un writer ``odt`` e relativo programma ``rst2odt`` 
+con i quali `generare file odt`_ a partire da |reST|.
+I risultati non sono ovviamente piacevoli quanto i file generati 
+tramite LaTeX, ma possono essere utili in determinati casi.
+
+.. _`generare file odt`: http://docutils.sourceforge.net/docs/user/odt.html
+
+manpages
+~~~~~~~~
+
+Al fine di completare la documentazione di un programma con una 
+pagina di ``man``, docutils include un writer ``manpage`` 
+e il relativo programma ``rst2man``, che trasformano un 
+documento |reST| che soddisfa determinate convenzioni in 
+una pagina in \*roff visualizzabile con ``man``.
+
+Sul sito docutils si trova della documentazione alle voci 
+manpage_ e rst2man_.
+
+.. _manpage: http://docutils.sourceforge.net/docs/user/manpage.html
+.. _rst2man: http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt
+