¿Cómo hacer que el archivo README de mi módulo Perl sea compatible con la pantalla Markdown de Github?

perl-module

Question

He creado el archivo README en mi módulo Perl en Markdown. Github trata este archivo README como texto plano. Intenté cambiar el nombre del archivo a "README.md", que se ve muy bien en Github, pero es invisible para las herramientas de Perl que buscan un archivo llamado "README".

¿Hay alguna manera de que pueda tener un archivo README y que Github interprete correctamente mi formato de Markdown?

La única opción que se me ocurrió fue tener tanto un README como un README.md, pero preferiría no tener que mantener los dos archivos sincronizados manualmente.

Gracias por tu ayuda.

Answer 1

La única opción que se me ocurrió fue tener tanto un README como un README.md, pero preferiría no tener que mantener los dos archivos sincronizados manualmente.

¿Entonces automáticamente los mantiene sincronizados?

Answer 2

¡Formatea tu README en el pod, renómbrelo como README.pod y luego works ambos lugares! Example

Para mis propósitos, en realidad solo genero mi README.pod desde el pod principal haciendo

$ podselect lib/My/Main/Module.pm > README.pod

Una advertencia, los enlaces externos nombrados no funcionan correctamente L<GitHub|http://github.com> desafortunadamente apuntará a search.cpan.org en busca de un módulo de GitHub. He tratado de informarles de este error pero no me ha llevado a ninguna parte. En su lugar, solo puede utilizar enlaces externos simples (es decir, GitHub: L<http://github.com> ) y funcionan bien.

¡Buenas noticias, parece que lo han solucionado desde la última vez que lo comprobé!

Solo una pregunta, ¿qué partes de la cadena de herramientas de Perl esperan un archivo README? Si te refieres a incluirlo en tu archivo comprimido, solo asegúrate de agregar el archivo a tu MANIFESTAR y este se incluirá.

Answer 3

¿Has oído hablar de POD ? Esta es la herramienta de documentación estándar en Perl. POD es un formato de documentación de texto simple que realmente reside en su código. Uno de los comandos que vienen con perl es perldoc . Puedes usarlo para obtener la información de cualquier comando de Perl. Prueba estos:

$ perldoc File::Find
$ perldoc -f split

Todos los módulos Perl en CPAN deben incorporar la documentación POD. De hecho, así es como se construyen las páginas web de CPAN.

Entonces, ¿a dónde voy con esto y cómo te va a ayudar esto?

Debe incluir la documentación POD en su programa Perl. Luego, puede usar el comando pod2text para crear su README para su programa Perl:

$ pod2text myperl.pl > README

Eso maneja la mitad de tu problema.

La otra mitad es un poco más complicada. Debe instalar desde CPAN el Pod::Markdown en su sistema. Luego, puede ejecutar el comando pod2markdown que viene con este módulo para crear la versión de reducción de su archivo:

$ pod2markdown myperl.pl > README.md

Los resultados:

• Su documentación vive, como debería, en su programa Perl.
• Los usuarios pueden usar el programa perldoc para imprimir la documentación completa de su programa.
• Puede usar la herramienta pod2text para crear su archivo README .
• Puede usar la herramienta pod2markdown para crear su archivo README.md .
• Como beneficio adicional, puede usar el módulo Pod::Usage que viene con Perl para mostrar la documentación de POD (o partes de ella) como texto de ayuda que se muestra cuando un usuario ejecuta su programa con el parámetro -help .

Entonces, un lugar donde vive su documentación, y está utilizando un par de programas de ayuda para crear los archivos que Github y las herramientas Perl que necesite.

Answer 4

Estaba buscando una solución para este problema y decidí usar Dist::Zilla::Plugin::ReadmeAnyFromPod ya que comprende las etiquetas =attr y =method de Pod :: Weaver.

Answer 5

Otra solución si realmente quiere distribuir su módulo con un README Markdown, que no implique a Pod es:

• renombra tu archivo README a README.md
• actualizar el cambio anterior en el archivo MANIFEST

Creo que puede ser una solución interesante porque más personas conocen la sintaxis de Markdown que Pod uno. Como el objetivo del archivo README es para que lo lea cualquier persona, Markdown debe considerarse.

Answer 6

Si no te importa usar Dist::Zilla , puedes eliminar el mantenimiento de un README por completo. Por ejemplo, Dist::Zilla::Plugin::ReadmeFromPod puede crear su archivo README extrayendo el Pod de su módulo principal. Esto significa nunca tener que escribir un README de nuevo.

Nunca lo he intentado yo mismo, pero puedes ver algo como Dist::Zilla::Plugin::ReadmeMarkdownFromPod para crear tu README automáticamente en markdown.

Puede que esta no sea la respuesta exacta que está buscando, pero creo que usar este tipo de herramienta puede ahorrarle mucho tiempo, ya que le permite evitar repetirse en su documentación.