| 1 |
NAME |
| 2 |
|
| 3 |
Pod::Pandoc - process Plain Old Documentation format with Pandoc |
| 4 |
|
| 5 |
DESCRIPTION |
| 6 |
|
| 7 |
The Plain Old Documentation format (Pod) is a markup language used to |
| 8 |
document Perl code (see perlpod for reference). Several Perl modules |
| 9 |
exist to process and convert Pod into other formats. |
| 10 |
|
| 11 |
Pod::Pandoc is an attempt to unify and extend Pod converting based on |
| 12 |
the Pandoc <http://pandoc.org/> document converter. Pandoc supports |
| 13 |
more document formats in a more detailled and uniform way than any set |
| 14 |
of Perl modules will ever do. For this reason Pod::Pandoc provides |
| 15 |
methods to convert Pod to the Pandoc document model for further |
| 16 |
processing with Pandoc. |
| 17 |
|
| 18 |
OUTLINE |
| 19 |
|
| 20 |
* pod2pandoc is a command line script to convert Pod to any format |
| 21 |
supported by Pandoc. |
| 22 |
|
| 23 |
* App::pod2pandoc provides functionality of pod2pandoc to be used in |
| 24 |
Perl code. |
| 25 |
|
| 26 |
* Pod::Simple::Pandoc converts Pod to the abstract document model of |
| 27 |
Pandoc. |
| 28 |
|
| 29 |
* Pod::Pandoc::Modules manages a set of Pod documents of Perl |
| 30 |
modules. |
| 31 |
|
| 32 |
REQUIREMENTS |
| 33 |
|
| 34 |
Installation of this module does not require Pandoc but it is needed to |
| 35 |
make actual use of it. See http://pandoc.org/installing.html for |
| 36 |
installation. |
| 37 |
|
| 38 |
USAGE EXAMPLES |
| 39 |
|
| 40 |
Replace pod2html |
| 41 |
|
| 42 |
# pod2html --infile=input.pm --css=style.css --title=TITLE > output.html |
| 43 |
pod2pandoc input.pm --css=style.css --toc --name -o output.html |
| 44 |
|
| 45 |
Pandoc option --toc corresponds to pod2html option --index and is |
| 46 |
disabled by default. pod2pandoc adds title and subtitle from NAME |
| 47 |
section. |
| 48 |
|
| 49 |
Replace pod2markdown |
| 50 |
|
| 51 |
# pod2markdown input.pod |
| 52 |
pod2pandoc input.pod -t markdown |
| 53 |
|
| 54 |
# pod2markdown input.pod output.md |
| 55 |
pod2pandoc input.pod -o output.md |
| 56 |
|
| 57 |
GitHub wiki |
| 58 |
|
| 59 |
The GitHub wiki of this project |
| 60 |
<https://github.com/nichtich/Pod-Pandoc/wiki> is automatically |
| 61 |
populated with its module documentation. Wiki pages are created with |
| 62 |
pod2pandoc as following (see script update-wiki.sh): |
| 63 |
|
| 64 |
pod2pandoc lib/ script/ wiki/ --ext md --index Home --wiki -t markdown_github |
| 65 |
|
| 66 |
Sphinx and Read The Docs |
| 67 |
|
| 68 |
The Sphinx documentation generator <https://sphinx-doc.org/> recommends |
| 69 |
documents in reStructureText format. It further requires a |
| 70 |
configuration file conf.py and some links need to be adjusted because |
| 71 |
Pandoc does not support wikilinks in rst output format (see script |
| 72 |
update-docs.sh: |
| 73 |
|
| 74 |
pod2pandoc lib/ script/ docs/ --ext rst --wiki -t rst --standalone |
| 75 |
perl -pi -e 's!`([^`]+) <([^>]+)>`__!-e "docs/$2.rst" ? ":doc:`$1 <$2>`" : "`$1 <$2>`__"!e' docs/*.rst |
| 76 |
make -C docs html |
| 77 |
|
| 78 |
The result is published automatically at |
| 79 |
http://pod-pandoc.rtfd.io/en/latest/Pod-Pandoc.html. |
| 80 |
|
| 81 |
SEE ALSO |
| 82 |
|
| 83 |
This module is based on the wrapper module Pandoc to execute pandoc |
| 84 |
from Perl and on the module Pandoc::Elements for pandoc document |
| 85 |
processing. |
| 86 |
|
| 87 |
This module makes obsolete several specialized Pod::Simple::... modules |
| 88 |
such as Pod::Simple::HTML, Pod::Simple::XHTML, Pod::Simple::LaTeX, |
| 89 |
Pod::Simple::RTF Pod::Simple::Text, Pod::Simple::Wiki, Pod::WordML, |
| 90 |
Pod::Perldoc::ToToc etc. It also covers batch conversion such as |
| 91 |
Pod::Simple::HTMLBatch, Pod::ProjectDocs, Pod::POM::Web, and |
| 92 |
Pod::HtmlTree. |
| 93 |
|
| 94 |
AUTHOR |
| 95 |
|
| 96 |
Jakob Voß <[email protected]> |
| 97 |
|
| 98 |
CONTRIBUTORS |
| 99 |
|
| 100 |
Benct Philip Jonsson |
| 101 |
|
| 102 |
COPYRIGHT AND LICENSE |
| 103 |
|
| 104 |
Copyright 2017- Jakob Voß |
| 105 |
|
| 106 |
GNU General Public License, Version 2 |
| 107 |
|