Debian Codegraph @

README

raw
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