perlpod - Online en la nube

PROGRAMA:

NOMBRE

perlpod - el formato simple de documentación antigua

DESCRIPCIÓN

Pod es un lenguaje de marcado fácil de usar que se utiliza para escribir documentación para Perl, Perl
programas y módulos Perl.

Hay traductores disponibles para convertir Pod a varios formatos como texto sin formato, HTML, man
páginas y más.

El marcado de pod consta de tres tipos básicos de párrafos: ordinario, literal y de comando.

Ordinario párrafo
La mayoría de los párrafos de su documentación serán bloques de texto normales, como éste. usted
puede simplemente escribir su texto sin ningún tipo de marcación y con solo una línea en blanco
antes y después de. Cuando se formatea, se someterá a un formato mínimo, como
reenvasado, probablemente puesto en una fuente con espaciado proporcional, y tal vez incluso justificado.

Puede utilizar códigos de formato en párrafos ordinarios, para , itálico, "estilo de código",
hipervínculos y más. Dichos códigos se explican en la sección "Códigos de formato", a continuación.

Literal párrafo
Los párrafos textuales se utilizan generalmente para presentar un bloque de código u otro texto que no
no requieren ningún análisis o formato especial, y que no deben ajustarse.

Un párrafo textual se distingue porque su primer carácter es un espacio o una tabulación.
(Y comúnmente, todas sus líneas comienzan con espacios y / o tabulaciones). Debe reproducirse
exactamente, asumiendo que las pestañas están en los límites de 8 columnas. No hay formato especial
códigos, por lo que no puede poner en cursiva ni nada por el estilo. A \ significa \, y nada más.

Comando párrafo
Un párrafo de comando se usa para un tratamiento especial de fragmentos completos de texto, generalmente como
encabezados o partes de listas.

Todos los párrafos de comando (que suelen tener solo una línea) comienzan con "=", seguidos
por un identificador, seguido de un texto arbitrario que el comando puede usar como le plazca.
Los comandos actualmente reconocidos son

= vaina
= head1 Heading Text
= head2 Heading Text
= head3 Heading Text
= head4 Heading Text
= sobre el nivel de sangría
= cosas del artículo
= espalda
= comenzar formato
= formato final
= para formato de texto ...
= tipo de codificación
= cortar

Para explicarlos cada uno en detalle:

"= cabeza1 Encabezado Texto"
"= cabeza2 Encabezado Texto"
"= cabeza3 Encabezado Texto"
"= cabeza4 Encabezado Texto"
Head1 a head4 producen títulos, siendo head1 el nivel más alto. El texto en el
el resto de este párrafo es el contenido del encabezado. Por ejemplo:

= Atributos del objeto head2

El texto "Atributos del objeto" comprende el encabezado allí. El texto en este encabezado
Los comandos pueden usar códigos de formato, como se ve aquí:

= head2 Valores posibles para C <$ />

Estos comandos se explican en la sección "Códigos de formato", a continuación.

"= más indentlevel "
"= artículo cosas..."
"= atrás"
El elemento, el final y el reverso requieren un poco más de explicación: "= over" inicia una región
específicamente para la generación de una lista usando comandos "= item", o para sangrar
(grupos de) párrafos normales. Al final de su lista, use "= back" para terminarla. los
nivel de sangría la opción "= over" indica qué tan lejos de la sangría, generalmente en ems
(donde un em es el ancho de una "M" en la fuente base del documento) o aproximadamente
unidades comparables; si no hay nivel de sangría opción, el valor predeterminado es cuatro. (Y algo
los formateadores pueden simplemente ignorar lo que sea nivel de sangría usted proporciona.) En el cosas en "= elemento
cosas...", puede utilizar códigos de formato, como se ve aquí:

= elemento que usa C <$ |> para controlar el almacenamiento en búfer

Estos comandos se explican en la sección "Códigos de formato", a continuación.

Tenga en cuenta también que existen algunas reglas básicas para usar regiones "= over" ... "= back":

· No use "= item" s fuera de una región "= over" ... "= back".

· La primera cosa después del comando "= over" debe ser un "= item", a menos que haya
no habrá ningún elemento en esta región "= over" ... "= back".

· No pongas "= cabezan"comandos dentro de una región" = over "..." = back ".

· Y quizás lo más importante, mantenga la coherencia de los elementos: utilice "= elemento *" para
todos ellos, para producir balas; o utilice "= artículo 1", "= artículo 2", etc., para producir
listas numeradas; o use "= item foo", "= item bar", etc., es decir, cosas que parecen
nada como viñetas o números.

Si comienza con viñetas o números, quédese con ellos, ya que los formateadores usan la primera
Escriba "= elemento" para decidir cómo formatear la lista.

"= cortar"
Para finalizar un bloque de Pod, use una línea en blanco, luego una línea que comience con "= cortar" y un espacio en blanco
línea después de ella. Esto le permite a Perl (y al formateador Pod) saber que aquí es donde Perl
el código se está reanudando. (La línea en blanco antes de "= cut" no es técnicamente necesaria, pero
muchos procesadores Pod más antiguos lo requieren).

"= vaina"
El comando "= pod" por sí solo no hace gran cosa, pero le indica a Perl (y
Formateadores de pod) que un bloque de pod comienza aquí. Un bloque de Pod comienza con cualquier comando
párrafo, por lo que generalmente se usa un comando "= pod" solo cuando desea iniciar un bloque de Pod
con un párrafo ordinario o un párrafo literal. Por ejemplo:

= cosas del artículo ()

Esta función hace cosas.

= cortar

sub cosas {
...
}

= vaina

Recuerde verificar su valor de retorno, como en:

cosas () || morir "¡No podía hacer cosas!";

= cortar

"= comenzar formatname "
"= fin formatname "
"= para nombredeformato texto..."
For, begin y end le permitirán tener regiones de texto / código / datos que generalmente no son
se interpretan como texto de Pod normal, pero se pasan directamente a formateadores particulares, o
son por lo demás especiales. Un formateador que pueda usar ese formato usará la región,
de lo contrario, se ignorará por completo.

Un comando "= comenzar nombredeformato", algunos párrafos y un comando" = fin nombredeformato", significar
que el texto / datos en el medio está destinado a formateadores que entienden el especial
formato llamado nombredeformato. Por ejemplo,

= comenzar html


Este es un párrafo HTML sin formato

= terminar html

El comando "= para nombredeformato texto..."especifica que el resto de este
párrafo (comenzando justo después nombredeformato) está en ese formato especial.

= para html
Este es un párrafo HTML sin formato

Esto significa lo mismo que la región anterior "= begin html" ... "= end html".

Es decir, con "= para", solo puede tener el valor de un párrafo de texto (es decir, el texto
en "= foo targetname text ..."), pero con "= begin targetname" ... "= end targetname",
puede tener cualquier cantidad de cosas en el medio. (Tenga en cuenta que todavía debe haber una línea en blanco
después del comando "= comenzar" y una línea en blanco antes del comando "= fin").

A continuación, se muestran algunos ejemplos de cómo utilizarlos:

= comenzar html

Figura 1.

= terminar html

= comenzar texto

---------------
| foo |
| barra |
---------------

^^^^ Figura 1. ^^^^

= texto final

Algunos nombres de formato que actualmente aceptan los formateadores incluyen "roff", "man",
"látex", "tex", "texto" y "html". (Algunos formateadores tratarán algunos de estos como
sinónimos.)

Un nombre de formato de "comentario" es común solo para tomar notas (presumiblemente para usted)
que no aparecerá en ninguna versión formateada del documento Pod:

= para comentario
¡Asegúrese de que todas las opciones disponibles estén documentadas!

Cosas nombres de formato requerirá dos puntos iniciales (como en "= for: formatname" o "= begin
: formatname "..." = end: formatname "), para indicar que el texto no son datos sin procesar, sino
is Texto de pod (es decir, que posiblemente contenga códigos de formato) que no es para
formato normal (por ejemplo, puede que no sea un párrafo de uso normal, pero podría ser para
formato como nota a pie de página).

"= codificación encodingname "
Este comando se utiliza para declarar la codificación de un documento. La mayoría de los usuarios no necesitarán
esta; pero si su codificación no es US-ASCII, coloque "= codificación encodingname " comando
muy temprano en el documento para que los formateadores de pod sepan cómo decodificar el
documento. Para nombre de codificación, use un nombre reconocido por el módulo Encode :: Supported.
Algunos formateadores de pod pueden intentar adivinar entre un Latin-1 o CP-1252 versus UTF-8
codificación, pero pueden adivinar mal. Es mejor ser explícito si usa algo
además de ASCII estricto. Ejemplos:

= codificación latin1

= codificación utf8

= codificación koi8-r

= codificación ShiftJIS

= codificación big5

"= codificación" afecta a todo el documento y debe ocurrir solo una vez.

Y no lo olvide, todos los comandos excepto "= codificación" duran hasta el final de su párrafono,
su línea. Entonces, en los ejemplos a continuación, puede ver que cada comando necesita la línea en blanco
después, para finalizar su párrafo. (Y algunos traductores de Pod más antiguos pueden requerir
"= codificación" línea para tener una siguiente línea en blanco también, aunque debería ser legal para
omitir.)

Algunos ejemplos de listas incluyen:

= terminado

= artículo *

Primer elemento

= artículo *

Segundo punto

= espalda

= terminado

= elemento Foo ()

Descripción de la función Foo

= barra de elementos ()

Descripción de la función de barra

= espalda

Maquetación Códigos
En párrafos ordinarios y en algunos párrafos de comando, varios códigos de formato (también conocidos como
"secuencias interiores") se pueden utilizar:

"I "- texto en cursiva
Usado para enfatizar ("" be I "") y parámetros ("" rehacer I "")

"B " -- texto en negrita
Usado para conmutadores ("" conmutador B <-n> de perl ""), programas ("" algunos sistemas proporcionan un
B para eso ""), énfasis ("" sea B ""), y así sucesivamente ("" y esa función es
conocido como B "").

"C " -- code text
Representa el código en una fuente de máquina de escribir, o da alguna otra indicación de que esto representa
texto del programa ("" C "") o alguna otra forma de informática
(""C "").

"L "- un hipervínculo
Hay varias sintaxis, que se enumeran a continuación. En las sintaxis dadas, "texto", "nombre" y
"sección" no puede contener los caracteres '/' y '|'; y cualquier '<' o '>' debe ser
emparejado

· "L "

Enlace a una página de manual de Perl (p. Ej., "L "). Tenga en cuenta que" nombre "no debe
contener espacios. Esta sintaxis también se usa ocasionalmente para referencias a Unix man
páginas, como en "Lcrontab(5)> ".

· "L "o" L "

Enlace a una sección en otra página del manual. Por ejemplo, "L "

· "L "o" L "

Enlace a una sección de esta página de manual. Por ejemplo, "L "

Una sección se inicia con el encabezado o elemento nombrado. Por ejemplo, "L " o
"L "ambos enlazan a la sección iniciada por" "= item $." "en perlvar. Y
"L "o" L "ambos enlazan a la sección iniciada por
"" = head2 For Loops "" en perlsyn.

Para controlar qué texto se usa para mostrar, usa "" L "", como en:

· "L "

Vincula este texto a esa página del manual. Por ejemplo, "L "

· "L "o" L "

Vincula este texto a esa sección de esa página de manual. Por ejemplo, "L
"if" | perlsyn / "Modificadores de declaraciones"> "

· "L "o" L "o" L "

Vincula este texto a esa sección de esta página de manual. Por ejemplo, "L
atributos | / "Datos de miembros"> "

O puede vincular a una página web:

· "L "

"L "

Vínculos a una URL absoluta. Por ejemplo, "Lhttp://www.perl.org/> "o" L
Página de inicio |http://www.perl.org/> ".

"MI "- un personaje de escape
Muy similar a HTML / XML "yfoo; " "referencias de entidad":

· "E "- un literal <(menor que)

· "E "- un literal> (mayor que)

· "E "- un literal | (vertico de caramelos)

· "E "- un literal / (Solidús)

Los cuatro anteriores son opcionales, excepto en otros códigos de formato, en particular "L <...>",
y cuando esté precedido de una letra mayúscula.

· "E "

Algún nombre de entidad HTML no numérico, como "E ", que significa lo mismo que
"é" en HTML - es decir, una e minúscula con un acento agudo (en forma de /).

· "E "

El carácter ASCII / Latin-1 / Unicode con ese número. Un "0x" inicial significa que
número es hexadecimal, como en "E <0x201E>". Un "0" inicial significa que número es octal, como en
"E <075>". De lo contrario número se interpreta en decimal, como en "E <181>".

Tenga en cuenta que es posible que los formateadores de pod más antiguos no reconozcan los escapes numéricos octales o hexadecimales,
y que muchos formateadores no pueden representar de manera confiable caracteres por encima de 255 (algunos
los formateadores pueden incluso tener que usar representaciones comprometidas de Latin-1 / CP-1252
caracteres, como renderizar "E "como una simple" e ".)

"F "- utilizado para nombres de archivo
Normalmente se muestra en cursiva. Ejemplo: "" F <.cshrc> ""

"S ": el texto contiene espacios que no se separan
Esto significa que las palabras en texto no debe dividirse entre líneas. Ejemplo:
"S <$ x? $ Y: $ z>".

"X "- una entrada de índice
La mayoría de los formateadores ignoran esto, pero algunos pueden usarlo para crear índices. Eso
siempre se representa como una cadena vacía. Ejemplo: "X "

"Z <>": un código de formato nulo (efecto cero)
Rara vez se utiliza. Es una forma de moverse usando un código E <...> a veces. Para
ejemplo, en lugar de "" NE 3 "" (para "N <3") podría escribir "" NZ <> <3 "" (la "Z <>"
divide la "N" y la "<" para que no se consideren parte de un (ficticio)
Código "N <...>").

La mayoría de las veces, solo necesitará un conjunto de corchetes angulares para delimitar la
principio y fin de los códigos de formato. Sin embargo, a veces querrá poner una
corchete de ángulo recto (un signo mayor que, '>') dentro de un código de formato. Este es
particularmente común cuando se usa un código de formato para proporcionar un tipo de fuente diferente para un
fragmento de código. Como ocurre con todas las cosas en Perl, hay más de una forma de hacerlo. Uno
La forma es simplemente escapar del corchete de cierre usando un código "E":

C <$ a E = E $ b>

Esto producirá: "" $ a <=> $ b ""

Una forma más legible y quizás más "sencilla" es utilizar un conjunto alternativo de delimitadores
que no requiere un solo ">" para escapar. Corchetes angulares dobles ("<<" y ">>")
puede ser usado if y only if there is espacio en blanco Derecho después el apertura delimitador y
espacio en blanco Derecho antes el cierre delimitador! Por ejemplo, lo siguiente hará el
truco:

C << $ a <=> $ b >>

De hecho, puede utilizar tantos paréntesis angulares repetidos como desee siempre que tenga la
el mismo número de ellos en los delimitadores de apertura y cierre, y asegúrese de que los espacios en blanco
sigue inmediatamente al último '<' del delimitador de apertura, e inmediatamente precede al
primero '>' del delimitador de cierre. (El espacio en blanco se ignora). Por lo tanto, lo siguiente
Además trabajo:

C <<< $ a <=> $ b >>>
C <<<< $ a <=> $ b >>>>

Y todos significan exactamente lo mismo que esto:

C <$ a E = E $ b>

La forma de paréntesis múltiples no afecta la interpretación del contenido de la
código de formato, solo cómo debe terminar. Eso significa que los ejemplos anteriores también son
exactamente lo mismo que esto:

C << $ a E = E $ b >>

Como ejemplo adicional, esto significa que si desea poner estos bits de código en "C"
(código) estilo:

abierto (X, ">> cosa.dat") || muere $!
$ foo-> bar ();

podrías hacerlo así:

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

que presumiblemente es más fácil de leer que la forma anterior:

C mi thing.dat ") || muere $!>
C <$ foo-E barra ();>

Actualmente, esto es compatible con pod2text (Pod :: Text), pod2man (Pod :: Man) y cualquier otro
pod2xxx o Pod :: Xxxx traductores que usan Pod :: Parser 1.093 o posterior, o Pod :: Tree 1.02 o
más tarde.

La característica Intención
La intención es la simplicidad de uso, no el poder de expresión. Los párrafos parecen párrafos
(formato de bloque), para que se destaquen visualmente y para que pueda ejecutarlos
"fmt" para reformatearlos fácilmente (eso es F7 en mi versión de vi, o Esc Q en mi versión de
emacs). Quería que el traductor dejara siempre las comillas "'", "" "y" "" solas, en
modo literal, para poder sorber en un programa de trabajo, cambiarlo en cuatro espacios y tener
se imprime, er, palabra por palabra. Y presumiblemente en una fuente monoespaciada.

El formato Pod no es necesariamente suficiente para escribir un libro. Pod está destinado a ser
una fuente común a prueba de idiotas para nroff, HTML, TeX y otros lenguajes de marcado, como se usa para
documentación en línea. Existen traductores para pod2texto, pod2html, pod2man (eso es para
nroff(1) y troff(1)), pod2latex y pod2fm. Varios otros están disponibles en CPAN.

Incrustar Vainas in Perl Módulos
Puede incrustar la documentación de Pod en sus módulos y scripts de Perl. Comienza tu
documentación con una línea vacía, un comando "= head1" al principio y finalice con un
comando "= cortar" y una línea vacía. los perl ejecutable ignorará el texto del Pod. Usted puede
colocar una declaración de Pod donde perl espera el comienzo de una nueva declaración, pero no dentro de
una declaración, ya que daría lugar a un error. Vea cualquiera de los módulos de biblioteca suministrados
por ejemplo.

Si va a colocar su Pod al final del archivo y está usando un "__END__" o
Marca de corte "__DATA__", asegúrese de poner una línea vacía allí antes del primer comando de Pod.

__FIN__

= head1 NAME

Hora :: Local: calcula de manera eficiente la hora a partir de la hora local y GMT

Sin esa línea vacía antes de "= head1", muchos traductores no hubieran reconocido la
"= head1" como inicio de un bloque de Pod.

Sugerencias para Escritura Vaina
·

La característica verificador de cápsulas El comando se proporciona para verificar la sintaxis del Pod en busca de errores y advertencias.
Por ejemplo, comprueba si hay líneas completamente en blanco en los bloques de pod y si hay líneas desconocidas.
comandos y códigos de formato. También debe pasar su documento a través de una
o más traductores y revise el resultado, o imprima el resultado y corrija
ese. Algunos de los problemas encontrados pueden ser errores en los traductores, que puede o puede
no deseo trabajar alrededor.

· Si está más familiarizado con la escritura en HTML que con la escritura en Pod, puede intentar
su mano para escribir documentación en HTML simple y convertirla a Pod con el
módulo experimental Pod :: HTML2Pod, (disponible en CPAN), y mirando el resultado
código. El módulo experimental Pod :: PXML en CPAN también podría ser útil.

· Muchos traductores de Pod más antiguos requieren las líneas antes de cada comando de Pod y después de cada
El comando Pod (incluido "= cortar"!) Para que sea una línea en blanco. Tener algo como esto:

# - - - - - - - - - - - - -
= artículo $ petardo-> boom ()

Esto detona ruidosamente el objeto petardo.
= cortar
boom secundario {
...

... hará que esos traductores de Pod no vean por completo el bloque de Pod.

En su lugar, hágalo así:

# - - - - - - - - - - - - -

= artículo $ petardo-> boom ()

Esto detona ruidosamente el objeto petardo.

= cortar

boom secundario {
...

· Algunos traductores de Pod más antiguos requieren párrafos (incluidos párrafos de comando como
"= head2 Functions") para ser separados por completamente líneas vacías. Si tienes un
línea aparentemente vacía con algunos espacios, esto podría no contar como un separador para
esos traductores, y eso podría causar un formato extraño.

· Los traductores más antiguos pueden agregar palabras alrededor de un enlace L <>, de modo que "L " mayo
convertirse en "la página de manual de Foo :: Bar", por ejemplo. Así que no deberías escribir cosas como "el
L documentación ", si desea que el documento traducido se lea con sensatez. En su lugar,
escribe "la L documentación "o" L
documentation | Foo :: Bar> ", para controlar cómo sale el enlace.

· Pasar la columna 70 en un bloque textual puede ser descortésmente envuelto por algunos
formateadores.

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