Lenguajes de marcas ligeras
De WikiEducator
Contenido
¿Qué es?
reStructuredText es un lenguaje de marcas ligero, de fácil lectura en su formato de fuente pero muy versátil para producir documentos complejos.
¿Qué puedo hacer?
- Escribo la documentación en texto plano y después la convierto a distintos formatos.
- Soporta versionado porque es texto
- Se puede leer con cualquier editor
Documentación de referencia
- Chuleta ReST
- http://sphinx.pocoo.org/rest.html
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
- http://people.ee.ethz.ch/~creller/web/tricks/reST.html
- Manual de rst2pdf (y rst en general): http://rst2pdf.ralsina.com.ar/ y http://lateral.netmanagers.com.ar/static/manual.pdf
- Presentación rst http://catherinedevlin.pythoneers.com/presentations/rst/olf.html
- Tutorial en francés: http://culot.org/public/Docs/documentation_rest.html
¿Cómo escribo rst?
- Documento de texto
- Escribe un documento de texto plano. Suelen tener extensión .rst o .txt
- Títulos y subtítulos
- Para escribir un título basta con poner símbolos '=' debajo del texto del título, de la siguiente forma:
Título ======
- Los símbolos = puestos debajo del texto deben tener el mismo tamaño que el título.
- Para la escritura de subtítulos y subtítulos de segundo nivel, se utiliza los símbolos '-' y '*', respectivamente. Su utilización es igual que el de los títulos, ejemplo:
Subtítulo --------- Subtítulo de Segundo Nivel ************************** Subtítulo de Tercer Nivel +++++++++++++++++++++++++
- Estilo de texto
- *cursiva* o **negrita**. ``texto en espacio fijo.``
- Saltos de página en pdf
- Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código:
.. raw:: pdf PageBreak
- Listas
- listas con viñetas y numeradas:
* Lista con viñetas * Lista con viñetas
#. Lista numerada #. Lista numeradas
- Imágenes
.. figure:: img/nombre_archivo.png :width: 100% :height: 100 :scale: 50 :alt: texto alternativo
- El campo width indica el tamaño de la imagen en el documento, un 100% indica que utiliza el máximo posible ya sea el tamaño de la imagen o el tamaño de la hoja.
- Más ejemplos con rst
- Ejemplo: http://catherinedevlin.pythoneers.com/presentations/rst/show.rst
- Resultado: http://catherinedevlin.pythoneers.com/presentations/rst/show.html
Herramientas de conversión
- Online: http://www.tele3.cz/jbar/rest/rest.html
- Instalo docutils y rst2pdf. Instalación de doctuils y rst2pdf
- Pandoc http://johnmacfarlane.net/pandoc/
Ejemplos de uso
Abro un terminal. Ejemplo en linux:
$ rst2html <origen.rst> <destino.html> --> crea destino.html $ rst2pdf <origen.rst> --> crea origen.pdfEjemplos:
user@home $ rst2html intro.rst intro.html user@home $ rst2pdf intro.rst user@home $ rst2html --stylesheet=miHojadeEstilos.css doc.rst # ruta de la hoja de estilos
Pandoc
http://johnmacfarlane.net/pandoc/demos.html
- HTML fragment:
pandoc README -o example1.html
- HTML en un fichero
pandoc -s README -o example2.html
- HTML con tabla de contenidos, CSS y pie
pandoc -s -S --toc -c pandoc.css -A footer.html README -o example3.html
- LaTeX:
pandoc -s README -o example4.tex
- reStructuredText:
pandoc -s -w rst --toc README -o example6.text
- Rich text format (RTF):
pandoc -s README -o example7.rtf
- Beamer slide show:
pandoc -t beamer SLIDES -o example8.pdf
- Convertir página web
pandoc -s -r html http://www.gnu.org/software/make/ -o example12.text
- OpenDocument XML:
pandoc README -s -w opendocument -o example20.xml
- ODT (OpenDocument Text, readable by OpenOffice):
pandoc README -o example21.odt
- MediaWiki
pandoc -s -S -w mediawiki --toc README -o example22.wiki
- EPUB ebook:
pandoc -S README -o README.epub
- Word docx:
pandoc -s -S README -o example29.docx
Mejorando la presentación
- Crear estilos personalizados: http://docutils.sourceforge.net/docs/user/slide-shows.html
- Ejemplos de css para probar:
- Temas para S5: http://meyerweb.com/eric/tools/s5/themes/
En Windows
- Instalo Python (http://www.python.org/download)
- Instalo setuptools
- Descargar y ejecutar el archivo peak.telecommunity.com/dist/ez_setup.py desde el intérprete de comandos (cmd)
C:\Python27\python.exe ez_setup.py
- Instalo docutils
- Descargar y descomprimir http://docutils.sourceforge.net/docutils-snapshot.tgz
- Ejecutar el archivo setup.py dentro de la carpeta descomprimida o
C:\Python27\python.exe setup.py install
- Descargar e instalar Reportlab:
- Para 32 bits: http://www.reportlab.com/ftp/reportlab-2.5.win32-py2.7.exe o
- Para 64 bits: http://www.reportlab.com/ftp/reportlab-2.5.win-amd64-py2.7.exe
- Descargar e instalar la última versión del repositorio http://code.google.com/p/rst2pdf/source/checkout. Hace falta un cliente de subversion (como http://tortoisesvn.tigris.org/ ). En el servidor del aula dejamos una copia.
C:\Python27\python.exe setup.py install
Ya está todo instalado! Uso:
C:\Python27\Scripts\rst2html origen.rst destino.html C:\Python27\Scripts\rst2pdf.exe origen.rst [-s estilo.txt] -o destino.pdf
Creación de presentaciones con rst2pdf
Tip: rst2pdf tiene problemas con doctuils 0.8 . Es mejor instalar la versión del repositorio:
$ svn checkout http://svn.berlios.de/svnroot/repos/docutils/trunk/docutils $ cd docutils $ sudo python setup.py install
- Presentaciones: http://lateral.netmanagers.com.ar/tr/es/stories/BBS52.html
- Otro ejemplo con http://fausto23.wordpress.com/2010/10/15/otro-modo-de-hacer-presentaciones/
- Modificación de estilos: http://python.org.ar/pyar/Recetario/EstilosRst2Pdf
- Unos ejemplos para practicar: https://subversion.american.edu/aisaac/misc/
- Comandos de creación
$ rst2pdf -s estilo.txt slides.rst -b1 -o slides.pdf $ rst2pdf -s estilo.txt slides.rst -e inkscape -b1 -o slides.pdf # para poder usar svg
|
Ejemplos para practicar y aprender
En muchos proyectos se usa restructuredtext para documentar y generar distintos formatos de doc. Mira estos ejemplos interesantes:
- Pycon Argentina: Machete de python Repositorio: https://github.com/ralsina/python-cheatsheet/
- Chuleta de expresiones regulares en rst : blog y github
