perlpodspec - Online en la nube

PROGRAMA:

NOMBRE

perlpodspec - Documentación antigua simple: especificación de formato y notas

DESCRIPCIÓN

Este documento contiene notas detalladas sobre el lenguaje de marcado Pod. La mayoría de la gente solo tendrá que
lea perlpod para saber cómo escribir en Pod, pero este documento puede responder a algunos
preguntas relacionadas con el análisis y la representación de Pod.

En este documento, "debe" / "no debe", "debería" / "no debería" y "puede" tener su
significados convencionales (cf. RFC 2119): "X debe hacer Y" significa que si X no hace Y, es
en contra de esta especificación, y realmente debería corregirse. "X debería hacer Y" significa que es
recomendado, pero X puede fallar en hacer Y, si hay una buena razón. "X puede hacer Y" es simplemente un
tenga en cuenta que X puede hacer Y a voluntad (aunque depende del lector detectar cualquier connotación de
"y creo que sería agradable si X hiciera Y "versus" realmente no molestia yo si X lo hizo
Y ").

En particular, cuando digo "el analizador debe hacer Y", el analizador puede fallar al hacer Y, si la llamada
la aplicación solicita explícitamente que el analizador No hacer Y. A menudo digo esto como "el
analizador debería, por defecto, hacer Y. "Esto no exigir el analizador para proporcionar una opción
para desactivar cualquier característica que sea Y (como expandir pestañas en párrafos textuales),
aunque implica que tal opción pueden ser proporcionado.

Vaina Definiciones

El pod está incrustado en archivos, generalmente archivos fuente de Perl, aunque puede escribir un archivo
eso no es nada más que Pod.

A línea en un archivo consta de cero o más caracteres que no son de nueva línea, terminados por un
nueva línea o al final del archivo.

A nueva línea secuencia suele ser un concepto que depende de la plataforma, pero los analizadores de pods deben
entender que significa cualquiera de CR (ASCII 13), LF (ASCII 10) o un CRLF (ASCII 13 seguido
inmediatamente por ASCII 10), además de cualquier otro significado específico del sistema. La primera
La secuencia CR / CRLF / LF en el archivo se puede utilizar como base para identificar la nueva línea
secuencia para analizar el resto del archivo.

A en blanco línea es una línea que consta completamente de cero o más espacios (ASCII 32) o tabulaciones
(ASCII 9) y terminado con una nueva línea o final de archivo. A no en blanco línea es una linea
que contiene uno o más caracteres distintos del espacio o tabulación (y terminados por una nueva línea o
fin del documento).

(Nota: Muchos analizadores de pod más antiguos no aceptaban una línea que constara de espacios / pestañas y luego una
nueva línea como una línea en blanco. Las únicas líneas que consideraban en blanco eran las que constaban de no
personajes at que todas, terminado por una nueva línea.)

Espacio en blanco se utiliza en este documento como un término general para espacios, pestañas y nueva línea
secuencias. (Por sí mismo, este término suele hacer referencia a un espacio en blanco literal. Es decir,
secuencias de caracteres de espacio en blanco en la fuente del Pod, a diferencia de "E <32>", que es un
código de formato que denota un carácter de espacio en blanco.)

A Vaina analizador es un módulo diseñado para analizar Pod (independientemente de si esto implica
llamar devoluciones de llamada o construir un árbol de análisis o formatearlo directamente). A Vaina formateador
(o Vaina traductor) es un módulo o programa que convierte Pod a algún otro formato (HTML,
texto sin formato, TeX, PostScript, RTF). A Vaina procesador puede ser un formateador o traductor, o
podría ser un programa que hace algo más con el Pod (como contar palabras, escanear
para puntos de índice, etc.).

El contenido del pod está incluido en Vaina bloques. Un bloque de Pod comienza con una línea que coincide
"m / \ A = [a-zA-Z] /", y continúa hasta la siguiente línea que coincide con "m / \ A = cut /" o hasta el
final del archivo si no hay línea "m / \ A = cut /".

Dentro de un bloque de Pod, hay Vaina párrafos. Un párrafo de Pod consta de líneas que no están en blanco
de texto, separados por una o más líneas en blanco.

Para el procesamiento de Pod, hay cuatro tipos de párrafos en un bloque de Pod:

· Un párrafo de comando (también llamado "directiva"). La primera línea de este párrafo
debe coincidir con "m / \ A = [a-zA-Z] /". Los párrafos de comando suelen tener una línea, como en:

= head1 NOTAS

= artículo *

Pero pueden abarcar varias líneas (no en blanco):

= para comentario
Hm, me pregunto cómo se vería si
intentaste escribir un BNF para Pod a partir de esto.

= head3 Dr. Strangelove, o: Cómo aprendí a
Deja de preocuparte y ama la bomba

Cosas Los párrafos de comando permiten formatear códigos en su contenido (es decir, después de la parte
que coincide con "m / \ A = [a-zA-Z] \ S * \ s * /"), como en:

= head1 ¿Se acordó de C ?

En otras palabras, el controlador de procesamiento de pod para "head1" aplicará el mismo procesamiento
a "¿Te acuerdas de C ? "que lo haría con un párrafo ordinario (es decir,
códigos de formato como "C <...>") se analizan y presumiblemente se formatean de forma adecuada, y
los espacios en blanco en forma de espacios literales y / o tabulaciones no son significativos.

· UNA literal párrafo. La primera línea de este párrafo debe ser un espacio literal o
pestaña, y este párrafo no debe estar dentro de "= begin identificador", ..." = fin
identificador"secuencia a menos que"identificador"comienza con dos puntos (": "). Es decir, si un
párrafo comienza con un espacio literal o tabulación, pero is dentro de un "= comenzar identificador", ...
"= fin identificador"región, entonces es un párrafo de datos, a menos que"identificador" empieza con
dos puntos.

Espacio en blanco is significativo en los párrafos textuales (aunque, en el procesamiento, las tabulaciones son
probablemente expandido).

· Un ordinario párrafo. Un párrafo es un párrafo ordinario si su primera línea coincide
ni "m / \ A = [a-zA-Z] /" ni "m / \ A [\ t] /", y si no está dentro de un "= comenzar
identificador", ..." = fin identificador"secuencia a menos que"identificador"comienza con dos puntos
(":").

· UNA datos párrafo. Este es un párrafo que is dentro de un "= comenzar identificador"..." = fin
identificador"secuencia donde"identificador" lo hace No comience con dos puntos literales (":"). En
En cierto sentido, un párrafo de datos no es parte de Pod en absoluto (es decir, efectivamente está "fuera de
of-band "), ya que no está sujeto a la mayoría de los tipos de análisis de Pod; pero se especifica
aquí, dado que los analizadores de pod deben poder llamar a un evento o almacenarlo en algún
formar en un árbol de análisis sintáctico, o al menos simplemente analizar en torno a él.

Por ejemplo: considere los siguientes párrafos:

# <- esa es la columna 0

= cabeza1 Foo

Cosas

$ foo-> bar

= cortar

Aquí, "= head1 Foo" y "= cut" son párrafos de comando porque la primera línea de cada
coincide con "m / \ A = [a-zA-Z] /". "[espacio] [espacio]$ foo-> bar "es un párrafo literal, porque su
la primera línea comienza con un carácter de espacio en blanco literal (y no hay "= begin" ... "= end"
región alrededor).

El "= comenzar identificador"..." = fin identificador"Los comandos detienen los párrafos que rodean
de ser analizado como párrafos ordinarios o textuales, si identificador no comienza con un
colon. Esto se analiza en detalle en la sección "Acerca de los párrafos de datos y
"= comenzar / = finalizar" Regiones ".

Vaina Comandos

Esta sección está destinada a complementar y aclarar la discusión en "Párrafo de comando"
en perlpod. Estos son los comandos de Pod actualmente reconocidos:

"= cabecera1", "= cabecera2", "= cabecera3", "= cabecera4"
Este comando indica que el texto del resto del párrafo es un encabezado.
Ese texto puede contener códigos de formato. Ejemplos:

= Atributos del objeto head1

= cabeza3 ¿Qué B ¡hacer!

"= vaina"
Este comando indica que este párrafo comienza un bloque de Pod. (Si ya estamos en
en el medio de un bloque de Pod, este comando no tiene ningún efecto).
en este párrafo de comando después de "= pod", debe ignorarse. Ejemplos:

= vaina

Este es un párrafo simple de Pod.

= pod Este texto se ignora.

"= cortar"
Este comando indica que esta línea es el final de este bloque de Pod iniciado previamente.
Si hay algún texto después de "= cortar" en la línea, debe ignorarse. Ejemplos:

= cortar

= cortar La documentación termina aquí.

= cortar
# Esta es la primera línea del texto del programa.
sub foo {# Este es el segundo.

Es un error intentar comienzo un bloque Pod con un comando "= cortar". En ese caso, el
El procesador de pod debe detener el análisis del archivo de entrada y debe emitir una advertencia de forma predeterminada.

"= más"
Este comando indica que este es el comienzo de una región de lista / sangría. Si hay
cualquier texto que siga a "= over", debe constar únicamente de un número positivo distinto de cero.
La semántica de este numeral se explica en "Acerca de = más ... = Regiones atrás"
sección, más abajo. Los códigos de formato no se expanden. Ejemplos:

= más de 3

= más de 3.5

= terminado

"= artículo"
Este comando indica que un elemento de una lista comienza aquí. Los códigos de formato son
procesada. La semántica del texto (opcional) en el resto de este párrafo
se explican en la sección "Acerca de = más ... = atrás Regiones", más abajo. Ejemplos:

= artículo

= artículo *

= artículo *

= artículo 14

= artículo 3.

= elemento C << $ cosa-> cosas (I ) >>

= artículo Para transportarnos más allá de los mares para ser probado por pretendido
delitos

= artículo En este momento está transportando grandes ejércitos de extranjeros
mercenarios para completar las obras de muerte, desolación y
tiranía, ya comenzada con circunstancias de crueldad y perfidia
apenas paralelo en las épocas más bárbaras, y totalmente
indigno de la cabeza de una nación civilizada.

"= atrás"
Este comando indica que este es el final de la región iniciada por el más reciente
comando "= over". No permite texto después del comando "= back".

"= comenzar nombre de formato"
"= comenzar parámetro de nombre de formato"
Esto marca los siguientes párrafos (hasta que coincida "= end formatname") como siendo
para algún tipo especial de procesamiento. A menos que "formatname" comience con dos puntos, el
los párrafos que no son de comando son párrafos de datos. Pero si "nombredeformato" sí begin
con dos puntos, los párrafos que no son de comando son párrafos ordinarios o párrafos de datos.
Esto se analiza en detalle en la sección "Acerca de los párrafos de datos y" = comienzo / = final ".
Regiones".

Se recomienda que los nombres de formato coincidan con la expresión regular "m / \ A:? [- a-zA-Z0-9 _] + \ z /". Todo
siguiente espacio en blanco después del nombre de formato es un parámetro que puede ser utilizado por el
formateador cuando se trata de esta región. Este parámetro no debe repetirse en el
párrafo "= fin". Los implementadores deben anticipar la expansión futura en la semántica
y la sintaxis del primer parámetro para "= comenzar" / "= final" / "= para".

"= nombre de formato final"
Esto marca el final de la región abierta por la región correspondiente "= begin formatname".
Si "nombredeformato" no es el nombre de formato de la apertura más reciente "= comenzar nombredeformato"
región, entonces esto es un error y debe generar un mensaje de error. Esto se discute
en detalle en la sección "Acerca de los párrafos de datos y" = inicio / = final "Regiones".

"= para el texto del nombre de formato ..."
Esto es sinónimo de:

= comenzar nombre de formato

texto...

= fin nombre de formato

Es decir, crea una región que consta de un solo párrafo; ese párrafo debe ser
se trata como un párrafo normal si "formatname" comienza con ":"; si "nombredeformato"
no se comience con dos puntos, luego "texto ..." constituirá un párrafo de datos. Hay
no hay forma de usar "= para el nombre de formato texto ..." para expresar "texto ..." como un párrafo literal.

"= codificación nombre de codificación"
Este comando, que debe aparecer al principio del documento (al menos antes de cualquier
Datos ASCII!), Declara que este documento está codificado en la codificación nombre de codificación,
que debe ser un nombre de codificación que Encode reconozca. (Lista de codificación de
codificaciones, en Encode :: Supported, es útil aquí.) Si el analizador de Pod no puede decodificar el
codificación declarada, debería emitir una advertencia y puede abortar el análisis del documento
.

Un documento que tenga más de una línea "= codificación" debe considerarse un error. Vaina
Los procesadores pueden tolerar esto silenciosamente si las líneas no-primero "= codificación" son solo
duplicados del primero (p. ej., si hay una línea "= codificación utf8" y más adelante
otra línea "= codificación utf8"). Pero los procesadores de pod deberían quejarse si hay
líneas "= codificación" contradictorias en el mismo documento (p. ej., si hay una "= codificación
utf8 "al principio del documento y" = codificación de big5 "más tarde). Procesadores de pod que
reconocer las listas de materiales también pueden quejarse si ven una línea "= codificación" que contradice la
Lista de materiales (p. Ej., Si un documento con una lista de materiales UTF-16LE tiene una línea "= encoding shiftjis").

Si un procesador de pod ve cualquier comando que no sea los enumerados anteriormente (como "= head", o
"= haed1", o "= cosas", o "= sepia", o "= w123"), ese procesador debe tratar de forma predeterminada
esto como un error. No debe procesar el párrafo que comienza con ese comando, debe
por defecto advierte de esto como un error y puede abortar el análisis. Un analizador de pod puede permitir una forma
para aplicaciones particulares para agregar a la lista anterior de comandos conocidos, y para estipular,
para cada comando adicional, si se deben procesar los códigos de formato.

Las versiones futuras de esta especificación pueden agregar comandos adicionales.

Vaina Maquetación Códigos

(Tenga en cuenta que en borradores anteriores de este documento y de perlpod, los códigos de formato
denominadas "secuencias interiores", y este término todavía se puede encontrar en la documentación
para los analizadores de Pod y en los mensajes de error de los procesadores de Pod).

Hay dos sintaxis para formatear códigos:

· Un código de formato comienza con una letra mayúscula (solo US-ASCII [AZ]) seguida de una
"<", cualquier número de caracteres y terminando con el primer ">" coincidente. Ejemplos:

Eso es lo que yo ¡pensar!

¿Qué es C ¿por?

X y C Bajo diferentes sistemas operativos>

· Un código de formato comienza con una letra mayúscula (solo US-ASCII [AZ]) seguida de dos
o más "<", uno o más espacios en blanco, cualquier número de caracteres, uno o más
más caracteres de espacio en blanco y termina con la primera secuencia coincidente de dos o más
">", donde el número de ">" es igual al número de "<" en la apertura de este
código de formato. Ejemplos:

¡Eso es lo que yo << tú >> piensas!

C <<< open (X, ">> cosa.dat") || muere $! >>>

B << $ foo-> bar (); >>

Con esta sintaxis, los caracteres de espacio en blanco después de "C <<<" y antes de ">>>"
(o cualquier letra) son No renderizable. No significan espacios en blanco, son simplemente
parte de los propios códigos de formato. Es decir, todos estos son sinónimos:

C
C << cosa >>
C << cosa >>
C <<< cosa >>>
C <<<
cosa
>>>>

y así sucesivamente.

Finalmente, la forma de corchetes de ángulos múltiples no No alterar la interpretación de anidado
códigos de formato, lo que significa que las siguientes cuatro líneas de ejemplo son idénticas en
significado:

B = E $ b >>

B $ b >>>

B = E $ b >>>

B <<< ejemplo: C << $ a E = E $ b >> >>>

Al analizar Pod, una parte notablemente complicada es el análisis correcto de (¡potencialmente anidado!)
códigos de formato. Los implementadores deben consultar el código en la rutina "parse_text" en
Pod :: Parser como ejemplo de una implementación correcta.

"I "- texto en cursiva
Vea la breve discusión en "Formateo de códigos" en perlpod.

"B " -- texto en negrita
Vea la breve discusión en "Formateo de códigos" en perlpod.

"C " -- code text
Vea la breve discusión en "Formateo de códigos" en perlpod.

"F "- estilo para nombres de archivo
Vea la breve discusión en "Formateo de códigos" en perlpod.

"X "- una entrada de índice
Vea la breve discusión en "Formateo de códigos" en perlpod.

Este código es inusual en el sentido de que la mayoría de los formateadores descartan completamente este código y su
contenido. Otros formateadores lo renderizarán con códigos invisibles que se pueden usar en
construyendo un índice del documento actual.

"Z <>": un código de formato nulo (efecto cero)
Discutido brevemente en "Códigos de formato" en perlpod.

Este código es inusual, es que no debería tener contenido. Es decir, un procesador puede
quejarse si ve "Z ". Se queje o no, el patatas texto
debe ignorarse.

"L "- un hipervínculo
Las complicadas sintaxis de este código se analizan en profundidad en "Códigos de formato" en
perlpod, y los detalles de implementación se analizan a continuación, en "Acerca de los códigos L <...>".
Analizar el contenido de L es complicado. En particular, el contenido debe ser verificado.
para saber si parece una URL o si debe dividirse en literal "|" y / o
"/" (¡en el orden correcto!), etc. antes Se resuelven los códigos E <...>.

"MI "- un personaje de escape
Consulte "Códigos de formato" en perlpod y varios puntos en "Notas sobre la implementación de Pod
Procesadores ".

"S ": el texto contiene espacios que no se separan
Este código de formato es sintácticamente simple, pero semánticamente complejo. Lo que significa
es que cada espacio en el contenido imprimible de este código significa un
espacio.

Considerar:

C <$ x? $ y: $ z>

S >

Ambos significan el texto monoespaciado (estilo c [oda]) que consta de "$ x", un espacio, "?", Uno
espacio, ":", un espacio, "$ z". La diferencia es que en este último, con el código S,
esos espacios no son espacios "normales", sino que son espacios que no se separan.

Si un procesador de Pod ve cualquier código de formato que no sean los enumerados anteriormente (como en
"N <...>", o "Q <...>", etc.), ese procesador debe, por defecto, tratar esto como un error. A
El analizador de pod puede permitir una forma de que aplicaciones particulares se agreguen a la lista anterior de conocidos
códigos de formato; un analizador de pod incluso podría permitir una forma de estipular, para cada adicional
comando, si requiere alguna forma de procesamiento especial, como lo hace L <...>.

Las versiones futuras de esta especificación pueden agregar códigos de formato adicionales.

Nota histórica: algunos procesadores de pod más antiguos no verían un ">" como cierre de un código "C <",
si el ">" fue precedido inmediatamente por un "-". Esto fue para que esto:

C <$ foo-> bar>

analizaría como equivalente a esto:

C <$ foo-E bar>

en lugar de como equivalente a un código de formato "C" que contiene solo "$ foo-", y luego un
"barra>" fuera del código de formato "C". Este problema ha sido resuelto desde entonces por
adición de sintaxis como esta:

C << $ foo-> bar >>

Los analizadores compatibles no deben tratar "->" como especial.

Los códigos de formato no pueden abarcar párrafos en absoluto. Si un código se abre en un párrafo,
y no se encuentra ningún código de cierre al final de ese párrafo, el analizador de Pod debe cerrar ese
código de formato, y debería quejarse (como en "Código I sin terminar en el párrafo que comienza
en la línea 123: 'Los objetos de tiempo no son ...' "). Así que estos dos párrafos:

I

¡No me hagas volver a decirlo!>

...deber No ser analizado como dos párrafos en cursiva (con el código I comenzando en uno
párrafo y comenzando en otro.) En cambio, el primer párrafo debe generar un
advertencia, pero aparte de eso, el código anterior debe analizarse como si fuera:

I

¡No me hagas volver a decirlo!

(En la jerga de SGMLish, todos los comandos de Pod son como elementos a nivel de bloque, mientras que todos los de Pod
los códigos de formato son como elementos de nivel en línea).

Notas on Poner en marcha Vaina TÉRMICO

La siguiente es una sección larga de requisitos diversos y sugerencias relacionadas con
Procesamiento de vainas.

· Los formateadores de pod deben tolerar líneas en bloques textuales que sean de cualquier longitud, incluso
si eso significa tener que romperlos (posiblemente varias veces, para filas muy largas) para
Evite que el texto se salga del lateral de la página. Los formateadores de pod pueden advertir sobre tales
rotura. Tales advertencias son particularmente apropiadas para líneas con más de 100
caracteres de largo, que generalmente no son intencionales.

· Los analizadores de pod deben reconocer que todas de los tres conocidos formatos de nueva línea: CR, LF y
CRLF. Ver perlport.

· Los analizadores de pod deben aceptar líneas de entrada de cualquier longitud.

· Dado que Perl reconoce una marca de orden de bytes Unicode al comienzo de los archivos como señalización
que el archivo está codificado en Unicode como en UTF-16 (ya sea big-endian o little-endian) o
UTF-8, los analizadores de pod deberían hacer lo mismo. De lo contrario, la codificación de caracteres debe ser
entendido como UTF-8 si la primera secuencia de bytes de alto bit en el archivo parece válida
como secuencia UTF-8, o como CP-1252 (versiones anteriores de esta especificación
usó Latin-1 en lugar de CP-1252).

Las versiones futuras de esta especificación pueden especificar cómo Pod puede aceptar otras codificaciones.
Presumiblemente, el tratamiento de otras codificaciones en el análisis de Pod sería como en el análisis de XML:
Cualquiera que sea la codificación declarada por un archivo Pod en particular, el contenido se almacenará en
memoria como caracteres Unicode.

· Las marcas de orden de bytes Unicode más conocidas son las siguientes: si el archivo comienza con el
dos valores de bytes literales 0xFE 0xFF, esta es la lista de materiales para big-endian UTF-16. Si el archivo
comienza con el valor de dos bytes literales 0xFF 0xFE, esta es la lista de materiales para little-endian
UTF-16. En una plataforma ASCII, si el archivo comienza con los tres valores de bytes literales
0xEF 0xBB 0xBF, esta es la lista de materiales para UTF-8. Un mecanismo portátil para plataformas EBCDIC
es:

my $ utf8_bom = "\ x {FEFF}";
utf8 :: encode ($ utf8_bom);

· Una heurística ingenua, pero a menudo suficiente, en plataformas ASCII, para probar la primera
secuencia de bytes de alto bit en un archivo sin lista de materiales (ya sea en código o en Pod), para ver si
esa secuencia es válida como UTF-8 (RFC 2279) es para verificar si el primer byte en
la secuencia está en el rango 0xC2 - 0xFD y si el siguiente byte está en el rango
0x80 - 0xBF. Si es así, el analizador puede concluir que este archivo está en UTF-8, y todos
Se debe suponer que las secuencias de bits altos en el archivo son UTF-8. De lo contrario, el analizador
debe tratar el archivo como si estuviera en CP-1252. (Una mejor verificación y que funciona en EBCDIC
plataformas también, es pasar una copia de la secuencia a utf8 :: decode () que realiza
una verificación de validez completa en la secuencia y devuelve VERDADERO si es válido UTF-8, FALSO
de lo contrario. Esta función siempre está precargada, es rápida porque está escrita en C,
y solo te llamarán una vez como máximo, por lo que no es necesario que lo evites
problemas de rendimiento.) En la improbable circunstancia de que la primera secuencia de bits altos
en un archivo que realmente no es UTF-8 parece ser UTF-8, uno puede atender a nuestro
heurística (así como cualquier heurística más inteligente) anteponiendo esa línea con una
línea de comentario que contiene una secuencia highbit que es claramente No válido como UTF-8. Una linea
que consta simplemente de "#", un e-agudo y cualquier byte que no sea de bit alto, es suficiente para
establecer la codificación de este archivo.

· Los procesadores de pod deben tratar un párrafo "= para [etiqueta] [contenido ...]" con el mismo significado
algo como un párrafo "= comienzo [etiqueta]", contenido y un párrafo "= final [etiqueta]". (El
analizador puede combinar estas dos construcciones, o puede dejarlas distintas, en el
expectativa de que el formateador los tratará de la misma manera).

· Al renderizar Pod a un formato que permite comentarios (es decir, a casi cualquier formato, otro
que texto plano), un formateador de pod debe insertar texto de comentario que identifique su nombre y
número de versión, y el nombre y números de versión de cualquier módulo que pueda estar usando para
procesar el Pod. Ejemplos mínimos:

%% POD :: Pod2PS v3.14159, usando POD :: Parser v1.92



{\ doccomm generado por Pod :: Tree :: RTF 3.14159 usando Pod :: Tree 1.08}

. \ "Pod :: Man versión 3.14159, usando POD :: Parser versión 1.92

Los formateadores también pueden insertar comentarios adicionales, que incluyen: la fecha de lanzamiento del Pod
programa del formateador, la dirección de contacto del autor (es) del formateador, el
hora, el nombre del archivo de entrada, las opciones de formato vigentes, la versión de Perl utilizada,
etc.

Los formateadores también pueden optar por anotar errores / advertencias como comentarios, además o en lugar de
emitirlos de otra manera (como en mensajes a STDERR, o "morir" ing).

· Analizadores de pod pueden emitir advertencias o mensajes de error ("Código E desconocido E ! ") a STDERR
(ya sea imprimiendo en STDERR, o "advirtiendo" / "carp" ing, o "muriendo" / "croak" ing),
but deben permitir la supresión de todas esas salidas STDERR y, en su lugar, permitir una opción para
informar errores / advertencias de alguna otra manera, ya sea activando una devolución de llamada, o
notando errores en algún atributo del objeto del documento, o en algunos igualmente discretos
mecanismo, o incluso agregando una sección "Errores de pod" al final del formulario analizado
del documento

· En casos de documentos excepcionalmente aberrantes, los analizadores de Pod pueden abortar el análisis. Incluso
entonces, debe evitarse el uso de "morir" / "croar"; siempre que sea posible, la biblioteca del analizador
puede simplemente cerrar el archivo de entrada y agregar texto como "*** Formato cancelado ***" al
final del documento en memoria (parcial).

· En los párrafos donde se entienden los códigos de formato (como E <...>, B <...>) (es decir, No
párrafos textuales, pero de alta calidad que incluyen párrafos ordinarios y párrafos de comando que
producir texto renderizable, como "= head1"), el espacio en blanco literal generalmente debe ser
considerado "insignificante", ya que un espacio literal tiene el mismo significado que cualquier
(distinto de cero) número de espacios literales, líneas nuevas literales y tabulaciones literales (siempre que
esto no produce líneas en blanco, ya que terminarían el párrafo). Analizadores de pod
debe compactar espacios en blanco literal en cada párrafo procesado, pero puede proporcionar un
opción para anular esto (ya que algunas tareas de procesamiento no lo requieren), o puede
seguir reglas especiales adicionales (por ejemplo, tratar especialmente período-espacio-espacio o
secuencias de período-nueva línea).

· Los analizadores de pod no deberían, de forma predeterminada, intentar forzar el apóstrofo (') y citar (") en
comillas tipográficas (pequeños 9, 66, 99, etc.), ni intente convertir la comilla invertida (`) en nada
más que un carácter de comilla invertida (¡distinto de un carácter de comillas abiertas!), ni
"-" en cualquier cosa menos dos signos menos. Ellos deben nunca hacer cualquiera de esas cosas para
texto en códigos de formato C <...>, y nunca vez al texto en párrafos textuales.

· Al renderizar Pod en un formato que tiene dos tipos de guiones (-), uno que no es
guión de ruptura, y otro que es un guión rompible (como en "orientado a objetos", que
se puede dividir en líneas como "objeto-", nueva línea, "orientado"), los formateadores son
se recomienda traducir "-" en general a un guión que no se separe, pero puede aplicar heurísticas
para convertir algunos de estos en guiones de ruptura.

· Los formateadores de pod deben hacer esfuerzos razonables para evitar que las palabras del código Perl
roto a través de líneas. Por ejemplo, "Foo :: Bar" en algunos sistemas de formato se ve como
apto para dividirse entre líneas como "Foo ::" nueva línea "Bar" o incluso "Foo :: -"
nueva línea "Bar". Esto debe evitarse siempre que sea posible, ya sea desactivando todas las líneas
interrumpiendo a la mitad de la palabra, o envolviendo palabras particulares con puntuación interna en
los códigos "no divida esto entre líneas" (que en algunos formatos pueden no ser un solo código,
pero podría ser una cuestión de insertar espacios de ancho cero que no se rompan entre cada par
de caracteres en una palabra.)

· Los analizadores de pod deben, de forma predeterminada, expandir las pestañas en los párrafos textuales tal como están
procesados, antes de pasarlos al formateador u otro procesador. Los analizadores también pueden
permitir una opción para anular esto.

· Los analizadores de pods deberían, de forma predeterminada, eliminar las nuevas líneas del final de lo ordinario y literal
párrafos antes de pasarlos al formateador. Por ejemplo, mientras que el párrafo
que está leyendo ahora podría considerarse, en la fuente de Pod, para terminar con (y contener) el
nueva (s) línea (s) que lo terminan, debe procesarse como terminando con (y conteniendo) el
carácter de punto que finaliza esta oración.

· Los analizadores de pods, cuando informan errores, deben hacer un esfuerzo para informar un
número de línea ("E <> anidadas en el párrafo 52, cerca de la línea 633 de Thing / Foo.pm!"), en su lugar
de simplemente anotar el número de párrafo ("Anidado E <> en el párrafo # 52 de
Thing / Foo.pm! "). Cuando esto sea problemático, el número de párrafo debe ser al menos
acompañada de un extracto del párrafo ("Anidado E <> en el párrafo # 52 de
Thing / Foo.pm, que comienza con el descriptor de acceso de lectura / escritura para C
atributo...'").

· Los analizadores de pod, al procesar una serie de párrafos textuales uno tras otro, deben
considérelos como un gran párrafo literal que contiene líneas en blanco.
Es decir, estas dos líneas, que tienen una línea en blanco entre ellas:

usar Foo;

imprimir Foo-> VERSION

debe estar unificado en un párrafo ("\ tuse Foo; \ n \ n \ tprint Foo-> VERSION") antes
pasando al formateador u otro procesador. Los analizadores también pueden permitir una opción
por anular esto.

Si bien esto puede ser demasiado engorroso de implementar en analizadores de pod basados ​​en eventos, es
sencillo para analizadores que devuelven árboles de análisis.

· Se recomienda a los formateadores de pods, cuando sea posible, que eviten dividir palabras breves
párrafos (menos de doce líneas, digamos) en las páginas.

· Los analizadores de pod deben tratar una línea con solo espacios y / o tabulaciones como una "línea en blanco"
como separa párrafos. (Algunos analizadores más antiguos reconocieron solo dos
nuevas líneas como una "línea en blanco" pero no reconocería una nueva línea, un espacio y una nueva línea,
como una línea en blanco. Este es un comportamiento de incumplimiento).

· Los autores de los formateadores / procesadores de pod deben hacer todo lo posible para evitar escribir sus
propio analizador de Pod. Ya existen varios en CPAN, con una amplia gama de interfaces
styles, y uno de ellos, Pod :: Parser, viene con versiones modernas de Perl.

· Los caracteres en los documentos de Pod se pueden transmitir como literales o por número en E
códigos, o por un mnemónico equivalente, como en E que es exactamente equivalente a
E <233>. Los números son los valores Latin1 / Unicode, incluso en plataformas EBCDIC.

Al referirse a los caracteres con una E código numérico, números en el rango 32-126
se refieren a los conocidos caracteres US-ASCII (también definidos allí por Unicode, con la
mismo significado), que todos los formateadores de Pod deben representar fielmente. Caracteres cuya E <>
los números están en los rangos 0-31 y 127-159 no deben usarse (ni como literales,
ni como E códigos), a excepción de las secuencias de bytes literales para la nueva línea (ASCII 13,
ASCII 13 10 o ASCII 10) y tabulación (ASCII 9).

Los números en el rango 160-255 se refieren a caracteres Latin-1 (también definidos allí por
Unicode, con el mismo significado). Los números superiores a 255 deben entenderse como
Caracteres Unicode.

· Tenga en cuenta que algunos formateadores no pueden representar de forma fiable caracteres fuera de 32-126; y
muchos pueden manejar 32-126 y 160-255, pero nada por encima de 255.

· Además del conocido "E "y" E "códigos para menor que y mayor-que, Pod
los analizadores deben comprender "E "para" / "(solidus, barra) y" E "para" | "
(barra vertical, tubo). Los analizadores de pod también deben comprender "E " y
"MI "como códigos heredados para los caracteres 171 y 187, es decir," doble que apunta a la izquierda
comillas de ángulo "=" guillemet que apunta a la izquierda "y" ángulo doble que apunta a la derecha
comillas "=" guillemet apuntando hacia la derecha ". (Parecen pequeños" << "y" >> ",
y ahora se expresan preferiblemente con los códigos HTML / XHTML "E " y
"MI ".)

· Los analizadores de pod deben comprender todas las "E "códigos definidos en la entidad
declaraciones en la especificación XHTML más reciente en "www.W3.org". Los analizadores de pod deben
comprender al menos las entidades que definen caracteres en el rango 160-255
(Latín-1). Los analizadores de pods, cuando se enfrentan a algunos "Eidentificador> "código, no debería
simplemente reemplácelo con nullstring (por defecto, al menos), pero puede pasarlo como un
cadena que consta de los caracteres literales E, menor que, identificador, mas grande que.
O los analizadores de pod pueden ofrecer la opción alternativa de procesar tales
"MIidentificador> "códigos disparando un evento especialmente para dichos códigos, o agregando un
tipo de nodo especial para el árbol de documentos en memoria. Tal "Eidentificador> "puede tener
un significado especial para algunos procesadores, o algunos procesadores pueden optar por agregarlos a un
informe de error especial.

· Los analizadores de pod también deben admitir los códigos XHTML "E "para el carácter 34 (comillas dobles,
")," E "para el carácter 38 (ampersand, &) y" E "para el personaje 39
(apóstrofe, ').

· Tenga en cuenta que en todos los casos de "E ", lo que (ya sea un nombre html o un número en
cualquier base) debe constar solo de caracteres alfanuméricos, es decir, lo que debe vigilar
"m / \ A \ w + \ z /". Por tanto, "E <0 1 2 3>" no es válido porque contiene espacios, que no
caracteres alfanuméricos. Esto presumiblemente no necesite tratamiento especial por una vaina
procesador; "0 1 2 3" no parece un número en ninguna base, por lo que presumiblemente
buscar en la tabla de nombres similares a HTML. Dado que no hay (y no puede haber) un
Entidad similar a HTML llamada "0 1 2 3", esto se tratará como un error. Sin embargo, Pod
los procesadores pueden tratar "E <0 1 2 3>" o "E " como sintácticamente inválido,
potencialmente obteniendo un mensaje de error diferente al mensaje de error (o advertencia, o
evento) generado por un htmlname simplemente desconocido (pero teóricamente válido), como en
"MI "[sic]. Sin embargo, los analizadores de pods no están obligados a hacer esta distinción.

· Tenga en cuenta que E deben No ser interpretado simplemente como "codepoint número en la sección de
conjunto de caracteres actual / nativo ". Siempre significa sólo" el carácter representado por
punto de código número en Unicode. "(Esto es idéntico a la semántica de & #número; en
XML.)

Esto probablemente requerirá que muchos formateadores tengan tablas de mapeo de Unicode tratable
puntos de código (como el "\ xE9" para el carácter e-aguda) a las secuencias de escape o
códigos necesarios para transmitir tales secuencias en el formato de salida de destino. Un convertidor
a * roff, por ejemplo, sabría que "\ xE9" (ya sea que se transmita literalmente o mediante un
E <...> secuencia) debe transmitirse como "e \\ * '". Del mismo modo, un programa que renderiza Pod en
una ventana de la aplicación Mac OS, presumiblemente necesitaría saber que "\ xE9" se asigna a
el punto de código 142 en la codificación MacRoman que (en el momento de escribir este artículo) es nativo para Mac OS.
Tales asignaciones Unicode2, cualquiera que sea, presumiblemente ya están ampliamente disponibles para
formatos de salida. (¡Tales mapeos pueden estar incompletos! No se espera que los implementadores
hacer todo lo posible en un intento de traducir silábicas cherokee, runas etruscas,
Símbolos musicales bizantinos, o cualquiera de las otras cosas raras que Unicode puede codificar).
Y si un documento de Pod utiliza un carácter que no se encuentra en dicho mapeo, el formateador
Debería considerarlo un carácter irreprimible.

· Si, sorprendentemente, el implementador de un formateador Pod no puede encontrar una
asignación de tabla existente de caracteres Unicode a escapes en el formato de destino (por ejemplo,
una tabla decente de caracteres Unicode para * roff escapa), será necesario construir
tal mesa. Si se encuentra en esta circunstancia, debe comenzar con los personajes
en el rango 0x00A0 - 0x00FF, que son principalmente los caracteres acentuados más utilizados.
Luego proceda (según lo permita la paciencia y la meticulosidad lo obligue) a través de los personajes
que los grupos de estándares (X) HTML juzgaron lo suficientemente importantes como para merecer mnemónicos.
Estos se declaran en las especificaciones HTML (X) en el sitio www.W3.org. En el momento de
escrito (septiembre de 2001), los archivos de declaración de entidad más recientes son:

http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

Luego, puede avanzar a través de los caracteres Unicode notables restantes en el rango
0x2000-0x204D (consulte las tablas de caracteres en www.unicode.org), y cualquier otra cosa
te llama la atención. Por ejemplo, en xhtml-simbolo.ent, ahí está la entrada:



Mientras que la asignación "infin" al carácter "\ x {221E}" (con suerte) habrá sido
ya manejado por el analizador de Pod, la presencia del carácter en este archivo significa
que es lo suficientemente importante como para incluirlo en la tabla de un formateador que se asigna desde
caracteres Unicode notables a los códigos necesarios para representarlos. Entonces para un
Mapeo Unicode-to- * roff, por ejemplo, esto merecería la entrada:

"\ x {221E}" => '\ (en',

Se espera ansiosamente que en el futuro, un número cada vez mayor de formatos (y formateadores)
admitirá caracteres Unicode directamente (como (X) HTML lo hace con "∞", "∞",
o "∞"), reduciendo la necesidad de mapeos idiosincrásicos de Unicode-to-mis_escapes.

· Depende del formateador de Pod individual mostrar buen juicio cuando se enfrenta a un
carácter no reproducible (que es distinto de una E desconocida secuencia que el
el analizador no pudo resolver nada, renderizable o no). Es una buena práctica mapear
Letras latinas con diacríticos (como "E "/" E <233> ") al correspondiente
letras US-ASCII sin acento (como un carácter simple 101, "e"), pero claramente esto es
a menudo no es factible, y un carácter no reproducible puede representarse como "?", o el
me gusta. Al intentar una alternativa sensata (desde E <233> a "e"), los formateadores de pod pueden utilizar
la tabla% Latin1Code_to_fallback en Pod :: Escapes o Text :: Unidecode, si está disponible.

Por ejemplo, este texto de Pod:

La magia está habilitada si establece C <$ Moneda> en 'E '.

se puede representar como: "la magia está habilitada si configura $ Moneda en '?'"o como" la magia es
habilitado si configura $ Moneda en '[euro]'", o como" magia está habilitada si configura
$ Moneda a '[x20AC]', etc.

Un formateador de pod también puede anotar, en un comentario o advertencia, una lista de lo que no se puede reproducir
se encontraron personajes.

· E <...> puede aparecer libremente en cualquier código de formato (que no sea en otro E <...> o en un
Z <>). Es decir, "X 1,000,000 Solución> "es válida, al igual que" L
mi 1,000,000 Solución | Millones :: Euros> ".

· Algunos formateadores de pod dan salida a formatos que implementan espacios que no se rompen como
carácter individual (que llamaré "NBSP"), y otros dan salida a formatos que
implementar espacios que no se rompan al igual que los espacios envueltos en un "no dividir esto
líneas ". Tenga en cuenta que en el nivel de Pod, pueden producirse ambos tipos de códigos: Pod
contienen un carácter NBSP (ya sea como literal, o como "E <160>" o "E "código);
y el pod puede contener "S baz> "códigos, donde" meros espacios "(carácter 32) en
estos códigos se toman para representar espacios que no se rompen. Los analizadores de pod deben considerar
apoyando el análisis opcional de "S baz> "como si fuera
"foonbspInbspbaz ", y, en sentido contrario, el análisis opcional de grupos de
palabras unidas por NBSP como si cada grupo estuviera en un código S <...>, de modo que los formateadores puedan
utilice la representación que mejor se corresponda con lo que exige el formato de salida.

· Algunos procesadores pueden encontrar que el código "S <...>" es más fácil de implementar reemplazando
cada espacio en el árbol de análisis sintáctico bajo el contenido de la S, con un NBSP. Pero nota: el
el reemplazo debe aplicarse No a espacios en que todas texto, pero only a espacios en imprimible
texto. (Esta distinción puede o no ser evidente en el modelo de árbol / evento particular
implementado por el analizador de pod). Por ejemplo, considere este caso inusual:

S >

Esto significa que el espacio en el medio del texto del enlace visible no debe romperse.
a través de líneas. En otras palabras, es lo mismo que esto:

L <"Funciones de carga automáticaE <160>" / Funciones de carga automática>

Sin embargo, un reemplazo de espacio a NBSP mal aplicado podría (incorrectamente) producir algo
equivalente a esto:

L <"Funciones de carga automáticaE <160>" / Funciones de carga automáticaE <160>>

... que casi definitivamente no funcionará como un hipervínculo (asumiendo que esto
formateador genera un formato que admite hipertexto).

Los formateadores pueden optar por no admitir el código de formato S, especialmente en los casos en que
el formato de salida simplemente no tiene ningún carácter / código NBSP y ningún código para "no rompa esto
cosas a través de líneas ".

· Además del carácter NBSP discutido anteriormente, a los implementadores se les recuerda la existencia
del otro carácter "especial" en Latin-1, el carácter de "guión suave", también conocido
como "guión discrecional", es decir, "E <173>" = "E <0xAD>" = "E "). Este personaje
expresa un punto de separación de sílabas opcional. Es decir, normalmente se muestra como nada, pero
se puede representar como un "-" si un formateador rompe la palabra en ese punto. Formateadores de pod
debe, según corresponda, realizar una de las siguientes acciones: 1) renderizar esto con un código con la
mismo significado (por ejemplo, "\ -" en RTF), 2) pasarlo con la expectativa de que el
El formateador entiende este carácter como tal, o 3) elimínelo.

Por ejemplo:

sigE acción
manuE texto
JarkE ko HieE taE nieE mi

Estos le indican al formateador que si debe dividir con guiones "sigaction" o "manuscrito",
entonces debería hacerse como "sig-[salto de línea]acción "o" manu-[salto de línea]script "(y si
no lo separa con guiones, entonces la "E "no aparece en absoluto). Y si es para
separe "Jarkko" y / o "Hietaniemi", solo puede hacerlo en los puntos donde hay
una "E "código.

En la práctica, se prevé que este carácter no se utilizará con frecuencia, pero
los formateadores deben admitirlo o eliminarlo.

· Si cree que desea agregar un nuevo comando a Pod (como, por ejemplo, un "= biblio"
comando), considere si podría obtener el mismo efecto con un for o begin / end
secuencia: "= para biblio ..." o "= comenzar biblio" ... "= finalizar biblio". Procesadores de vainas que
no entiendo "= para biblio", etc., simplemente lo ignorarán, mientras que pueden quejarse
en voz alta si ven "= biblio".

· A lo largo de este documento, "Pod" ha sido la ortografía preferida para el nombre del
formato de documentación. También se puede utilizar "POD" o "pod". Para la documentación que es
(normalmente) en el formato Pod, puede utilizar "pod", "Pod" o "POD". Comprensión
estas distinciones son útiles; pero obsesionarse con cómo deletrearlos, por lo general no lo es.

Acerca de L <...> Códigos

Como puede ver de un vistazo a perlpod, el código L <...> es el más complejo del Pod
códigos de formato. Es de esperar que los puntos siguientes aclaren qué significa y cómo
los procesadores deberían ocuparse de ello.

· Al analizar un código L <...>, los analizadores de pod deben distinguir al menos cuatro atributos:

Primero:
El texto del enlace. Si no hay ninguno, debe ser "indef". (Por ejemplo, en "L
Funciones | perlfunc> ", el texto del vínculo es" Funciones Perl ". En" L " y
incluso "L <| Time :: HiRes>", no hay texto de enlace. Tenga en cuenta que el texto del enlace puede contener
formateo.)

Segundo:
El texto de enlace posiblemente inferido; es decir, si no hay un texto de enlace real, entonces este
es el texto que deduciremos en su lugar. (Por ejemplo, para "L ", el
el texto del enlace inferido es "Getopt :: Std".)

Tercero:
El nombre o URL, o "indef" si no hay ninguno. (Por ejemplo, en "L ", el
nombre (también llamado a veces la página) es "perlfunc". En "L ", el nombre
es "indef".)

Cuarto:
La sección (también conocido como "elemento" en los perlpods más antiguos), o "undef" si no hay ninguno. Por ejemplo, en
"L "," DESCRIPCIÓN "es la sección. (Tenga en cuenta que esto es
no es lo mismo que una sección de página de manual como el "5" en "man 5 crontab". "Sección Foo"
en el sentido de Pod significa la parte del texto que se introduce con el encabezado o
elemento cuyo texto es "Foo".)

Los analizadores de pod también pueden tener en cuenta atributos adicionales que incluyen:

Quinto:
Una marca para indicar si el elemento 3 (si está presente) es una URL (como "http://lists.perl.org" es),
en cuyo caso no debería haber ningún atributo de sección; un nombre de Pod (como "perldoc" y
"Getopt :: Std" son); o posiblemente un nombre de página de manual (como "crontab(5) "es).

Sexto:
El contenido L <...> original sin procesar, antes de que el texto se divida en "|", "/", etc., y antes
Los códigos E <...> se expanden.

(Los anteriores se enumeraron solo para una referencia concisa a continuación. No es un requisito
que estos se pasen como una lista o matriz real).

Por ejemplo:

L
=> undef, # texto del enlace
"Foo :: Bar", # texto del enlace posiblemente inferido
"Foo :: Bar", # nombre
undef, # sección
'pod', # qué tipo de enlace
"Foo :: Bar" # contenido original

L
=> "Sección de Perlport sobre NL", # texto del enlace
"Sección de Perlport sobre NL", # texto del enlace posiblemente inferido
"perlport", # nombre
"Nuevas líneas", # sección
'pod', # qué tipo de enlace
"Sección de Perlport sobre NL's | perlport / Newlines"
# contenido original

L
=> undef, # texto del enlace
'"Newlines" in perlport', # texto del enlace posiblemente inferido
"perlport", # nombre
"Nuevas líneas", # sección
'pod', # qué tipo de enlace
"perlport / Newlines" # contenido original

L<crontab(5) / "DESCRIPCIÓN">
=> undef, # texto del enlace
'"DESCRIPCIÓN" en crontab(5) ', # texto del enlace posiblemente inferido
"crontab(5) ", # nombre
"DESCRIPCIÓN", # sección
'man', # qué tipo de enlace
'crontab(5) / "DESCRIPTION" '# contenido original

L
=> undef, # texto del enlace
'"Atributos de objeto"', # texto del enlace posiblemente inferido
undef, # nombre
"Atributos de objeto", # sección
'pod', # qué tipo de enlace
"/ Atributos del objeto" # contenido original

L<http://www.perl.org/>
=> undef, # texto del enlace
"http://www.perl.org/", # texto del enlace posiblemente inferido
"http://www.perl.org/", # nombre
undef, # sección
'url', # qué tipo de enlace
"http://www.perl.org/"# contenido original

Lhttp://www.perl.org/>
=> "Perl.org", # texto del enlace
"http://www.perl.org/", # texto del enlace posiblemente inferido
"http://www.perl.org/", # nombre
undef, # sección
'url', # qué tipo de enlace
"Perl.org |http://www.perl.org/"# contenido original

Tenga en cuenta que puede distinguir los enlaces URL de cualquier otra cosa por el hecho de que coinciden
"m / \ A \ w +: [^: \ s] \ S * \ z /". Entonces "Lhttp://www.perl.com> "es una URL, pero" L "
no lo es.

· En caso de códigos L <...> sin "texto |" parte de ellos, los formateadores más antiguos han exhibido
gran variación en la visualización real del enlace o la referencia cruzada. Por ejemplo,
L<crontab(5)> se representaría como "el crontab(5) página de manual ", o" en el crontab(5) página de manual "
o solo "crontab(5) ".

Los procesadores de pod ahora deben tratar los enlaces sin "texto |" de la siguiente manera:

L => L
L => L <"sección" | / sección>
L => L <"sección" en nombre | nombre / sección>

· Tenga en cuenta que los nombres de las secciones pueden contener marcas. Es decir, si una sección comienza con:

= head2 Acerca del operador C <-M>

o con:

= item Acerca del operador C <-M>

entonces un enlace se vería así:

L Operador>

Los formateadores pueden optar por ignorar el marcado con el fin de resolver el enlace y utilizar
solo los caracteres renderizables en el nombre de la sección, como en:

Sobre el -M
Operador

...

Sobre el -M
Operador "en somedoc

· Versiones anteriores de perlpod distinguieron "L "enlaces de
"L "(y sus destinos). Se han fusionado sintácticamente y
semánticamente en la especificación actual, y . puede referirse a "= headn
Encabezado del comando "Contenido" o al comando "= elemento Contenido del elemento". Esta especificación
no especifica qué comportamiento debería ser en el caso de que un documento dado tenga
varias cosas que parecen producir lo mismo . identificador (p. ej., en HTML,
varias cosas todas produciendo lo mismo nombre de ancla ennombre de ancla"> ...
elementos). Donde los procesadores de Pod pueden controlar este comportamiento, deben usar el primero
tal ancla. Es decir, "L " se refiere a first Sección "Bar" en Foo.

Pero para algunos procesadores / formatos, esto no se puede controlar fácilmente; como con el HTML
ejemplo, el comportamiento de múltiples ambiguosnombre de ancla"> ... es más
fácilmente, simplemente se deja en manos de los navegadores para que decidan.

· En una "L "código, el texto puede contener códigos de formato para formatear o para
E <...> escapa, como en:

L cosas> | ...>

Para códigos "L <...>" sin un "nombre |" parte, sólo pueden aparecer los códigos "E <...>" y "Z <>".
Es decir, los autores no deben utilizar "" L > "".

Tenga en cuenta, sin embargo, que los códigos de formato y Z <> pueden ocurrir en todas y cada una de las partes de un
L <...> (es decir, en nombre , ., texto y url).

Los autores no deben anidar códigos L <...>. Por ejemplo, "L página man> "debería
ser tratado como un error.

· Tenga en cuenta que los autores de pods pueden usar códigos de formato dentro de la parte de "texto" de
"L "(y así sucesivamente para L ).

En otras palabras, esto es válido:

Ve a leer L | perlvar / "$.">

Algunos formatos de salida que permiten la representación de códigos "L <...>" como hipertexto, pueden no
permitir que se formatee el texto del enlace; en ese caso, los formateadores tendrán que ignorar
ese formato.

· Al momento de escribir, "L "los valores son de dos tipos: el nombre de una página de pod
como "L "(que podría ser un módulo o programa Perl real en un @INC / PATH
directorio, o un archivo .pod en esos lugares); o el nombre de una página de manual de Unix, como
"Lcrontab(5)> ". En teoría," L "en ambiguo entre una página de pod llamada
"chmod", o la página de manual de Unix "chmod" (en cualquier sección de manual). sin embargo, el
presencia de una cadena en parens, como en "crontab(5) ", es suficiente para señalar que lo que
lo que se está discutiendo no es una página de Pod, por lo que presumiblemente es una página de manual de Unix. El
La distinción no tiene importancia para muchos procesadores Pod, pero algunos procesadores que
renderizar a formatos de hipertexto puede necesitar distinguirlos para saber cómo
renderizar una "L dada "código.

· Las versiones anteriores de perlpod permitían una "L "sintaxis (como en" L
Atributos> "), que no se distingue fácilmente de" L "sintaxis y para
"L <" sección ">" que era sólo un poco menos ambigua. Esta sintaxis ya no está en
la especificación, y ha sido reemplazada por la "L "sintaxis (donde la barra
antes era opcional). Los analizadores de pod deben tolerar la sintaxis "L <" section ">", para
mientras que al menos. La heurística sugerida para distinguir "L " desde
"L "es que si contiene algún espacio en blanco, es un .. Procesadores de vainas
debería advertir sobre esta sintaxis obsoleta.

Acerca de = más ... = atrás Regiones

Las regiones "= over" ... "= back" se utilizan para varios tipos de estructuras similares a listas. (Yo uso el
término "región" aquí simplemente como un término colectivo para todo, desde el "= sobre" hasta el
coincidencia "= atrás".)

· El numérico distinto de cero nivel de sangría en "= más nivel de sangría"..." = back "se utiliza para
dando al formateador una pista sobre cuántos "espacios" (ems, o unidades aproximadamente equivalentes)
debería cambiar, aunque muchos formateadores tendrán que convertir esto en un valor absoluto
medida que puede no coincidir exactamente con el tamaño de los espacios (o M) en el
fuente base del documento. Es posible que otros formateadores deban ignorar por completo el número. El
falta de cualquier explícito nivel de sangría parámetro es equivalente a un nivel de sangría valor de 4.
Los procesadores de pod pueden quejarse si nivel de sangría está presente pero no es un número positivo
coincidente con "m / \ A (\ d * \.)? \ d + \ z /".

· Se recuerda a los autores de los formateadores de pod que "= over" ... "= back" puede mapear a varios
diferentes construcciones en su formato de salida. Por ejemplo, al convertir Pod a
(X) HTML, se puede asignar a cualquiera de ... , ... , ... , o
... . Del mismo modo, "= elemento" se puede asignar a o .

· Cada región "= over" ... "= back" debe ser una de las siguientes:

· Una región "= over" ... "= back" que contiene solo comandos "= item *", cada uno seguido de
algunos párrafos ordinarios / textuales, otros anidados "= over" ... "= back"
regiones, "= para ..." párrafos y "= comienzo" ... "= final" regiones.

(Los procesadores de pod deben tolerar un "= elemento" desnudo como si fuera "= elemento *").
"*" se representa como un asterisco literal, una "o" o como una especie de viñeta real
carácter, se deja en manos del formateador Pod, y puede depender del nivel de
anidamiento.

· Una región "= over" ... "= back" que contiene solo "m / \ A = item \ s + \ d + \.? \ S * \ z /"
párrafos, cada uno (o cada grupo de ellos) seguido de algún número de
párrafos ordinarios / textuales, otras regiones anidadas "= sobre" ... "= atrás", "= para ..."
párrafos y / o códigos "= comienzo" ... "= final". Tenga en cuenta que los números deben comenzar en 1
en cada sección, debiendo proceder en orden y sin saltarse números.

(Los procesadores de pod deben tolerar líneas como "= elemento 1" como si fueran "= elemento 1",
con el punto.)

· Una región "= over" ... "= back" que contiene solo comandos "= item [text]", cada uno
(o cada grupo de ellos) seguido de algunos párrafos ordinarios / textuales,
otras regiones anidadas "= sobre" ... "= atrás", o "= para ..." párrafos, y
"= comenzar" ... "= terminar" regiones.

El párrafo "= elemento [texto]" no debe coincidir con "m / \ A = elemento \ s + \ d + \.? \ S * \ z /" o
"m / \ A = item \ s + \ * \ s * \ z /", ni debe coincidir solo con "m / \ A = item \ s * \ z /".

· Una región "= over" ... "= back" que no contenga párrafos "= item" en absoluto, y
que contiene sólo algunos párrafos ordinarios / textuales, y posiblemente también
algunas regiones anidadas "= sobre" ... "= volver", "= para ..." párrafos y
"= comenzar" ... "= terminar" regiones. Esta región "= over" ... "= back" sin elementos en Pod es
equivalente en significado a un " ... "elemento en HTML.

Tenga en cuenta que con todos los casos anteriores, puede determinar qué tipo de "= sobre" ...
"= back" que tiene, al examinar el primer párrafo del pod después de
el comando "= over".

· Formateadores de pod deben tolerar cantidades arbitrariamente grandes de texto en el "= elemento texto..."
párrafo. En la práctica, la mayoría de estos párrafos son cortos, como en:

= artículo Para cortar nuestro comercio con todas las partes del mundo

Pero pueden ser arbitrariamente largos:

= artículo Para transportarnos más allá de los mares para ser probado por pretendido
delitos

= artículo En este momento está transportando grandes ejércitos de extranjeros
mercenarios para completar las obras de muerte, desolación y
tiranía, ya comenzada con circunstancias de crueldad y perfidia
apenas paralelo en las épocas más bárbaras, y totalmente
indigno de la cabeza de una nación civilizada.

· Los procesadores de pod deben tolerar "= item *" / "= item número"comandos sin
párrafo adjunto. El elemento del medio es un ejemplo:

= terminado

= artículo 1

Recoge la tintorería.

= artículo 2

= artículo 3

Pasa por la tienda. Consigue Abba Zabas, Stoli y sillas de jardín baratas.

= espalda

· Ninguna región "= over" ... "= back" puede contener encabezados. Los procesadores pueden tratar tal
encabezado como un error.

· Tenga en cuenta que una región "= over" ... "= back" debería tener algún contenido. Es decir, autores
no debería tener una región vacía como esta:

= terminado

= espalda

Los procesadores de pod que ven una región "= over" ... "= back" sin contenido, pueden ignorarla o
puede informarlo como un error.

· Los procesadores deben tolerar una lista "= over" que aparece al final del documento (es decir,
que no tiene "= back" coincidente), pero pueden advertir sobre dicha lista.

· Los autores de los formateadores de pod deben tener en cuenta que esta construcción:

= artículo Neque

= artículo Porro

= artículo Quisquam Est

Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

= artículo Ut Enim

es semánticamente ambiguo, de una manera que dificulta un poco las decisiones de formato.
Por un lado, se podría mencionar un ítem "Neque", mención de otro ítem
"Porro", y mención de otro ítem "Quisquam Est", solo el último requiere
el párrafo explicativo "Qui dolorem ipsum quia dolor ..."; y luego un elemento "Ut
Enim ". En ese caso, querrá formatearlo así:

Neque

Puerro

Quisquam Este
Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut-Enim

Pero también podría ser una discusión de tres elementos (relacionados o equivalentes),
"Neque", "Porro" y "Quisquam Est", seguido de un párrafo que los explica todos, y
luego un nuevo elemento "Ut Enim". En ese caso, probablemente quieras formatearlo así:

Neque
Puerro
Quisquam Este
Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut-Enim

Pero (en el futuro previsible), Pod no proporciona ninguna forma para que los autores de Pod
distinguir qué agrupación se refiere a la estructura de grupo "= elemento" anterior. Entonces
los formateadores deberían formatearlo así:

Neque

Puerro

Quisquam Este

Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut-Enim

Es decir, debe haber (al menos aproximadamente) un espaciado igual entre elementos como entre
párrafos (aunque ese espaciado bien puede ser menor que la altura total de una línea de
texto). Esto deja que el lector use señales (con) textuales para averiguar si
el párrafo "Qui dolorem ipsum ..." se aplica al elemento "Quisquam Est" oa todos
tres elementos "Neque", "Porro" y "Quisquam Est". Si bien no es una situación ideal, esta
es preferible a proporcionar pistas de formato que pueden ser contrarias a la
intención del autor.

Acerca de Fecha Párrafos y "= comienzo / = final" Regiones

Los párrafos de datos se utilizan normalmente para insertar datos que no son de Pod que se van a utilizar (normalmente
pasado) al renderizar el documento a un formato específico:

= comenzar rtf

\ par {\ pard \ qr \ sa4500 {\ i Impreso \ ~ \ chdate \ ~ \ chtime} \ par}

= final rtf

Por cierto, se podría lograr exactamente el mismo efecto con un solo párrafo "= para":

= para rtf \ par {\ pard \ qr \ sa4500 {\ i Printed \ ~ \ chdate \ ~ \ chtime} \ par}

(Aunque no es formalmente un párrafo de datos, tiene el mismo significado que uno, y Pod
los analizadores pueden analizarlo como uno).

Otro ejemplo de un párrafo de datos:

= comenzar html

¡Me gusta PIE !

¡Especialmente el pastel de nueces!

= terminar html

Si estos fueran párrafos normales, el analizador de Pod intentaría expandir la "E" (en el
primer párrafo) como un código de formato, como "E " mineral ". Pero desde este
está en un "= comenzar identificador"..." = fin identificador"región y el identificador "html" no
comenzar tienen un prefijo ":", el contenido de esta región se almacena como párrafos de datos,
en lugar de procesarse como párrafos ordinarios (o si comenzaban con espacios y / o
tabulaciones, como párrafos textuales).

Como ejemplo adicional: en el momento de redactar este artículo, no se admite ningún identificador "biblio", pero supongamos
algunos procesadores fueron escritos para reconocerlo como una forma de (digamos) denotar un
referencia (que necesariamente contiene códigos de formato en párrafos ordinarios). El hecho de que
Los párrafos "biblio" destinados a un procesamiento ordinario se indicarán con un prefacio.
cada identificador "biblio" con dos puntos:

= comenzar: biblio

Wirth, Niklaus. 1976. Yo
Programas.> Prentice-Hall, Englewood Cliffs, Nueva Jersey.

= fin: biblio

Esto le indicaría al analizador que los párrafos en esta región de inicio ... final están sujetos a
manejo normal como párrafos ordinarios / textuales (aunque todavía está etiquetado como destinado solo para
procesadores que entienden el identificador "biblio"). Se podría tener el mismo efecto con:

= para: biblio
Wirth, Niklaus. 1976. Yo
Programas.> Prentice-Hall, Englewood Cliffs, Nueva Jersey.

El ":" en estos identificadores significa simplemente "procesar este material normalmente, aunque el
el resultado será para algún objetivo especial ". Sugiero que las API del analizador informen" biblio "como
el identificador de destino, pero también informa que tenía un prefijo ":". (Y de manera similar, con el
encima de "html", informe "html" como el identificador de destino y observe el Negro de un prefijo ":".)

Tenga en cuenta que un "= comenzar identificador"..." = fin identificador"región donde identificador comienza con un
colon, can contener comandos. Por ejemplo:

= comenzar: biblio

El clásico de Wirth está disponible en varias ediciones, que incluyen:

= para comentario
hm, consulte iberlibro.com para saber cuánto cuestan las copias usadas.

= terminado

= artículo

Wirth, Niklaus. 1975. Yo
Teubner, Stuttgart. [Sí, está en alemán].

= artículo

Wirth, Niklaus. 1976. Yo
Programas.> Prentice-Hall, Englewood Cliffs, Nueva Jersey.

= espalda

= fin: biblio

Sin embargo, tenga en cuenta que un "= comenzar identificador"..." = fin identificador"región donde identificador sí No
comenzar con dos puntos, no debe contener directamente comandos "= head1" ... "= head4", ni
"= sobre", ni "= atrás", ni "= elemento". Por ejemplo, esto puede considerarse inválido:

= comenzar algunos datos

Este es un párrafo de datos.

= head1 ¡No hagas esto!

Este también es un párrafo de datos.

= terminar algunos datos

Un procesador de Pod puede indicar que lo anterior (específicamente el párrafo "= head1") es un
error. Sin embargo, tenga en cuenta que lo siguiente debe No ser tratado como un error:

= comenzar algunos datos

Este es un párrafo de datos.

= cortar

# Sí, esto ya no es Pod.
sub excl {(rand ()> .5)? "¡hoo!" : "¡ja!" }

= vaina

Este también es un párrafo de datos.

= terminar algunos datos

Y esto también es válido:

= comenzar algún formato

Este es un párrafo de datos.

Y este es un párrafo de datos.

= comenzar otro formato

Este también es un párrafo de datos.

Y este también es un párrafo de datos.

= comenzar: yetanotroformato

= head2 ¡Este es un párrafo de comando!

¡Este es un párrafo ordinario!

¡Y este es un párrafo literal!

= fin: yetanotroformato

= terminar algún otro formato

¡Otro párrafo de datos!

= terminar algún formato

El contenido de la región anterior "= begin: yetanotherformat" ... "= end: yetanotherformat"
no son párrafos de datos, porque el identificador de la región que contiene inmediatamente
(": yetanotherformat") comienza con dos puntos. En la práctica, la mayoría de las regiones que contienen datos
los párrafos contendrán only párrafos de datos; sin embargo, el anidamiento anterior es sintácticamente
válido como Pod, incluso si es raro. Sin embargo, los controladores de algunos formatos, como "html",
aceptará solo párrafos de datos, no regiones anidadas; y pueden quejarse si ven
(dirigido a ellos) regiones anidadas, o comandos, distintos de "= end", "= pod" y "= cut".

También considere esta estructura válida:

= comenzar: biblio

El clásico de Wirth está disponible en varias ediciones, que incluyen:

= terminado

= artículo

Wirth, Niklaus. 1975. Yo
Teubner, Stuttgart. [Sí, está en alemán].

= artículo

Wirth, Niklaus. 1976. Yo
Programas.> Prentice-Hall, Englewood Cliffs, Nueva Jersey.

= espalda

¡Compra compra compra!

= comenzar html





= terminar html

¡Ahora ahora ahora!

= fin: biblio

Allí, la región "= begin html" ... "= end html" está anidada dentro de la más grande "= begin
: biblio "..." = end: biblio "región. Tenga en cuenta que el contenido de la" = begin html "..." = end
html "es párrafo (s) de datos, porque el identificador de la región que contiene inmediatamente
("html") no se comience con dos puntos.

Analizadores de pod, al procesar una serie de párrafos de datos uno tras otro (dentro de un
región única), debería considerarlos como un gran párrafo de datos que
contener líneas en blanco. Entonces, el contenido de lo anterior "= begin html" ... "= end html" pueden be
almacenados como dos párrafos de datos (uno que consta de "
src = 'wirth_spokesmodeling_book.png'> \ n "y otro que consta de" \ n "), pero debo be
almacenados como un solo párrafo de datos (que consta de "
src = 'wirth_spokesmodeling_book.png'> \ n \ n \norte").

Los procesadores de pod deben tolerar el vacío "= begin algo"..." = fin algo"regiones, vacías
"= comenzar:algo"..." = final:algo"regiones y sin contenido" = para algo"Y
"= para:algo"párrafos. Es decir, estos deben ser tolerados:

= para html

= comenzar html

= terminar html

= comenzar: biblio

= fin: biblio

Por cierto, tenga en cuenta que no hay una manera fácil de expresar un párrafo de datos que comience con
algo que parece un comando. Considerar:

= empezar cosas

= shazbot

= terminar cosas

Allí, "= shazbot" se analizará como un comando de Pod "shazbot", no como un párrafo de datos
"= shazbot \ n". Sin embargo, puede expresar un párrafo de datos que consista en "= shazbot \ n" usando
este código:

= para cosas = shazbot

La situación en la que esto es necesario es presumiblemente bastante rara.

Tenga en cuenta que los comandos = end deben coincidir con el comando = begin actualmente abierto. Es decir, deben
anidar correctamente. Por ejemplo, esto es válido:

= comenzar exterior

X

= comenzar interior

Y

= final interior

Z

= final exterior

mientras esto no es válido:

= comenzar exterior

X

= comenzar interior

Y

= final exterior

Z

= final interior

Esto último es incorrecto porque cuando se ve el comando "= end external", el
región tiene el nombre de formato "interno", no "externo". (Sucede que "externo" es el
nombre de formato de una región superior.) Esto es un error. Los procesadores deben informar de forma predeterminada
esto como un error y puede detener el procesamiento del documento que contiene ese error. Un corolario
de esto es que las regiones no pueden "superponerse". Es decir, el último bloque anterior no
representan una región llamada "exterior" que contiene X e Y, superponiéndose a una región llamada
"interno" que contiene Y y Z. Pero debido a que no es válido (ya que todos aparentemente se superponen
regiones sería), no representa eso, ni nada en absoluto.

Del mismo modo, esto no es válido:

= comenzar cosa

= terminar hting

Esto es un error porque la región está abierta por "cosa", y el "= end" intenta cerrarse
"hting" [sic].

Esto también es inválido:

= comenzar cosa

= fin

Esto no es válido porque cada comando "= end" debe tener un parámetro de nombre de formato.

Use perlpodspec en línea usando los servicios de onworks.net