lunes, 23 de marzo de 2009

HAL y las marcas (LaTeX - V)

Nuestro fichero marcado con LaTeX no es una traducción perfecta de nuestro fichero marcado con marcas informales. Ante el desconocimiento de marcas LaTeX apropiadas para los elementos peculiares y, en principio, exclusivos de nuestro texto original (nombre de programa, opción y orden), llegamos al compromiso provisional de suprimir tales marcas.

No hay nada en LaTeX que obligue a una concesión tan poco justa. De hecho, LaTeX proporciona dos marcas, equivalentes al <EM> y al <CODE> de HMTL, que pueden desempeñar perfectamente el mismo papel:

\emph{texto}
Marca el texto como texto enfatizado.

\verb CAR texto CAR
Marca el texto como código de computador. CAR funciona aquí como delimitador y puede ser cualquier carácter que no forme parte del texto que marca. (Los espacios no deben incluirse y se han escrito sólo para facilitar su comprensión). Así, por ejemplo, el fragmento de texto '-dump' se podría marcar de esta forma: \verb!-dump!.


Por si fuera poco, LaTeX dispone también de un entorno semejante a \verb para marcar bloques independientes de código, como el que constituye la penúltima línea de nuestro texto original. Lo que implica que deberíamos haber utilizado una marca diferente para el bloque de código que constituye esa línea. Por ejemplo:

INICIO BLOQUE ORDEN
w3m -dump http://www.w3.org/TR/html401/struct/lists.html
FIN BLOQUE ORDEN


Si, además, concebimos dicha línea como un bloque de código, resulta innecesario situarla ahora como un párrafo aparte y pensar la línea subsiguiente como otro párrafo más. En realidad, esa forma de escribir no sería estructuralmente correcta, si es que tenemos en cuenta el sentido mismo del texto. La multiplicación de párrafos es una consecuencia indeseable de no haber comprendido que la línea en cuestión debe formar parte del mismo párrafo, lo que en ningún caso significa que no pueda tener un valor estructuralmente especial dentro de él, como bloque de código lógicamente independiente. Es notable como LaTeX nos fuerza, pues, a ser más finos a la hora de estructurar nuestra escritura, gracias a la disponibilidad de marcas distintas para unidades lógicas diferentes.

En consecuencia, la parte afectada de nuestro texto con marcas informales se puede reescribir ahora de una forma más precisa:

INICIO PÁRRAFO
Con INICIO NOMBRE PROGRAMAw3mFIN NOMBRE PROGRAMA el proceso de convertir una página web en texto es absolutamente elemental: añadir la opción INICIO OPCIÓN-dumpFIN OPCIÓN. Por ejemplo:
INICIO BLOQUE ORDEN
w3m -dump http://www.w3.org/TR/html401/struct/lists.html
FIN BLOQUE ORDEN
nos devuelve la página dada como argumento, tal cual se presenta en el navegador, pero como puro texto.
FIN PÁRRAFO

Con estas nuevas marcas de LaTeX es casi trivial modificar el fichero txt2latex.sed para que procese estas tres líneas como debe:

s/INICIO NOMBRE FICHERO/\\emph{/g
s/FIN NOMBRE FICHERO/}/g
s/INICIO ORDEN/\\verb!/g
s/FIN ORDEN/\!/g
s/INICIO BLOQUE ORDEN/\n\\begin{verbatim}\n/g
s/FIN BLOQUE ORDEN/\n\\end{verbatim}\n/g

Por otra parte, habría que suprimir, además, la línea de txt2latex.sed que añadía el carácter de escape al guión bajo, puesto que ya no es necesaria: en un fragmento de texto con las marcas LaTeX mentadas los caracteres especiales de LaTeX se interpretan literalmente sin que haya necesidad de escaparlos.

Tras ejecutar el guión generar_latex fichero_etiquetado.txt ---fichero_etiquetado.txt se ha de modificar previamente como acabamos de explicar---, el fichero resultante, fichero_etiquetado.tex tendría el siguiente aspecto:

\documentclass{article}
\usepackage[spanish]{babel}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}

\begin{document}

\section{Navegación gráfica}
Si hubiésemos estado visitando la página con un buen navegador gráfico que disponga de la opción de guardar las páginas web como texto, tendríamos que realizar al menos dos acciones, ambas independientes:

\begin{enumerate}
\item Ir al menú <<Archivo>> del navegador y guardar como texto la página web. (Lo que además implica seleccionar un nombre de fichero y un directorio).
\item Crear en \emph{Vim} una nueva ventana para editar en ella el documento que acabamos de guardar, mediante la orden \verb!:new ruta_fichero!.
\end{enumerate}

\section{Navegación desde consola}
Si navegamos con \emph{w3m}, y gracias a la interacción entre las aplicaciones de consola, bastaría ejecutar una única acción desde el propio \emph{Vim}, que, además, podríamos abreviar para reproducirla en situaciones semejantes. Veamos cómo.

Con \emph{w3m} el proceso de convertir una página web en texto es absolutamente elemental: añadir la opción \verb!-dump!. Por ejemplo:
\begin{verbatim}
w3m -dump http://www.w3.org/TR/html401/struct/lists.html
\end{verbatim}
nos devuelve la página dada como argumento, tal cual se presenta en el navegador, pero como puro texto.
\end{document}

Si el LaTeX básico dispone de marcas suficientes para etiquetar todo nuestro texto original, ¿por que no las comentamos a su debido tiempo? ¿Por qué hemos diferido su explicación hasta ahora?

La razón es que no vamos a utilizar las marcas descritas, sino otras, más elaboradas, que obligan a recurrir a algún paquete que extienda las funcionalidades básicas de LaTeX. Y no las vamos a utilizar, porque, aunque son perfectamente válidas para un texto tan simple como el de nuestro ejemplo, conviene tener noticia de mecanismos más sofisticados y aptos para situaciones más complejas. De paso, veremos tomaremos contacto con el tipo de mecanismos habituales en el uso de paquetes.

Un paquete especialmente indicado para casos en los que hay que introducir código es el paquete listings, que vendrá instalado en cualquier distribución de LaTeX y, por supuesto, en TeX Live. El paquete listings suministra dos marcas parejas al \verb y al entorno verbatim comentados anteriormente. Son las siguientes:

\lstlisting CAR código CAR
Permite marcar fragmentos de código.

\begin{lstlisting}código\end{lstlisting}
Permite marcar bloques de código.


listings, como cualquier paquete, debe cargarse en el preámbulo del documento con la orden:

\usepackage{listings}

Tras ella suele aparecer una orden de configuración de las opciones del paquete. En nuestro caso, es imprescindible, al menos, una opción, la que defina la fuente básica con que se mostrará el código para que se diferencie del texto corriente. \verb y verbatim lo hacían por nosotros, establecían la fuente como perteneciente a la familia Typewriter, pero listings no lo hace por defecto, y no lo hace, porque no presupone por adelantado que nuestro documento pueda contener algo más que código. Debemos pues, excepcionalmente, tocar este aspecto del estilo. La orden que permite refinar la configuración de listings es \lstset{opciones_configuración} y la opción para modificar la familia de la fuente básica de forma que utilice la familia Typewriter es basicstyle=\ttfamily. Por otra parte, listings suele requerir de una disminución del tamaño de la fuente básica cuando las líneas de código son más largas de lo acostumbrado, como la penúltima línea de nuestro texto original. Ahí podemos utilizar la orden \small de LaTeX, que utiliza una fuente más pequeña de la habitual. En nuestro caso concreto, la opción podría aparecer también como parte de la configuración básica, es decir, dentro de \lstset, o bien como opción que matiza un entorno lstlisting en particular. Nosotros vamos a quedarnos con la primera posibilidad, aunque pueda ser discutible desde el punto de vista estético.

Por tanto, y teniendo en cuenta las anteriores explicaciones, deberíamos añadir estas dos líneas al preámbulo de nuestro documento:

\usepackage{listings}
\lstset{basicstyle=\small\ttfamily}


Finalmente sólo falta sustituir los \verb y \verbatim de antes por las marcas equivalentes de listings [Las modificaciones se muestran en azul]:

\documentclass{article}
\usepackage[spanish]{babel}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}

\usepackage{listings}
\lstset{basicstyle=\small\ttfamily}


\begin{document}
\section{Navegación gráfica}
Si hubiésemos estado visitando la página con un buen navegador gráfico que disponga de la opción de guardar las páginas web como texto, tendríamos que realizar al menos dos acciones, ambas independientes:

\begin{enumerate}
\item Ir al menú <<Archivo>> del navegador y guardar como texto la página web. (Lo que además implica seleccionar un nombre de fichero y un directorio).
\item Crear en \emph{Vim} una nueva ventana para editar en ella el documento que acabamos de guardar, mediante la orden \lstinline!:new ruta_fichero!.
\end{enumerate}

\section{Navegación desde consola}
Si navegamos con \emph{w3m}, y gracias a la interacción entre las aplicaciones de consola, bastaría ejecutar una única acción desde el propio \emph{Vim}, que, además, podríamos abreviar para reproducirla en situaciones semejantes. Veamos cómo.

Con \emph{w3m} el proceso de convertir una página web en texto es absolutamente elemental: añadir la opción \lstinline!-dump!. Por ejemplo:
\begin{lstlisting}
w3m -dump http://www.w3.org/TR/html401/struct/lists.html
\end{lstlisting}
nos devuelve la página dada como argumento, tal cual se presenta en el navegador, pero como puro texto.
\end{document}



Resumen

  • LaTeX suele favorecer e, incluso, forzar, al escritor a tomar conciencia plena de la estructura lógica de sus escritos.

  • El paquete listings extiende las funcionalidades básicas de LaTeX para la edición de documentos que contengan cualquier clase de código.

  • La mayoría de los paquetes, como listings, proporcionan marcas u órdenes especializadas que el usuario puede utilizar de acuerdo con sus fines concretos.

  • Las paquetes más versátiles, como listings, proporcionan al usuario la posibilidad de configurar muchos detalles que afectan al resultado final.

2 comentarios:

  1. Buenas, no entiendo el uso del paquete para una sola línea de código ¿Qué sifnifica CAR? , si copio pego literal no funciona \lstlisting CAR código CAR
    Permite marcar fragmentos de código.

    ResponderEliminar
  2. CAR es un comodín para referirse a un carácter delimitador que debe elegir el usuario según el fragmento de código que vaya a etiquetar. No hay que ponerlo literalmente.

    Por ejemplo, la siguiente línea de código en Python, etiquetada con \lstinline, funciona perfectamente con los típicos delimitadores de las órdenes de LaTeX, esto es: '{' y '}'

    \lstinline{println("Hello, World")}

    Sin embargo este otro fragmento, también en Python, produciría error:

    \lstinline{d = {'a': 1, 'b': 1}}

    No funciona porque este fragmento de código en Python requiere él mismo el uso de llaves. Cuando pdflatex procesa el documento no puede inferir que unas llaves son para enmarcar el código que se quiere imprimir y que las otras pertenecen al alfabeto del código mismo. Por eso en ese caso es necesario utilizar otro delimitador para \listinline, por ejemplo:

    \lstinline!d = {'a': 1, 'b': 1}!

    o

    \lstinline$d= {'a': 1, 'b': 1}$

    O cualesquiera otros delimitadores no contenidos en el alfabeto del código que se quiere etiquetar.

    ResponderEliminar