Documentar Python

Release 2.0

Fred L. Drake, Jr.

16 de octubre de 2000
BeOpen PythonLabs
E-mail: fdrake@beopen.com

Resumen

El lenguaje Python contiene gran cantidad de documentación, mucha de ella contribuida por diversos autores. La
sintaxis de marcado utilizada por Python se basa en LATEX y exige un conjunto importante conjunto de macros espe-
cialmente escritos para documentar Python. Este documento describe las macros introducidas para dar soporte a la
documentación de Python y cómo se deberían utilizar para dar soporte a un amplio rango de formatos de salida.
Este documento describe las clases de documento y marcado especial utilizado en la documentación de Python.
Los autores pueden seguir esta guía, junto con las plantillas proporcionadas con la distribución, para crear o mantener
documentos completos o secciones.

Índice General
1 Introducción 2

2 Estructura de los directorios 2

3 Curso de choque de LATEX 3

4 Clases de documento 4

5 Marcaje especial 4
5.1 Marcas del preámbulo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.2 Marcas de meta-información . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.3 Unidades de información . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.4 Mostrar ejemplos de código . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.5 Marcas en línea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.6 Marcas específicas de módulos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.7 Marcas al nivel de biblioteca . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.8 Marcas de tablas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.9 Referencia de marcas de listas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.10 Marcas para la generación de índices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6 Nombres especiales 13

7 Herramientas de proceso 14
7.1 Herramientas externas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.2 Herramientas internas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
8 Tendencias de futuro 15
8.1 Documentación estructurada . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
8.2 Foros de discusión . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

1 Introducción
La documentación de Python suele ser considerada de buena calidad para un lenguaje de programación gratuito. Hay
varios motivos, siendo el más importante el temprano compromiso del creador de Python, Guido van Rossum, con
la provisión de documentación sobre el lenguaje y sus bibliotecas y la continua aparición de voluntarios para crear y
mantener documentación.
El compromiso de la comunidad toma muchas formas, desde la creación a informes de error a las simples quejas
cuando la documentación pudiera ser más completa o fácil de usar. Todas estas formas de realimentación desde la
comunidad han demostrado su utilidad durante el tiempo en el que he estado involucrado en el mantenimiento de la
documentación.
Este documento va dirigido a autores y potenciales autores de documentación para Python. Más concretamente, es
para gente que contribuya a la documentación estándar y desarrolle documentos adicionales utilizando las mismas
herramientas que los documentos estándar. Esta guía será menos útil para los autores que utilicen las herramientas
de documentación de Python para otros temas y aún menos útil para los autores que no utilicen estas heramientas en
absoluto.
El material de esta guía va dirigido a asistir a los autores que utilicen las herramientas de documentación de Python.
Icluye información sobre la distribución en código fuente de la documentación estándar, una discusión sobre los
tipos de documentos, material de referencia sobre las marcas definidas en las clases de documentos, una lista de
herramientas externas necesarias para el procesado de los documentos y material de referencia sobre las herramientas
proporcionadas con los recursos de la documentación. Al final hay también una sección que discute el futuro de la
documentación de Python y una lista de material de referencia.

2 Estructura de los directorios

La distribución fuente de la documentación estándar de Python contiene muchos directorios. A pesar de no es necesario
que los documentos de terceros se coloquen en esta estructura o una similar, puede ayudar saber dónde buscar ejemplos
y herramientas al desarrollar nuevos documentos usando las herramientas de documentación de Python. Esta sección
describe esta estructura de directorios.
Las fuentes de la documentación suelen estar ubicadas inmediatamente dentro de la distribución fuente de Python en
el directorio ‘Doc/’, pero no dependen de la distribución fuente de Python en modo alguno.
El directorio ‘Doc/’ contiene varios ficheros y subdirectorios. Los ficheros son autoexplicativos. Incluyen un
‘README’ (leeme) y un ‘Makefile’ (fichero de dependencias para la generación de la documentación final). Los
directorios se dividen en tres categorías:

Fuentes de documentos
Las fuentes LATEX de cada documento se sitúan en un directorio aparte. Estos directorios reciben nombres de
tres caracteres:

2 2 Estructura de los directorios

 Directorio Título del documento
api/ La API de Python/C
dist/ Distribución de módulos Python
doc/ Documentar Python
ext/ Extensión y empotrado del intérprete de Python
inst/ Instalación de módulos Python
lib/ Referencia de la biblioteca de Python
mac/ Referencia de módulos de Macintosh
ref/ Manual de referencia de Python
tut/ Guía de aprendizaje de Python

Salida dependiente del formato

La mayoría de los formatos de salida tienen un directorio que contiene un ‘Makefile’ que controla la generación
del formato y recoge la salida de los documentos finales. Las únicas variaciones sobre esta categoría son el
formato PDF (Portable Document Format, Formato portátil de documento) y el formato PostScript, recogidos
en los directorios ‘paper-a4/’ y ‘paper-letter/’ (esto causa que los ficheros temporales creados por LATEX queden
en el mismo lugar para cada tamaño de papel, en donde pueden ser ignorados fácilmente).

Directorio Formatos de salida

html/ Salida HTML
info/ Salida en info GNU
paper-a4/ PDF y PostScript, A4
paper-letter/ PDF y PostScript, papel US-Letter (carta)

Archivos adicionales
Se usan directorios adicionales para alamacenar archivos adicionales que utilizan los diversos procesos. Se
incluyen directorios para las clases de documentos LATEX compartidas, soporte LATEX2HTML, plantillas para
diversos componentes de los documentos y los guiones usados para realizar diversos pasos del proceso de
formato.

Directorio Contenido
perl/ Suporte al procesado LATEX2HTML
templates/ Plantillas para documentos fuente
texinputs/ Implementación del estilo LATEX
tools/ Guiones de procesado a medida

3 Curso de choque de LATEX

Esta sección es una breve introducción a conceptos y sintaxis de LATEX, para proporcionar a los autores suiciente
información para crear documentos sin tener que convertirse en “TEXnicos”.
Quizás el concepto más importante a tener presente al poner marcas a la documentación de Python es que, mientras
TEX no tiene estructura, LATEX se diseñó como una capa sobre TEX con soporte específico de marcaje estructurado.
La intención del marcaje específico de Python esextender la estructura proporcionada por las clases de documento
estándar de LATEX para dar soporte a información adicional específica de Python.
Los documentos LATEX contienen dos partes: el preámbulo y el cuerpo. El preámbulo se usa para especificar ciertos
metadatossobre el propio documento, tales como el título, la lista de autores, la fecha y la clase a la que pertenece
el documento. Se puede incluir información adicional para controlar la generación de índices y el uso de bases de
datos biliográficas. En la mayoría de los casos, se puede crear el preámbulo copiándolo de un documento existente y
modificando los detalles relevantes.
Se utiliza la clase de un documento para ubicarlo dentro de una amplia categoría de documentos y fijar algunas
propiedades de formato fundamentales. En la documentación de Python se usan dos clases: La clase manual y la clase

3
howto (cómo). Estas clases también definen el marcaje adicional utilizado para documentar conceptos y estructuras
propios de Pyton. Hay información específica sobre estas clases en la sección posterior 4, “Clases de documento”. Lo
primero que aparece en el preámbulo es la declaración de la clase del documento.
Tras la declaración de la clase, pueden venir algunas macros utilizadas para proporcionar información adicional sobre
el documento y declarar marcas adicionales. El preámbulo no debe generar salida, por lo que no se debe incluir texto
libre en él.
El cuerpo del documento sigue al preámbulo y contiene todos los componentes impresos del documento más su
marcaje estructurado.

4 Clases de documento
Se definen dos clases de documento LATEX específicas para usarlas con la documentación de Python. La clase manual
se usa para los documentos extensos, divididos en capítulos, y la clase howto (cómo), utilizada para documentos más
breves.
Los documentos manual son más extensos y se utilizan para la mayoría de los documentos estándar. Esta clase de
documento se basa en la clase estándar de LATEX report y recibe un formato muy similar a la un extenso informe
técnico. El Manual de referencia de Python es un buen ejemplo de documento manual la Referencia de bibliotecas
de Python sirve como ejemplo extenso.
Los documentos howto son más cortos y no tienen la extensa estructura de los documentos manual. Esta clase se
basa en la clase estándar de LATEX article (artículo) y recibe un formato similar al los “HOWTO” del Proyecto
de documentación de Linux (LDP en inglés), basados en el software LinuxDoc. La intención original de la clase
del documento era que representara un papel similar a la serie de HOWTO del LDP, pero la validez de la clase ha
resultado ser más amplia. Esta clase se utiliza para documentos “cómo” (este documento sirve de ejemplo) y para
manuales de referencia más breves para bibliotecas de módulos pequeñas y homogéneas. Como ejemplo de este uso,
sirven los documentos estándar Módulos de la biblioteca Macintosh y Using Kerberos from Python (Uso de Kerberos
desde Python), que contiene material de referencia de un paquete de extensión. Estos documentos equivalen de manera
burda a un solo capítulo de lo que sería una obra más extensa.

5 Marcaje especial
Las clases de documentos Python definen muchos entornos y macros nuevos. Esta sección contiene el material de
referencia relativo a estos servicios.

5.1 Marcas del preámbulo

\release{ver}
Indica el número de versión del software descrito en el documento.
\setshortversion{sver}
Indica el número de versión “corto” del software descrito en el documento.

5.2 Marcas de meta-información

\sectionauthor{author}{email}
Identifica al autor de la sección en curso. author debería ser el nombre del autor de modo tal que se pudiera
presentar en el documento final (aunque no se hace) y email debería ser la dirección de correo electrónico del
autor. La parte del dominio de la dirección debería aparecer en minúsculas.
No se genera salida de esta marca, sino que se utiliza para seguir la pista de las contribuciones.

4 5 Marcaje especial
5.3 Unidades de información

Se utilizan varios entornos para describir servicios específicos proporcionados por los módulos. Los parámetros de
cada entorno proporcionan información básica sobre lo que se está describiendo y su contenido proporciona la des-
cripción. La mayoría de estos entornos generan entradas en el índice general (si se genera para el documento en
cuestión). Si no se desea generar entradas en el índice, se dispone de variaciones del entorno que no lo hacen. Los
entornos tienen nombres del estilo de serviciodesc, siendo la variante que no genera índice serviciodescni. La lista
posterior incluye explícitamente las variantes disponibles.
Para cada uno de estos entornos, el primer parámetro, nombre, proporciona el nombre mediante el cual se accede al
servicio.
Los entornos que describen servicios de los objetos dentro de un módulo, tales como métodos o atributos, permiten un
parámetro opcional nombre de tipo. Cuando el servicio es un atributo de instancias de clase, sólo es necesario propor-
cionar nombre de tipo si la clase no ha sido la última en definirse en el módulo, ya que el valor nombre de la última
classdesc se usa por omisión. En el caso de los servicios de tipos internos o de extensión, se debe proporcionar
siempre el nombre de tipo. Otro caso especial lo constituyen los métodos y miembros de “protocolos” generales, como
los protocolos de formato y escritura descritos en el módulo formatter: Éstos pueden documentarse sin ninguna
clase de implementación y siempre necesitarán el parámetro nombre de tipo.
\begin{datadesc}{nombre}
\end{datadesc}
Este entorno se usa para documentar los datos globales de un módulo, incluyendo tanto variables como valores
utilizados como “constantes definidas”. Este entorno no se usa para documentar las clases y atributos del objeto.
\begin{datadescni}{nombre}
\end{datadescni}
Como datadesc, pero no afecta al índice.
\begin{excdesc}{nombre}
\end{excdesc}
Describe una excepción.
\begin{funcdesc}{nombre}{parámetros}
\end{funcdesc}
Describe una función al nivel del módulo. Los parámetros no deberían incluir los paréntesis de la sintaxis de
llamada. Los métodos de los objetos no se documentan con este entorno. Sí se documentan con este entorno los
métodos de objetos enlazados colocados en el espacio nominal del módulo como parte de su interfaz pública,
ya que equivalen a funciones normales para la mayoría de los propósitos.
La descripción debería incluir información sobre los parámetros requeridos y cómo se usan (especialmente si se
modifican los objetos mutables pasados como parámetros), los efectos secundarios y posibles excepciones. Se
puede añadir un pequeño ejemplo.
\begin{funcdescni}{nombre}{parámetros}
\end{funcdescni}
Como funcdesc, pero no afecta al índice.
\begin{classdesc}{nombre}{parámetros del constructor}
\end{classdesc}
Describe una clase y su constructor. Los parámetros del constructor no deben incluir el parámetro self ni los
paréntesis de la sintaxis de llamada.
\begin{memberdesc}[nombre de tipo]{nombre}
\end{memberdesc}
Describe un atributo del objeto. La descripción debe incluir información del tipo de dato esperado y si se puede
cambiar directamente.
\begin{memberdescni}[nombre de tipo]{nombre}
\end{memberdescni}

5.3 Unidades de información 5

 Como memberdesc, pero no afecta al índice.
\begin{methoddesc}[nombre de tipo]{nombre}{parámetros}
\end{methoddesc}
Describe un método del objeto. Los parámetros no deben incluir el parámetro self ni los paréntesis de la sintaxis
de llamada. La descripción debe incluir información análoga a la descrita en funcdesc.
\begin{methoddescni}[nombre de tipo]{nombre}{parámetros}
\end{methoddescni}
Como methoddesc, pero no afecta al índice.

5.4 Mostrar ejemplos de código

Los ejemplos de código fuente de Python o sesiones interactivas se representan con el entorno verbatim. Este entor-
no es parte estándar de LATEX. Es importante usar sólo espacios para el sangrado porque TEX descarta los tabuladores
en lugar de convertirlos en espacios.
La representación de una sesión interactiva requiere la inclusión de los indicadores y de la salida junto con el código
de Python. No se requieren marcas especiales para las sesiones interactivas.
Dentro del entorno verbatim, no hace falta marcar los caracteres especiales de LATEX en modo alguno. El ejemplo
entero se representará utilizando un tipo de letra de ancho fijo. No se intenta embellecer el resultado en modo alguno,
pues el entorno debe funcionar para ejemplos de código Python y otros.
El Grupo de interés especial de documentación ha discutido varias maneras de crear presentaciones de código embe-
llecido. Se puede consultar la zona de Doc-SIG en la sede Web de Python si se desea más información.

5.5 Marcas en línea

Las macros descritas en esta sección se usan para casi cualquier cosa dentro del texto del documento. Se pueden usar
tanto en las cabeceras (aunque se debería evitar cualquier cosa relitiva a hiperenlaces) como en el cuerpo del texto.
\bfcode{texto}
Como \code, más negrita.
\cdata{nombre}
El nombre de una variable de C.
\cfunction{nombre}
El nombre de una función C. nombre debe incluir el nombre de la función y los paréntesis finales.
\character{carácter}
Un carácter considerado como tal, más que como una cadena de un solo byte. El carácter se presentará como
con \samp.
\citetitle[url]{título}
El título de una publicación a la que se hace referencia. Si se especifica url, el título será un hiperenlace en el
formato HTML.
\class{nombre}
Un nombre de clase. Puede incluir puntos.
\code{texto}
Un breve fragmento de código o valor de constante literal. Típicamente, no debe incluir espacios, porque no se
añaden comillas.
\constant{nombre}
El nombre de una constante “definida”. Puede ser un #define de C o una variable de Python cuyo valor no
debe cambiar.

6 5 Marcaje especial
\ctype{nombre}
El nombre de un typedef o estructura de C. Utiliza \ctype{struct struct_tag} para estructuras
definidas sin typedef para dejar claro que se requiere struct.
\deprecated{versión}{qué hacer}
Declara lo que sea como obsoleto a partir de la versión version. El texto incluido en qué hacer debe recomendar
alternativas.
\dfn{término}
Marca la aparición en el texto de término que define el término. No se genera una entrada en el índice.
\e
Produce una barra invertida. Viene bien en \code y macros similares, y sólo se define allí. Para crear una
barra invertida en texto normal (como el contenido de una macro \file), se debe usar la macro estándar
\textbackslash.
\email{dirección}
Una dirección de correo electrónico. Observa que no se genera un hiperenlace en ninguno de los formatos de
salida posibles. La parte del dominio debe aparecer en minúsculas.
\emph{texto}
Texto resaltado. Se presentará en tipo de letra cursiva.
\envvar{nombre}
Una variable de entorno. Se genera una entrada en el índice.
\exception{nombre}
El nombre de una excepción. Puede incluir puntos.
\file{fichero o directorio}
El nombre de un fichero o directorio. En la salida a PDF o a PostScript, se utilizan comillas simples y un cambio
de tipo de letra. En HTML no se incluyen comillas. Ojo: La macro \file no se puede usar en el contenido de
un título de sección por limitaciones de proceso.
\filenq{fichero o directorio}
Como \file, pero nunca se usan comillas simples. Se puede usar en tablas si una columna sólo ha de contener
nombre de ficheros o directorios. Ojo: La macro \filenq no se puede usar en el contenido de un título de
sección por limitaciones de proceso.
\function{nombre}
El nombre de una función Python. Puede incluir puntos.
\kbd{secuencia de teclas}
Marca una secuencia de pulsaciones de teclas. La forma de secuencia de teclas puede depender de convenciones
especificas de la plataforma o de la aplicacion. Por ejemplo, una secuencia de teclas de xemacs puede marcarse
como \kbd{C-x C-f}.
\keyword{nombre}
El nombre de una palabra clave de un lenguaje de programacion
\makevar{nombre}
El nombre de una variable de make.
\manpage{nombre}{seccion}
Una referencia a una pagina de manual U NIX.
\member{nombre}
El nombre de un atributo de un objeto.
\method{nombre}
El nombre de un método de un objeto. nombre debe incluir el nombre del método y los paréntesis finales. Puede
incluir puntos.

5.5 Marcas en línea 7

\mimetype{nombre}
El nombre de un tipo MIME.
\module{nombre}
El nombre de un módulo o paquete . Puede incluir puntos.
\newsgroup{nombre}
El nombre de un grupo de noticias de USENET.
\program{nombre}
El nombre de un programa ejecutable. Puede ser diferente del nombre del fichero en alguna plataforma. En
particular, la extensión ‘.exe’ (u otra) debe omitirse en los programas de DOS y Windows.
\programopt{opción}
Una opción de línea de órdenes de un programa ejecutable. Debe usarse sólo para opciones de “disparo” e incluir
el guion inicial.
\longprogramopt{opción}
Una opción larga de línea de órdenes de un programa ejecutable. Debe usarse sólo para nombres de opción
largos que serán prefijados opr dos guiones. No se deben proporcionar los guiones como parte de la opción.
\pep{número}
Referencia a una Propuesta de mejora de Python (PEP). Genera los elementos de índice apropiados. Se genera
el texto ‘PEP número’. En la salida a HTML, el texto es un hipervínculo a la copia electrónica de la PEP
especificada.
\refmodule[clave]{nombre}
Como \module, pero genera un hipervínculo a la documentación del módulo nombrado. Observa que el \de-
claremodule correspondiente debe estar en el mismo documento. Si el \declaremodule define una clave
de un módulo diferente del nombre del módulo, se debe proporcionar también como clave a la macro \ref-
module.
\regexp{string}
Marca una expresión regular.
\rfc{número}
Una referencia a una Petición de comentarios (en inglés, RFC). Genera entradas apropiadas en el índice. Se
genera el texto ‘RFC número’. En la salida HTML, este texto es un hipervínculo a una copia electrónica de la
RFC especificada.
\samp{texto}
Un breve ejemplo de código, mayor que el que de daría mediante \code. Como se añaden comillas, se aceptan
espacios.
\shortversion
El número de versión “corto” del software documentado, especificado mediante la macro \setshortver-
sion en el preámbulo. En Python, el múmero corto de versión lo forman los primeros tres caracteres del valor
de sys.version. Por ejemplo, las versiones 2.0b1 y 2.0.1 tienen el mismo número de versión, 2.0. Puede que
esto no sea palicable a todos los paquetes. Si no se usa \setshortversion, produce una expansión vacía.
Vea también la macro \version.
\strong{texto}
Texto muy resaltado. Se presentará mediante un tipo de letra en negrita.
\url{url}
Una URL (o URN). La URL se presentará como texto. En la salida HTML y PDF, la URL será también un
hipervínculo. Se puede usar para referencias externas. Observa que muchos caracteres son especiales para LATEX
y esta macro no hace siempre lo esperado. En particular, el carácter (‘~’) no se trata de la manera adecuada.
Funciona si se codifica hexadecimalmente, es decir, como ‘%7e’.
\var{nombre}

8 5 Marcaje especial
 El nombre de una variable o parámetro formal dentro de una frase.
\versión
El número de versión del software descrito, especificado con \release en el preámbulo. Consultar la macro
\shortversion.
\versionadded{versión}
La versión de Python en que se agregó la característica descrita a la biblioteca o API. Se añade típicamente al
final del primer párrafo de la descripción, antes de las notas de disponibilidad. Se debe elegir la ubicación para
que la explicación tenga sentido, por lo que variará según los casos.
\versionchanged[explicación]{versión}
La versión de Python en que se cambió la característica mencionada (nuevos parámetros, cambio de efectos
secundarios. . . ). explicación debería ser una breve explicación del cambio, de un solo fragmento de frase, sin
poner en mayúscula la primera letra. El proceso de formato agregará un punto al final. Se añade típicamente al
final del promer párrafo de la descripción antes de las notas de disponibilidad y después de \versionadded.
Se debe escoger la ubicación para que la explicación tenga sentido.

5.6 Marcas específicas de módulos

Las marcas descritas en esta sección se usan para proporcionar información sobre el módulo que se está documentando.
Al principio de la sección que documenta un módulo aparece un uso típico de estas marcas. Un posible ejemplo tendría
este aspecto:
\section{\module{magro} ---
Acceso al servicio de MAGRO}

\declaremodule{extension}{magro}
\platform{Unix}
\modulesynopsis{Acceso al servicio de MAGRO de \UNIX{}.}
\moduleauthor{Pepita Pérez Pérez}{pepita.perezperez@chimpanfonia.org}

Los paquetes de Python — colecciones de módulos que se pueden describir como una unidad — se documentan con las
mismas marcas que los módulos. El nombre de un paquete de un módulo debe escribirse “completamente calificado”
(es decir, debe incluir el nombre del paquete). Por ejemplo, el módulo “cucu” del paquete “tras” debe marcarse como
‘\module{cucu.tras}’ y el principio de la sección de referencia aparecería así:

\section{\module{cucu.tras} ---
Módulo del paquete \module{tras}}

\declaremodule{extensión}{cucu.tras}
\modulesynopsis{Fastuoso módulo del paquete \module{tras}.}
\moduleauthor{Pepita Pérez}{pepita.perezperez@chimpanfonia.org}

Observa que el nombre de un paquete también se marca con \module.

\declaremodule[clave]{tipo}{nombre}
Requiere dos parámetros: el tipo de módulo (‘standard’, ‘builtin’, ‘extension’ o ‘’) y el nombre del
módulo. Se debe dar un parámetro opcional como base de la “clave” del módulo utilizada para enlazar con,
o hacer referencia a, la sección. La “clave” debe darse sólo si el nombre del módulo contiene caracteres de
subrayado y debe ser el nombre sin los caracteres de subrayado. Observa que el parámetro tipo debe ser uno de
los valores enumerados o se mostrará un mensaje de error. Para los módulos contenidos en paquetes, se debe
dar el nombre completamente calificado como nombre. Esta declaración debe ser lo primero tras la \section
utilizada para presentar el módulo.

5.6 Marcas específicas de módulos 9

\platform{especificaciones}
Especifica la portabilidad del módulo. especificaciones es una lista de claves separadas por comas que especifica
en qué plataformas está disponible el módulo. Las claves son identificadores cortos. Las claves que se usan en
la actualidad son: ‘IRIX’, ‘Mac’, ‘Windows’ y ‘Unix’. Es importante usar una clave ya utlizada cuando sea
posible. Se utiliza para proporcionar anotaciones en el Índice de módulos y en las salidas a formato HTML y
GNO info.
\modulesynopsis{texto}
texto es una breve descripción “en una línea” del módulo que se pueda usar como parte de la introducción al
capítulo. Deba aparecer tras \declaremodule. La sinopsis se utiliza para contruir el contenido de la tabla
insertada como \localmoduletable. No se genera salida de texto en la ubicación de la marca.
\moduleauthor{nombre}{email}
Esta macro se usa para codificar información sobre quién es el autor de un módulo. Actualmente, no genera
texto, pero ayuda a determinar el origen del módulo.

5.7 Marcas al nivel de biblioteca

Estas marcas se usan al describir una selección de módulos. Por ejemplo, el documento Módulos de biblioteca de
Macintosh lo utiliza como ayuda para proporcionar un resumen de los módulos de la colección y mucho capítulos de
la Referencia de bibliotecas Python lo usan con el mismo propósito.
\localmoduletable
Si existe un fichero ‘.syn’ para el capítulo actual (o para el documento completo en los documentos howto), se
genera una synopsistable con los contenidos cargados del fichero ‘.syn’.

5.8 Marcas de tablas

Se definen tres entornos de tablas de propósito general, que se deben usar siempre que sea posible. Estos entorno se
han definido para proporcionar tablas de anchuras específicas con algunas ventajas de cara al formato. Estos entornos
no son repuestos de propósito general de los entornos de tablas estándar de LATEX, pero son más adecuados para las
herramientas de proceso de documentación de Python. En particular, ¡el HTML generado tiene buen aspecto! Tambien
es mejor de cara a la posible futura conversión a SGML (consultar la sección 8, “Tendencias de futuro”).
Cada entorno se denomina tablecols, donde cols indica el número de columnas de la tabla, especificado en números
romanos en minúscula. Dentro de cada uno de estos entornos se define una nueva macro, \linecols, donde cols
concuerda con el valor cols del entorno de tabla correspondiente. Hay soporte para valores de cols para ii, iii y iv.
Todos estos entornos se construyen sobre el entorno tabular. También se proporcionan variaciones basadas en el
entorno longtable.
Observa que todas las tablas de la documentación estándar utilizan líneas verticales entre las columnas y que ésto se
debe especificar mediante marcas, para cada tabla. No se usa en general un borde alrededor de toda la tabla. Queda a
cargo del procesador hacerlo, por lo que las marcas no deben incluir el borde exterior.
Las variaciones de los entornos de tabla basados en longtable reciben un formato con espacio extra antes y después,
por lo que sólo deben usarse en tablas tan largas que sea razonable dividirlas en páginas. Se repite la cabecera en cada
parte de la tabla.
\begin{tableii}{colspec}{col1font}{encabezado1}{encabezado2}
\end{tableii}
Crear una tabla de dos columnas mediante el parámetro LATEX colspec. El parámetro de especificación de co-
lumnas debería indicar barras verticales entre columnas, pero no en el exterior de la tabla (se deja para las hojas
de estilo). El parámetro col1font se usa como tratamiento estilístico de la primera columna de la tabla. La pri-
mera columna se presenta como \col1font{column1}. Para evitar que la primera columna reciba tratamiento
especial, col1font puede ser ‘textrm’. Los encabezados de columna se toman de los valores encabezado1 y
encabezado2.

10 5 Marcaje especial
\begin{longtableii}C
\end{longtableii}
omo tableii, pero produce una tabla que se puede dividir en varias páginas. Los parámetros coinciden con
los de tableii.
\lineaii{columna1}{columna2}
Crear una tabla de una fila con un entorno tableii o longtableii. El texto de la primera columna se
generará aplicando la macro indicada por el valor col1font cuando se abriera eltableii.
\begin{tableiii}{colspec}{col1font}{encabezado1}{encabezado2}{encabezado3}
\end{tableiii}
Como el entorno tableii, pero con una tercera columna. El encabezado de la tercera columna es encabeza-
do3.
\begin{longtableiii}C
\end{longtableiii}
omo tableiii, pero produce una tabla que se puede dividir en varias páginas. Los parámetros coinciden con
los de tableiii.
\lineaiii{columna1}{columna2}{columna3}
Como la macro \lineii, pero con una tercera columna. El texto de la tercera columna es columna3.
\begin{tableiv}{colspec}{col1font}{encabezado1}{encabezado2}{encabezado3}{encabezado4}
\end{tableiv}
Como el entorno tableiii, pero con una cuarta columna. El encabezado de la cuarta columna es encabeza-
do4.
\begin{longtableiv}C
\end{longtableiv}
omo tableiv, pero produce una tabla que se puede dividir en varias páginas. Los parámetros coinciden con
los de tableiv.
\lineiv{columna1}{columna2}{columna3}{columna4}
Como la macro \lineiii, pero con una cuarta columna. El texto de la cuarta columna es columna4.
Hay un entorno tabular, synopsistable. La tabla generada por este entorno contiene dos columnas y cada fila se
define por una defininción alternativa de \modulesynopsis. Normalmente, este entorno no se utiliza directamente,
sino que lo crea la macro \localmoduletable.

5.9 Referencia de marcas de listas

Muchas secciones incluyen una lista de referencias a documentación de módulos o a documentos externos. Estas listas
se crean mediante el entorno seealso. Este entorno define varias macros más para permitir crear referencias de
manera razonable.
El entorno seealso se coloca típicamente en una sección inmediatamente anterior a las subsecciones. Se hace así
para asegurar que los enlaces que hagan referencia a esa sección no quedan ocultos en una subsección en la salida en
formato hipertexto de la documentación.
\begin{seealso}
\end{seealso}
Este entorno genera un encabezado “Consultar también:” y define las marcas utilizadas para describir referencias
individuales.
En las macros a continuación, why debe ser una frase completa o más, con la primera letra mayúscula (salvo que
empiece por un identificador, que no debería modificarse) y acabada en punto (o lo que corresponda).
Estas macros sólo están definidas dentro del contexto del entorno seealso.
\seemodule[key]{nombre}{why}

5.9 Referencia de marcas de listas 11

 Referencia a otro módulo. why es una breve explicación del interés de la referencia. El nombre del módulo
viene dado por name, con la clave del enlace, si ha lugar, en key. En las conversiones a HTML y PDF, el nombre
del módulo será un hipervínculo al módulo aludido. Nota: El módulo debe estar documentado en el mismo
documento (es necesario el \declaremodule correspondiente).
\seepep{número}{título}{why}
Referencia a una Propuesta de mejora de Python (PEP). número debe ser el número oficial otorgado por el editor
del PEP, título es el título legible de la PEP, tal como se encuentra en el original del documento. why es una breve
explicación del interés de la referencia. Se debe usar para referir al lector a PEPs que especifican interfaces o
características del lenguaje relevantes.
\seerfc{number}{title}{why}
Referencia a una RFC del IETF. Análogo a \seepep. Se usa para dirigir al lector a RFCs que especifican
protocolos o formatos de datos relevantes.
\seetext{texto}
Añade un texto arbitrario a la lista “Consultar también:”. Se puede usar para hacer referencia a materiales no
electrónicos (o electrónicos mediante la macro \url. Debe contener una o más frases completas.
\seetitle[url]{título}{why}
Hace referencia a un documento externo denominado título. Si se indica url, el título será un hipervínculo en la
versión en HTML del documento y se mostrará bajo el título en las versiones en papel.
\seeurl{url}{why}
Las referencias a recursos electrónicos específicos deben hacerse mediante la macro \seeurl. No se saocia un
título a la referencia, pero el texto why puede incluir un título marcado con la macro \citetitle.

5.10 Marcas para la generación de índices

La generación eficaz de índices para documentos técnicos puede resultar dificultosa, especialmente para los duchos en
la materia técnica pero no en la creación de índices. Gran parte de la dificultad radica en la terminología: no basta con
incluir los términos propios de expertos. Resulta bastante difícil encontrar los términos que van a buscar los novatos
para un autor que, típicamente, es un experto en la materia sobre la que escribe.
La verdadera dificultad de la generación de índices no es algo en lo que las herramientas de documentación puedan
ayudar. Sin embargo, facilitan la producción del índice una vez tomadas las decisiones sobre el contenido es tarea
de estas herramientas. Se proporcionan marcas que el software de proceso es capaz de reconocer para generar di-
versos índices con el mínimo esfuerzo. Además, muchos de los entornos descritos en la sección 5.3, “Unidades de
información”, generan elementos correspondientes en el índice general y en el de módulos.
Se puede usar la siguiente macro en le preámbulo del documento para controlar la generación de datos de índice:
\makemodindex
Debe usarse en el preámbulo del documento si se desea obtener un “Indice de módulos” que contenga material
de referencia de muchos módulos. Provoca la generación de un fichero de datos libjobname.idx a partir de
las macros \declaremodule macros. El programa makeindex puede procesar este fichero para generar un
fichero del que hacer \input desde el documento en la situación final del índice de módulos.
Existen varias macros útiles para añadir elementos de índice para conceptos particulares, muchos de los cuales son
específicos de los lenguajes de programación y hasta exclusivos de Python.
\bifuncindex{nombre}
Añade un elemento de índice que se refiere a una función interna denominada nombre. No se deben incluir los
paréntesis tras nombre.
\exindex{excepción}
Añade una referencia a una excepción denominada excepción.
\kwindex{palabra}

12 5 Marcaje especial
 Añade una referencia a una palabra reservada del lenguaje (no a un parámetro de tipo clave de una llamada a
función o método).
\obindex{tipo de objeto}
Añade un elemento de índice para un tipo de objeto interno.
\opindex{operador}
Añade una referencia a un operador, como ‘+’.
\refmodindex[clave]{módulo}
Añade un elemento de índice para el módulo módulo; si módulo contiene un carácter de subrayado, debe propor-
cionarse el parámetro opcional clave, con un valor igual a módulo, sin los caracteres de subrayado. Se generará
un elemento de índice “módulo (módulo)”. Esta marca está orientada a su uso con módulos no estándar imple-
mentados en Python.
\refexmodindex[clave]{módulo}
Como \refmodindex, pero el elemento de índice será “módulo (módulo de extensión)”. Esta marca está
orientada a su uso con módulos no estándar no implementados en Python.
\refbimodindex[clave]{módulo}
Como \refmodindex, pero el elemento de índice será “módulo (módulo interno)”. Esta marca está orientada
a su uso con módulos estándar no implementados en Python.
\refstmodindex[key]{module}
Como \refmodindex, pero el elemento del índice será “module (módulo estándar)”. Esta orientado a su uso
con módulos estándar implementados en Python.
\stindex{statement}
Añade una entrada de índice para un tipo de sentencia, tal como print o try/finally.
XXX Need better examples of difference from \kwindex.
Se proporcionan más macros útiles para crear fácilmente elementos de índice que aparecerás en muchos lugares del
índice rotando una lista de palabras. Éstas son macros imples que usan \index para construir elementos de índice.
Los elementos de índice construidos mediante estas macros contienen texto principal y secundario.
\indexii{word1}{word2}
Build two index entries. This is exactly equivalent to using \index{word1!word2} and \in-
dex{word2!word1}.
\indexiii{word1}{word2}{word3}
Build three index entries. This is exactly equivalent to using \index{word1!word2 word3}, \in-
dex{word2!word3, word1}, and \index{word3!word1 word2}.
\indexiv{word1}{word2}{word3}{word4}
Build four index entries. This is exactly equivalent to using \index{word1!word2 word3 word4},
\index{word2!word3 word4, word1}, \index{word3!word4, word1 word2}, and \in-
dex{word4!word1 word2 word3}.

6 Nombres especiales
Se usan mucho nombres especiales en la documentación de Python, incluyendo nombres de sistemas operativos,
lenguajes de programación, organismos reguladores, etc. Muchos de ellos tienen asignados macros de LATEX desde
hace mucho, aunque no sean muy útiles hoy en día. En la notación actual no se asignan marcas especiales, pero
incluimos aquí un glosario de nombres comunes, para ayudar a ls autores a mantener la consistencia en la presentación
de la documentación de Python.

POSIX El nombre asignado a cierto grupo de estándares. Siempre en mayúsculas.

13
Python El nombre de nuestro lenguaje de programación favorito siempre va con mayúscula.
Unicode El nombre de un juego de caracteres y una codificación de comparaciones. Va siempre en mayúscula.

7 Herramientas de proceso

7.1 Herramientas externas

Se necesitan muchas herramientas para procesar la documentación de Python si se desea obtener todos los formatos
soportados. Esta sección enumera las herramientas utilizadas e indica cuándo hace falta cada una de ellas. Consulta el
fichero ‘Doc/README’ para ver si hay requisitos de versión para cualquiera de ellas.

dvips Este programa suele ser parte de las instalaciones de TEX. Se usa para generar PostScript a partir de los ficheros
“independentes del dispositivo” ‘.dvi’. Es necesario para la conversión a PostScript.
emacs Emacs es el no va más de los editores para programadores. Viene con algo de soporte las estructuras de menú
de los documentos de Texinfo si se desea una conversión a info. Es necesario para la converisón a info. Usar
xemacs en lugar de la versión de FSF emacs puede dar lugar a inestabilidad en la conversión, pero eso se debe
a que nadie parece mantener el código Texinfo de Emacs de manera portable.
latex Éste es un formateador de texto impreso conocido a nivel mundial, escrito por de Donald Knuth. Se usa para la
conversión a PostScript y es necesario para la conversión a HTML (LATEX2HTML necesita uno de los ficheros
intermedios que crea).
latex2html Posiblemente, el guion Perl más largo que alguien haya intentado mantener. Convierte documentos LATEX
a HTML y lo hace bastante bien. Es necesario para las conversiones a HTML y GNU Info.
lynx Un programa de navegación de la Web en modo texto que incluye un conversión de HTML a texto plano. Se usa
para convertir los documentos howto a texto.
make Cualquier versión debería valer para los documentos estándar, pero es necesario el make de GNU para los
procesos experimentales de ‘Doc/tools/sgmlconv/’, al menos mientras sean experimentales.
makeindex Es un programa estándar para convertir datos de índice de LATEX en un índice con formato. Debría estar
incluido en todas las instalaciones de LATEX. Es necesario para las conversiones a PDF y PostScript.
makeinfo Se usa makeinfo de GNU para convertir documentos de Texinfo a ficheros info de GNU. Como se usa
Texinfo como formato intermedio en la conversión a info, se necesita este programa en dicha conversión.
pdflatex pdfTEX es una variante relativamente nueva de TEX. Se usa para generar la versión en PDF de los manuales.
Se instala típicamente como parte de la mayoría de las distribuciones de TEX. pdflatex es pdfTEX con el formato
LATEX.
perl Es necesario Perl para LATEX2HTML y uno de los guiones utilizado para post-procesar la salida de LATEX2HTML.
También se utiliza en la conversión HTML a Texinfo. Es necesario para las conversiones a HTML y a info de
GNU.
python Python se usa para muchos de los guiones del directorio ‘Doc/tools/’. Es necesario en todas las conversiones.
¡No debería suponer un problema1 si estás interesado en escribir documentación para Python!
1 N. del T.: Es necesario utilizar la versión de Python 2.0 para generar la documentación de Python 2.0.

14 7 Herramientas de proceso
7.2 Herramientas internas

Esta sección describe los diversos guiones utilizados para implementar las etapas de procesado de documentos o para
gestionar la secuencia de generación completa. La mayoría de estas herrramientas sólo son útiles en el contexto de la
generación de la documentación estándar, aunque algunas son más generales.

mkhowto El guion principal utilizado para dar formato a documentos de terceros. Contiene toda la lógica necesaria
para “obtener resultados”. El modo correcto de usar este guion es hacer un enlace simbólico2 o ejecutarlo en el
propio lugar. El guion real debe almacenarse como parte del árbol de las fuentes de la documentación, aunque
se puede usar para dar formato a documentos que no se hallen en él. Ejecuta mkhowto --help para obtener una
lista de las opciones de la línea de órdenes.
mkhowto puede usarse tanto para documentos de la clase howto como para documentos manual (en el
segundo caso, asegúrate de obtener la última versión del repositorio CVS de python, en lugar de la versión
distribuida con el archivo de fuentes ‘latex-1.5.2.tgz’).

8 Tendencias de futuro
La historia de la documentación de Python esta plagada de cambios, la mayoría de los cuales han sido pequeños y evo-
lutivos, Ha habido grandes discusiones acerca de realizar grandes cambios a los lenguajes de marcado y herramientas
usados para procesar la documentación. Esta sección habla de la naturaleza de dichos cambios y de lo que parece ser
la dirección más probable que tomará el desarrollo futuro.

8.1 Documentación estructurada

La mayoría de los pequeños cambios a las marcas de LATEX han sido con vistas a separar las marcas de la presentación,
haciendo que las dos sean algo más fáciles de mantener. En el curso de 1998, se hicieron muchos cambios con este
objetivo. Antes, los cambios se hacían de manera menos sistemática, preocupándose más de no tener que cambiar el
contenido existente. El resultado es un lenguaje de marcas muy estructurado y semántico implementado en LATEX. Sin
apenas marcas originales de TEX ni LATEX, la sintaxis de las marcas es la única evidencia que queda en las fuentes de
la documentación.
Un efecto secundario es que, aunque hemos sido capaces de usar “motores” estándar, tales como LATEX and
LATEX2HTML, para manipular los documentos, la mayoría de las transformaciones reales se han creado específica-
mente para Python. Las clases de documentos LATEX y el soporte de LATEX2HTML son implementaciones completas
del marcaje específico diseñado para estos documentos.
Combinar marcas muy personalizadas con los sistemas algo esotéricos utilizados para procesar los documentos no
lleva a preguntarnos varias cosas: ¿Podemos hacerlo más fácil? ¿mejor? Tras largas discusiones con la comunidad,
hemos determinado que merece la pena buscar activamente sistemas modernos de documentación estructurada.
Parece haber dos candidatos serios en este campo: El SGML (Lenguaje de marcas general estándar) y el XML (Len-
guaje de marcas extensible). Los dos estándares cuentan con ventajas y desventajas, siendo comunes muchas de las
ventajas.
SGML ofrece ventajas que son más atractivas a los autores, especialmente los que usan editores de texto corrientes.
Hay también más posibilidades para definir modelos de contenido. Existen varias herramientas de elevada calidad y
madurez demostrable, pero la mayoría no son libres/gratuitas. Las que sí lo son presentas problemas de portabilidad.
Las ventajas de XML inluyen un gran número de herramientas en evolución. Sin embargo, muchos de los estándares
asociados están en evolución todavía, por lo que las herramientas persiguen un blanco móvil. Esto supone que el
desarrollo de un juego de herramientas robustas que utilice algo más avanzado que la recomendación XML 1.0 no es
2 N. del T. El término “enlace simbólico” se usa en U NIX, el equivalente en Windows es, vagamente, el acesso directo.

7.2 Herramientas internas 15

posible a corto plazo. La promesa de disponibilidad de una panoplia de herramientas de alta calidad que den soporte a
los estándares más importantes no es inmediata. Es probable que muchas de las herramientas sean libres.
XXX Eventual migration to SGML/XML.

8.2 Foros de discusión

Las discusiones relativas al futuro de la documentación de Python tienen lugar en el Grupo de interés especial de docu-
mentación, o “Doc-SIG”. Hay información sobre el grupo, incluyendo los archivos de la lista de correo e información
sobre subscripciones en http://www.python.org/sigs/doc-sig/. El Doc-SIG está abierto a cualquiera que tenga interés en
él.
Los comentarios e informes de error sobre la documentación estándar deben enviarse a python-docs@python.org3 .
Puede comentarse el formato, el contenido, los errores gramáticos u ortográficos, o este mismo documento. También
es posible enviar comentarios a este documento directamente al autor, a fdrake@acm.org.

3 Los específicos de la versión en castellano deben enviarse a rapto@arrakis.es, dirección del coordinador, si no hay información más

específica en el documento concreto.

16 8 Tendencias de futuro