File: README

package info (click to toggle)
libpod-pom-view-restructured-perl 1.000003-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 188 kB
  • sloc: perl: 668; makefile: 2
file content (169 lines) | stat: -rw-r--r-- 6,350 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
NAME
    Pod::POM::View::Restructured - View for Pod::POM that outputs
    reStructuredText

SYNOPSIS
     use Pod::POM::View::Restructured;
     
     my $view = Pod::POM::View::Restructured->new;
     my $parser = Pod::POM->new;
     my $pom = $parser->parse_file("$top_dir/lib/Pod/POM/View/Restructured.pm");
     my $out = $pom->present($view);

DESCRIPTION
    This module outputs reStructuredText that is expected to be used with
    Sphinx. Verbatim sections (indented paragraphs) in the POD will be
    output with syntax highlighting for Perl code by default. See "POD
    commands specifically for reStructuredText" for how to change this for a
    particular block.

    This module can be downloaded from
    <https://metacpan.org/release/Pod-POM-View-Restructured>.

METHODS
  "new(\%params)"
    Constructor. \%params is optional. If present, the following keys are
    valid:

    "callbacks"
        See documentation below for "convert_file()".

    "namespace"
        If a namespace is declared then links to that namespace are
        converted to cross references and an anchor is added for each head
        tag.

  "convert_file($source_file, $title, $dest_file, $callbacks)"
    Converts the POD in $source_file to reStructuredText. If $dest_file is
    defined, it writes the output there. If $title is defined, it is used
    for the title of the document. Otherwise, an attempt is made to infer
    the title from the NAME section (checks if the body looks like
    "/\A\s*(\w+(?:::\w+)+)\s+-\s+/s").

    Returns the output as a string.

    $source_file and $dest_file can be either file names or file handles.

  "convert_files($file_spec, $index_file, $index_title, $out_dir)"
    Converts the files given in $file_spec to reStructuredText. If
    $index_file is provided, it is the path to the index file to be created
    (with a table of contents pointing to all of the files created). If
    $index_title is provided, it is used as the section title for the index
    file. $out_dir is the directory the generated files will be written to.

    $file_spec is a reference to an array of hashes specifying attributes
    for each file to be converted. The valid keys are:

    "source_file"
        File to convert.

    "dest_file"
        File to output the reStructuredText. If not provided, a file name
        will be generated based on the title.

    "title"
        Section title for the generated reStructuredText. If not provided,
        an attempt will be made to infer the title from the NAME section in
        the POD, if it exists. As a last resort, a title will be generated
        that looks like "section_(\d+)".

    "callbacks"
        A reference to a hash containing names and the corresponding
        callbacks.

        Currently the only valid callback is "link". It is given the text
        inside a L<> section from the POD, and is expected to return a tuple
        "($url, $label)". If the value returned for $label is undefined, the
        value of $url is used as the label.

    "no_toc"
        Causes the item to not be printed to the index or return in the
        "toc" field.

    This method returns a hash ref with a table of contents (the "toc"
    field) suitable for a reStructuredText table of contents.

    E.g.,

     my $conv = Pod::POM::View::Restructured->new;
     
     my $files = [
                  { source_file => "$base_dir/Restructured.pm" },
                  { source_file => "$base_dir/DWIW.pm" },
                  { source_file => "$base_dir/Wrapper.pm" },
                 ];
     
     my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir);

POD commands specifically for reStructuredText
    The following sequences can be used in POD to request actions
    specifically for this module.

  =for pod2rst next-code-block: *lang*
    This sets up the next verbatim section, i.e., the next indented
    paragraph to be highlighted according to the syntax of the
    programming/markup/config language *lang*. Verbatim sections are assumed
    to be Perl code by default. Sphinx uses Pygments to do syntax highlighting
    in these sections, so you can use any value for *lang* that Pygments
    supports, e.g., Python, C, C++, Javascript, SQL, etc.

EXAMPLES
    Converting a single file using "pod2rst"
         pod2rst --infile=Restructured.pm --outfile=restructured.rst

    Need to document:

    Document example of setting up sphinx build, generating rst from pod,
    and building

TODO
    code highlighting
        Currently, a verbatim block (indented paragraph) gets output as a
        Perl code block by default in reStructuredText. There should be an
        option (e.g., in the constructor) to change the language for
        highlighting purposes (for all verbatim blocks), or disable syntax
        highlighting and just make it a preformatted paragraph. There is a way
        to do this in POD (see "POD commands specifically for
        reStructuredText"), but there should also be an option in the
        constructor.

    improve escaping
        Text blocks are not escaped properly, so it is currently possible to
        invoke a command in reStructuredText by accident.

DEPENDENCIES
    Inherits from Pod::POM::View::Text that comes with the Pod::POM
    distribution.

AUTHORS
    Don Owens <don@regexguy.com>
    Jeff Fearn <Jeff.Fearn@gmail.com>
    Alex Muntada <alexm@cpan.org>

LICENSE AND COPYRIGHT
    Copyright (c) 2010 Don Owens <don@regexguy.com>. All rights reserved.
    Copyright (c) 2016 Jeff Fearn <Jeff.Fearn@gmail.com>. All rights
    reserved.
    Copyright (c) 2016-2021 Alex Muntada <alexm@cpan.org>. All rights
    reserved.

    This is free software; you can redistribute it and/or modify it under
    the same terms as Perl itself. See perlartistic.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
    Pod::POM

    Pod::POM::View::HTML

    pod2rst (distributed with Pod::POM::View::HTML)

    reStructuredText: <http://docutils.sourceforge.net/rst.html>

    Sphinx (uses reStructuredText): <https://www.sphinx-doc.org/>

    Pygments (used by Sphinx for syntax highlighting):
    <https://pygments.org/>