# Manual de LaTeX/Listados de código/Listados con listings
## El paquete listings, modo de uso

El paquete listings es el de uso habitual para la adición de código fuente de múltiples lenguajes de programación en un documento. Su funcionamiento es parecido al paquete verbatim.
Para utilizar este paquete, se debe utilizar:
* \usepackage{listings}
Este paquete permite el resaltado de los lenguajes de programación más comunes, además de ser configurable. Lo único que se necesita es utilizar el entorno lstlisting:
* \begin{lstlisting}
* El código se inserta aquí.
* \end{lstlisting}
También es posible, y es muy útil, insertar desde un fichero de código fuente. Esto facilita al máximo las modificaciones y pruebas del código a insertar mientras aún lo estás editando ya que las modificaciones que se hagan en el código se reflejarán de forma automática en el documento LaTeX (principio DRY):
* \lstinputlisting{nombre_fichero_codigo.py}
En este ejemplo se insertaría un fichero de código en Python. Lo relevante es que se puede incluir cualquier fichero indicando su nombre completo. El lenguaje que se reconoce no depende de la extensión del fichero ni de ninguna indicación interna al mismo, sino que depende de los ajustes que haya establecido para este paquete en el documento. Por ejemplo, para especificar que se trata del lenguaje Python es necesario expresar lo siguiente:
* \lstinputlisting[language=Python]{nombre_fichero_codigo.py}
También es posible seleccionar qué líneas se desean incluir:
* \lstinputlisting[language=Python, firstline=37, lastline=45]{nombre_fichero_codigo.py}
Lo que es muy útil para mostrar en el documento solamente aquello que sea relevante del código fuente. Si se omiten alguno de estos parámetros, firstline o lastline, que se deben mostrar todas las líneas desde el comienzo o hasta el final, respectivamente.
El siguiente es un documento completo que inserta un programa en Pascal:

### Lenguajes soportados

El paquete listings es capaz de resaltar los siguientes lenguajes:
ABAP$^{2,4}$, ACSL, Ada$^4$, Algol$^4$, Ant, Assembler$^{2,4}$, Awk$^4$, bash, Basic$^{2,4}$, C#$^5$, C++$^4$, C$^4$, Caml$^4$, Clean, Cobol$^4$, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran$^4$, GCL, Gnuplot, Haskell, HTML, IDL$^4$, inform, Java$^4$, JVMIS, ksh, Lisp$^4$, Logo, Lua$^2$, make$^4$, Mathematica$^{1,4}$, Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modelica$^3$, Modula-2, MuPAD, NASTRAN, Oberon-2, Objective C$^5$ , OCL$^4$, Octave, Oz, Pascal$^4$, Perl, PHP, PL/I, Plasm, POV, Prolog, Promela, Python, R, Reduce, Rexx, RSL, Ruby, S$^4$, SAS, Scilab, sh, SHELXL, Simula$^4$, SQL, tcl$^4$, TeX$^4$, VBScript, Verilog, VHDL$^4$, VRML$^4$, XML, XSLT.
Para algunos de ellos, se permiten diferentes dialectos. Para más información, utiliza la documentación que viene con el paquete, debería estar en tu distribución, bajo el nombre listings-*.dvi.

#### Notas

* Soporta Mathematica solamente si se trata de un fichero en texto plano. No se pueden incluir ficheros *.NB., sin embargo, Mathematica puede exportar ficheros fuente formateados para su uso en LaTeX.
* En estos lenguajes es obligatorio especificar el dialecto del lenguaje (por ejemplo: language={[x86masm]Assembler}).
* Modelica se soporta mediante el paquete dtsyntax disponible aquí.
* Para estos lenguajes hay múltiples dialectos soportados: C, por ejemplo, puede ser ANSI, Handel, Objective y Sharp. Ver p. 12 del manual de listings para una introducción a esto.
* Definido como un dialecto de otro lenguaje.

### Parámetros de configuración

Se pueden modificar los parámetros que afectan a cómo se muestra el código. Estos parámetros de configuración se pueden insertar en cualquier parte del documento, antes o después de \begin{document}). A continuación se muestra un ejemplo con todos los parámetros que se puede utilizar como base para modificarlo según las necesidades. El significado de cada parámetro se explica en la propia línea como un comentario.

#### escapeinside

El parámetro escapeinside necesita explicación. La opción escapeinside={A}{B} define los delimitadores de inicio y fin que se utilizarán para permitir la introducción de código LaTeX entre el código, en este caso, que todo el código entre "A" y "B" será interpretado como código LaTeX utilizando el estilo vigente en el entorno listings. En este ejemplo, se interpretan como código LaTeX a partir de %*, hasta que se encuentre el cierre con *).
Hay muchas más opciones, se recomienda revisar la documentación oficial.

### Definición de estilos

Este paquete permite definir estilos. Es decir, perfiles que definen un conjunto de parámetros.
Por ejemplo:
En este ejemplo, se definen dos estilos y se establece uno de ellos 'customc' como el estilo por defecto y la @ como el carácter de escape.
Se puede utilizar así:
El trozo de código C se imprimirá como:
El código se ha compilado con XeLaTeX para facilitar que las exclamaciones funcionen en el trozo de código C.

### Inclusión de ficheros automática

Si se tiene un conjunto de ficheros de código fuente para incluir, se puede uno encontrar repitiendo una y otra vez el mismo texto LaTeX Aquí es donde las macros muestran toda su potencia:
Con este ejemplo, se crea un comando para facilitar al máximo la inclusión de código. Se establece un estilo por defecto para que sea customc. Todos los listados tendrán su nombre el el título: no hay que escribir el nombre del fichero dos veces gracias a la macro.

### Problemas de codificación (¡¡¡IMPORTANTE EN ESPAÑOL!!!)

En el ejemplo anterior, para evitar el problema de codificación que surge con LaTeX y el uso de utf8 dentro de listings, se ha compilado los ejemplos con XeLaTeX.
El problema es que, por defecto, listings no soporta codificación multibyte para el código fuente.
Para poder manejar UTF-8, resulta necesario decirle a listings cómo interpretar los caracteres especiales que surjan entre el código fuente, mediante la definición de los mismos.
Esto se puede hacer de la siguiente forma:
La tabla anterior cubre la mayoría de los caracteres de los idiomas latinos:
Para una explicación más detallada del uso de literate se puede revisar la sección 6.4 en la Documentación de listings.
Otra posibilidad es sustituir el paquete \usepackage{listings} (en el preámbulo) por \usepackage{listingsutf8}.

### Personalización de los títulos

Se pueden tener unos títulos (caption y/o title) muy avanzados gracias al paquete caption. Veamos un ejemplo de uso con listings.