Diferencia entre revisiones de «Usuario:Lmorillas/modulo lenguajes de marcas/ligeros/rst»

De WikiEducator
Saltar a: navegación, buscar
(→‎Herramientas de conversión)
(→‎Documentación de referencia)
 
(40 revisiones intermedias por el mismo usuario no mostrado)
Línea 1: Línea 1:
−
{{MiTitulo | Restructured Text}}
+
{{MiTitulo | Lenguajes de marcas ligeras}}  
  
−
== ¿Qué es? ==
+
=== ¿Qué es? ===
−
reStructured Text es un sistema de marcado para escribir documentos.
+
  
−
==¿Qué puedo hacer?==
+
reStructuredText es un lenguaje de marcas ligero, de fácil lectura en su formato de fuente pero muy versátil para producir documentos complejos.  
−
* 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 ==  
+
=== ¿Qué puedo hacer? ===
−
* http://sphinx.pocoo.org/rest.html
+
 
−
* http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+
*Escribo la documentación en texto plano y después la convierto a distintos formatos.
−
* http://people.ee.ethz.ch/~creller/web/tricks/reST.html
+
*Soporta versionado porque es texto
 +
*Se puede leer con cualquier editor
 +
 
 +
=== Documentación de referencia ===
 +
 
 +
* [http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html 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
 +
 
 +
* [http://rst2pdf.ralsina.com.ar/handbook.html rst2pdf Handbook]
 +
 
 +
=== ¿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:
  
−
== ¿Cómo escribo rst? ==
 
−
; 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
 
  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:
+
: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
 
  ---------
 
  ---------
Línea 32: Línea 47:
 
  +++++++++++++++++++++++++
 
  +++++++++++++++++++++++++
  
−
; Saltos de página en pdf
+
;Estilo de texto
−
: Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código:
+
:<nowiki>*cursiva* o  **negrita**. ``texto en espacio fijo.`` </nowiki>
 +
 
 +
;Saltos de página en pdf  
 +
:Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código:
 +
 
 
  .. raw:: pdf
 
  .. raw:: pdf
 
   
 
   
−
    PageBreak
+
  PageBreak
 +
 
 +
;Listas
 +
:listas con viñetas y numeradas:
  
−
; Listas
 
−
: listas con viñetas y numeradas:
 
 
  * Lista con viñetas
 
  * Lista con viñetas
 
  * Lista con viñetas
 
  * Lista con viñetas
Línea 46: Línea 66:
 
  #. Lista numeradas
 
  #. Lista numeradas
  
−
; Imágenes
+
;Imágenes
 +
 
 
  .. figure:: img/nombre_archivo.png
 
  .. figure:: img/nombre_archivo.png
−
    :width: 100%
+
  &nbsp;:width: 100%
 +
  &nbsp;:height: 100
 +
  &nbsp;:scale: 50
 +
  &nbsp;: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.
+
: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 ==
+
=== Herramientas de conversión  ===
−
* Instalo [[http://docutils.sourceforge.net '''doctuils''']] y [[http://code.google.com/p/rst2pdf/ '''rst2pdf''']]
+
−
=== Ejemplos de uso ===
+
−
Abro un terminal. '''Ejemplo en linux''':
+
−
  $ rst2html <origen.rst> <destino.html>  --> crea destino.html
+
−
  $ rst2pdf <origen.rst> --> crea origen.pdf
+
  
−
Ejemplos:
+
*Online: http://www.tele3.cz/jbar/rest/rest.html  
−
<source lang="bash">
+
*Instalo [http://docutils.sourceforge.net '''docutils'''] y [http://code.google.com/p/rst2pdf/ '''rst2pdf''']. [[/instalacion_rst2pdf | Instalación de doctuils y rst2pdf]]
−
user@home $ rst2html intro.rst intro.html
+
* Pandoc http://johnmacfarlane.net/pandoc/
  
 +
=== Ejemplos de uso  ===
 +
 +
Abro un terminal. '''Ejemplo en linux''':
 +
 +
$ rst2html &lt;origen.rst&gt; &lt;destino.html&gt;  --&gt; crea destino.html
 +
$ rst2pdf &lt;origen.rst&gt; --&gt; crea origen.pdf
 +
 +
Ejemplos: <source lang="bash">
 +
user@home $ rst2html intro.rst intro.html
 
user@home $ rst2pdf intro.rst
 
user@home $ rst2pdf intro.rst
 +
user@home $ rst2html --stylesheet=miHojadeEstilos.css doc.rst  # ruta de la hoja de estilos
 
</source>
 
</source>
 +
 +
=== 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:
 +
** http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
 +
** http://docutils.sourceforge.net/sandbox/stylesheets/
 +
** http://trac.edgewall.org/browser/trunk/doc/utils/tracsphinx.css
 +
** http://culot.org/public/Docs/docutils.css
 +
** http://rst2a.com/gallery/html/
 +
* 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
 +
<source lang="bash">
 +
$ 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
 +
</source>
 +
{{Actividad|
 +
* Descarga la plantilla de http://lateral.netmanagers.com.ar/static/rst2pdf-slides/slides.style
 +
* Utilízala con el comando anterior
 +
* Modifícala
 +
* Comprueba los cambios
 +
}}
 +
 +
=== Ejemplos para practicar y aprender ===
 +
En muchos proyectos se usa restructuredtext para documentar y generar distintos formatos de doc.
 +
Mira estos ejemplos interesantes:
 +
*[http://www.netmanagers.com.ar/index.php?page=machete-de-python Pycon Argentina: Machete de python] Repositorio: https://github.com/ralsina/python-cheatsheet/
 +
*Chuleta de expresiones regulares en rst : [http://tartley.com/?p=1349 blog] y [https://github.com/tartley/python-regex-cheatsheet github]

Última revisión de 06:48 22 ene 2014


¿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

¿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

Ejemplos de uso

Abro un terminal. Ejemplo en linux: 

$ rst2html <origen.rst> <destino.html>  --> crea destino.html
$ rst2pdf <origen.rst> --> crea origen.pdf
Ejemplos: 
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

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

C:\Python27\python.exe setup.py install

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

Icon present.gif
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



$ 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


Icon activity.jpg

Actividad





Ejemplos para practicar y aprender

En muchos proyectos se usa restructuredtext para documentar y generar distintos formatos de doc. Mira estos ejemplos interesantes:

Obtenido de «https://es.wikieducator.org/index.php?title=Usuario:Lmorillas/modulo_lenguajes_de_marcas/ligeros/rst&oldid=14271»