Plain Old Documentation ( pod ) es un lenguaje de marcado ligero que se utiliza para documentar el lenguaje de programación Perl, así como los módulos y programas de Perl.
Pod está diseñado para ser un lenguaje simple y limpio con la sintaxis suficiente para ser útil. Intencionalmente no incluye mecanismos para fuentes, imágenes, colores o tablas. Algunos de sus objetivos son:
O'Reilly & Associates ha utilizado una versión extendida de pod que admite tablas y notas a pie de página llamada PseudoPOD para producir varios libros de Perl, en particular Programación Perl de Larry Wall , Tom Christiansen y Jon Orwant.
Pod facilita la escritura de páginas de manual , que se adaptan bien a documentos orientados al usuario. Por el contrario, otros sistemas de documentación, como Docstring de Python o Javadoc de Java , aunque pueden usarse para documentación de usuario, están diseñados para facilitar la generación de documentación orientada al desarrollador sobre el código fuente de un proyecto de software.
Pod es el lenguaje utilizado para la mayor parte de la documentación en el mundo Perl. Esto incluye el propio Perl, casi todos los módulos publicados públicamente , muchos scripts , la mayoría de los documentos de diseño, muchos artículos en Perl.com y otros sitios web relacionados con Perl, y la máquina virtual Parrot .
Pod rara vez se lee sin formato, aunque está diseñado para poder leerse sin la ayuda de una herramienta de formato. En cambio, se lee con laherramienta perldoc, o convertirlas en páginas man de Unix o páginas HTML estándar web.
También es posible utilizar pod en otros contextos además de Perl. Por ejemplo, para agregar documentación simple a los scripts bash , que luego se pueden convertir fácilmente en páginas man. [1] Dichos usos se basan en trucos específicos del lenguaje para ocultar las partes del pod, como (en bash) anteponer a la sección POD la línea :<<=cutque funciona llamando al comando no-op : de bash , con todo el bloque de Pod como un documento aquí como entrada.
Los archivos pod puros suelen tener la extensión .pod, pero pod se usa principalmente directamente en el código Perl, que normalmente usa las extensiones .ply .pm. (El analizador del intérprete de Perl está diseñado para ignorar el pod en el código Perl). En los archivos de código fuente, la documentación generalmente se coloca después del marcador (lo que también ayuda a resaltar la sintaxis en algunos editores para mostrarla como comentarios).__END__
Pod se puede convertir fácilmente a otros formatos, por ejemplo, algunos de los diversos formatos Wiki como: WikiWikiWeb , Kwiki, TWiki , UseModWiki , TiddlyWiki , Textile , MediaWiki , MoinMoin o Confluence usando Pod::Simple::Wiki.
Este documento es un pod sintácticamente correcto, que también intenta seguir las convenciones principales sobre la denominación de secciones. [2]
=cabeza1 NOMBREMy::Module- Un módulo de ejemplo=cabeza1 SINOPSISuse My::Module;my $object = My::Module->new();print $object->as_string;=cabeza1 DESCRIPCIÓNEste módulo realmente no existe,fue hecho con el único propósito dedemostrando cómo funciona POD.= cabeza2 Métodos=más de 12=elemento C<nuevo>Devuelve un nuevo objeto.My::Module=elemento C<como_cadena>Devuelve una representación en cadena deel objeto. Esto es principalmente para depurar.propósitos.=volver=cabeza1 LICENCIAEsto se publica bajo la Licencia Artística .Ver L<perlartistic>.=cabeza1 AUTORJuerd-L< http://juerd.nl/ >=cabeza1 VER TAMBIÉNL<perlpod>, L<perlpodspec>= cortar
Los archivos Pod están escritos en una codificación compatible con ASCII , como Latin-1 o UTF-8 . Un analizador de pods siempre asume que el archivo que está analizando no comienza con pod; ignora todas las líneas hasta que ve una directiva de pod. Las directivas del pod deben aparecer al principio de una línea y todas comienzan con un signo igual. El analizador de pods asumirá que todas las líneas siguientes son pods, hasta que encuentre una línea que contenga la directiva "=cut". Cualquier contenido siguiente se ignora hasta que el analizador encuentre otra directiva de pod. Por lo tanto, pod se puede mezclar con código fuente ejecutable si el analizador del lenguaje sabe cómo reconocer e ignorar pod.
El contenido del pod se divide en párrafos mediante líneas vacías. Los párrafos que comienzan con espacios en blanco (tabulaciones o espacios) se consideran "párrafos textuales" y se dejan sin formato; estos se utilizan para código de muestra, arte ASCII , etc. Los párrafos que comienzan con un signo igual son "párrafos de comando"; la secuencia de caracteres alfanuméricos que siguen inmediatamente al signo igual se trata como una directiva de pod y el resto del párrafo se formatea de acuerdo con esa directiva. Algunas directivas también afectan a los siguientes apartados. Si un párrafo comienza con algo además de un signo igual o un espacio en blanco, se considera un "párrafo normal".
Tanto los párrafos ordinarios como el contenido de los párrafos de comando se analizan en busca de códigos de formato. El formato en pod es muy sencillo; se limita principalmente a negrita, cursiva, subrayado, monoespaciado y algunos otros formatos. También hay un código para vincular entre documentos del pod o con otra sección dentro del mismo documento. Los códigos de formato constan de:
B<bolded text>, oB<< bolded text >>. Este formulario se utiliza a menudo para fragmentos de código que contienen un signo mayor que, que de otro modo finalizaría el código de formato.Los comandos en el pod incluyen cuatro niveles de encabezados, listas numeradas y con viñetas, y comandos para marcar secciones como en otro idioma. Esta última característica permite dar un formato especial a los analizadores que la admiten.