.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\" ========================================================================
.\"
.IX Title "Pod::POM::View::Restructured 3pm"
.TH Pod::POM::View::Restructured 3pm "2017-01-26" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::POM::View::Restructured \- View for Pod::POM that outputs reStructuredText
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module outputs reStructuredText that is expected to be used
with Sphinx. Verbatim sections (indented paragraphs) in the \s-1POD\s0
will be output with syntax highlighting for Perl code by default.
See \*(L"\s-1POD\s0 commands specifically for reStructuredText\*(R" for how
to change this for a particular block.
.PP
For a list of changes in recent versions, see the documentation
for Pod::POM::View::Restructured::Changes.
.PP
This module can be downloaded from .
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """new(\e%params)"""
.el .SS "\f(CWnew(\e%params)\fP"
.IX Subsection "new(%params)"
Constructor. \e%params is optional. If present, the following keys are valid:
.ie n .IP """callbacks""" 4
.el .IP "\f(CWcallbacks\fR" 4
.IX Item "callbacks"
See documentation below for \f(CW\*(C`convert_file()\*(C'\fR.
.ie n .IP """namespace""" 4
.el .IP "\f(CWnamespace\fR" 4
.IX Item "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.
.ie n .SS """convert_file($source_file, $title, $dest_file, $callbacks)"""
.el .SS "\f(CWconvert_file($source_file, $title, $dest_file, $callbacks)\fP"
.IX Subsection "convert_file($source_file, $title, $dest_file, $callbacks)"
Converts the \s-1POD\s0 in \f(CW$source_file\fR to reStructuredText. If
\&\f(CW$dest_file\fR is defined, it writes the output there. If
\&\f(CW$title\fR is defined, it is used for the title of the document.
Otherwise, an attempt is made to infer the title from the \s-1NAME\s0
section (checks if the body looks like \f(CW\*(C`/\eA\es*(\ew+(?:::\ew+)+)\es+\-\es+/s\*(C'\fR).
.PP
Returns the output as a string.
.PP
\&\f(CW$source_file\fR and \f(CW$dest_file\fR can be either file names or file
handles.
.ie n .SS """convert_files($file_spec, $index_file, $index_title, $out_dir)"""
.el .SS "\f(CWconvert_files($file_spec, $index_file, $index_title, $out_dir)\fP"
.IX Subsection "convert_files($file_spec, $index_file, $index_title, $out_dir)"
Converts the files given in \f(CW$file_spec\fR to reStructuredText.
If \f(CW$index_file\fR 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 \f(CW$index_title\fR is provided, it is used as
the section title for the index file. \f(CW$out_dir\fR is the
directory the generated files will be written to.
.PP
\&\f(CW$file_spec\fR is a reference to an array of hashes specifying
attributes for each file to be converted. The valid keys are:
.ie n .IP """source_file""" 4
.el .IP "\f(CWsource_file\fR" 4
.IX Item "source_file"
File to convert.
.ie n .IP """dest_file""" 4
.el .IP "\f(CWdest_file\fR" 4
.IX Item "dest_file"
File to output the reStructuredText. If not provided, a file
name will be generated based on the title.
.ie n .IP """title""" 4
.el .IP "\f(CWtitle\fR" 4
.IX Item "title"
Section title for the generated reStructuredText. If not
provided, an attempt will be made to infer the title from the
\&\s-1NAME\s0 section in the \s-1POD,\s0 if it exists. As a last resort, a title
will be generated that looks like \*(L"section_(\ed+)\*(R".
.ie n .IP """callbacks""" 4
.el .IP "\f(CWcallbacks\fR" 4
.IX Item "callbacks"
A reference to a hash containing names and the corresponding callbacks.
.Sp
Currently the only valid callback is \f(CW\*(C`link\*(C'\fR. It is given the
text inside a L<> section from the \s-1POD,\s0 and is expected to return a
tuple \f(CW\*(C`($url, $label)\*(C'\fR. If the value returned for \f(CW$label\fR is
undefined, the value of \f(CW$url\fR is used as the label.
.ie n .IP """no_toc""" 4
.el .IP "\f(CWno_toc\fR" 4
.IX Item "no_toc"
Causes the item to not be printed to the index or return in the \f(CW\*(C`toc\*(C'\fR field.
.PP
This method returns a hash ref with a table of contents (the
\&\f(CW\*(C`toc\*(C'\fR field) suitable for a reStructuredText table of contents.
.PP
E.g.,
.PP
.Vb 1
\& 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", \*(AqMy Big Test\*(Aq, $dest_dir);
.Ve
.SH "POD commands specifically for reStructuredText"
.IX Header "POD commands specifically for reStructuredText"
The following sequences can be used in \s-1POD\s0 to request actions specifically for this module.
.SS "=for pod2rst next-code-block: \fIlang\fP"
.IX Subsection "=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 \fIlang\fR. 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 \fIlang\fR that Pygments supports, e.g., Python, C, \*(C+,
Javascript, \s-1SQL,\s0 etc.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.ie n .IP "Converting a single file using ""pod2rst""" 4
.el .IP "Converting a single file using \f(CWpod2rst\fR" 4
.IX Item "Converting a single file using pod2rst"
.Vb 1
\& pod2rst \-\-infile=Restructured.pm \-\-outfile=restructured.rst
.Ve
.PP
\&\fBNeed to document:\fR
.IP "\fBDocument example of setting up sphinx build, generating rst from pod, and building\fR" 4
.IX Item "Document example of setting up sphinx build, generating rst from pod, and building"
.SH "TODO"
.IX Header "TODO"
.PD 0
.IP "code highlighting" 4
.IX Item "code highlighting"
.PD
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 \s-1POD \s0(see \*(L"\s-1POD\s0 commands specifically for reStructuredText\*(R"),
but there should also be an option in the constructor.
.IP "improve escaping" 4
.IX Item "improve escaping"
Text blocks are not escaped properly, so it is currently possible
to invoke a command in reStructuredText by accident.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Inherits from Pod::POM::View::Text that comes with the Pod::POM distribution.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "Don Owens " 4
.IX Item "Don Owens "
.PD 0
.IP "Jeff Fearn " 4
.IX Item "Jeff Fearn "
.PD
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2010 Don Owens . All rights reserved.
Copyright (c) 2016 Jeff Fearn . All rights reserved.
.PP
This is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
.PP
This program is distributed in the hope that it will be
useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied
warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR
PURPOSE.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::POM
.PP
Pod::POM::View::HTML
.PP
pod2rst (distributed with Pod::POM::View::HTML)
.PP
reStructuredText:
.PP
Sphinx (uses reStructuredText):
.PP
Pygments (used by Sphinx for syntax highlighting):
.SH "VERSION"
.IX Header "VERSION"
0.03