Continuando con la serie de artículos relacionados con la construcción de manuales de usuario, hoy revisaremos la tecnología empleada para hacerlo. En primer lugar  revisaremos en que casos se debería utilizar cada una de las herramientas.

Debería usar RestructuredText si voy a:

  • Generar documentación en varios formatos (Por ejemplo HTML y PDF). También es posible convertir Latex a HTML e incluso PDF a HTML, pero su soporte no es tan bueno como el que proporciona un framework como Sphinx.
  • Manuales de Usuario.
  • Cotizaciones.
  • Artículos.

Debería usar Latex si voy a:

  • Hacer un trabajo de grado o un libro largo.
  • Hacer un documento o publicación científica matemático.  También se puede hacer a través de Rest utilizando un plugin que utiliza las librerías matemáticas de Latex.
  • Presentaciones. Tal vez en un futuro reevalúe esto, pero hay que destacar el poder de la clase beamer de Latex.
  • Manuales de Usuario.
  • Cotizaciones.
  • Artículos.

Debería usar un Procesador de texto si voy a:

  • Hacer una carta, un memorando o un documento corto en general. Esta la ventaja de no tener que compilar, por lo que en un documento de una o dos hojas sin formato podría ser más rápido utilizar un procesador de texto.
  • Ojalá que para nada más.

Como se pudo apreciar, tanto RestructuredText como el Latex, se pueden usar para generar cualquier tipo de documentación, lo que buscaremos resolver a continuación es ¿en dónde radica la diferencia?

RST vs Latex

La primera respuesta a esta pregunta es el tiempo, Latex lleva más tiempo de desarrollo lo que se traduce en un herramienta más robusta y con una comunidad más grande. Es mucho más difícil encontrar ayuda para implementar algún tipo de estilo o formato complejo en RestructuredText que en el Latex.

La segunda respuesta es la sintaxis, de la cual se mostrará algunos ejemplos en la próxima tabla, ya que como se podrá apreciar la sintaxis de Restructured Tex suele ser más corta que la de Latex y más fácil de entender y recordar.

Restructured Text vs Latex

Característica Rest Latex
Negrilla **palabra** \textbf{ palabra }
Cursiva *palabra* \textit{ cursiva }

Sección

Subsección

Sub-subsección

 Sección

======

Subsección

————-

Sub-subsección

************

 \section{Sección}

\subsection{Subsección}
\subsubsection{Sub-subsección}
Listas

  • Primer ítem
  • Segundo ítem
  • Tercer ítem
 - Primer ítem

- Segundo ítem

- Tercer ítem

 \begin{itemize}

\item Primer ítem

\item Segundo ítem

\item Tercer ítem

\end{itemize}
Listas numeradas

  1. Primer ítem
  2. Segundo ítem
  3. Tercer item
 #. Primer ítem

#. Segundo ítem

#. Tercer ítem

 \begin{enumerate}

\item Primer ítem

\item Segundo ítem

\item Tercer ítem

\end{enumerate}
Imágenes .. figure:: imagen.jpg \begin{figure}

\includegraphics{imagen.jpg}

\end{figure}
Tabla sencilla

1 2 3
4 5 6
.. list-table::

* – 1
- 2
- 3
* – 4
- 5
- 6

 \begin{table}

\begin{tabular}{ccl}

1 & 2 & 3 \\

4 & 5 & 6 \\

\end{tabular}

\end{table}

La parte más compleja en ambas sintaxis es el manejo de tablas, el uso de tablas complejas (celdas de distinto tamaño entre filas), se maneja en RestructuredText hasta la fecha utilizando ASCII-Art, algo como esto:

+------------+------------+-----------+

| Header 1   | Header 2   | Header 3  |

+============+============+===========+

| body row 1 | column 2   | column 3  |

+------------+------------+-----------+

| body row 2 | Cells may span columns.|

+------------+------------+-----------+

| body row 3 | Cells may  | - Cells   |

+------------+ span rows. | - contain |

| body row 4 |            | - blocks. |

+------------+------------+-----------+

En Latex es necesario agregar algunas sentencias adicionales para indicar los comportamientos distintos de las celdas, por ejemplo:

\begin{tabular}{|l|l|l|}

\hline

\multicolumn{3}{|c|}{Encabezado} \\

\hline

Campo & Campo & Campo \\ \hline

\multirow{4}{*}{Fila} & Campo & Campo  \\

& Campo & Campo \\

& Campo & Campo \\

& Campo & Campo \\ \hline

\end{tabular}

Aún así hay herramientas para facilitar este proceso, por ejemplo en el caso del RestructuredText está el Ascii Art Table, que permite generar tablas a partir de texto, disponible aquí: http://sourceforge.net/projects/tableart/files/

Y para el caso de Latex, hay herramientas para generar las tablas a partir de una hoja de cálculo de open office calc o desde Excel.

Herramienta para generar tablas desde Calc http://calc2latex.sourceforge.net/

Herramienta para generar tablas desde Excel http://cobweb.ecn.purdue.edu/~zhang97/xls2latex/

Para concluir se puede establecer que ambos lenguajes son adecuados para la elaboración de documentación, el texto restructurado se caracteriza por tener una sintaxis más fácil y el Latex por su robustez y que la parte más complicada del proceso es la generación de tablas no simples, que puede ser facilitado a través de algunas herramientas.

A medida que se vaya profundizando en el tema en los siguientes artículos, se podrá apreciar que la verdadera ventaja de estas herramientas es el tiempo de generación de documentos una vez se haya establecido un formato base.

En el próximo artículo se revisará el proceso de instalación de Latex y la construcción de un formato base.

Índice de la Serie de Artículos:

Introducción
RestructuredText vs Latex
Introducción a Latex
Introducción a Sphinx

« »