Pod::Parser::Groffmom - Convert POD to a format groff_mom can handle.
Version 0.042
use Pod::Parser::Groffmom; my $foo = Pod::Parser::Groffmom->new(); my $file = 't/test_pod.pod'; open my $fh, '<', $file or die "Cannot open ($file) for reading: $!"; $parser->parse_from_filehandle($fh); print $parser->mom;
If you have printed the "mom" output to file named 'my.mom', you can then do this:
groff -mom my.mom > my.ps
And you will have a postscript file suitable for opening in gv, Apple's Preview.app or anything else which can read postscript files.
gv
Preview.app
If you prefer, read perldoc pod2mom for an easier interface.
perldoc pod2mom
This subclass of Pod::Parser will take a POD file and produce "mom" output. See http://linuxgazette.net/107/schaffter.html for a gentle introduction.
Pod::Parser
If you have groff on your system, it should have docs for "momdoc". Otherwise, you can read them at http://www.opensource.apple.com/source/groff/groff-28/groff/contrib/mom/momdoc/toc.html?f=text.
groff
The "mom" documentation is not needed to use this module, but it would be needed if you wish to hack on it.
The following arguments may be supplied to the constructor and override any values found in the POD document.
mom_title
mom_subtitle
mom_author
mom_copyright
mom_cover (creates a cover page)
mom_cover
mom_toc (creates a table of contents)
mom_toc
This is alpha code. There's not much control over it yet and there are plenty of POD corner cases it doesn't handle.
Most POD files will convert directly to "mom" output. However, when you view the result, you might want more control over it. The following is how MOM directives are handled. They may begin with either '=head1' or =head2'. It doesn't matter (this might change later).
Some commands which should alter mom behavior but not show up in the POD begin with =for.
=for
NAME
=head1 NAME This is the title of the pod.
Whatever follows "NAME" will be the title of your document.
TITLE
=head1 TITLE This is the title of the pod.
Synonymous with 'NAME'. You may only have one title for a document.
SUBTITLE
=head1 SUBTITLE This is the subtitle of the pod.
AUTHOR
=head1 AUTHOR Curtis "Ovid" Poe
This is the author of your document.
COPYRIGHT
=head1 COPYRIGHT 2009, Curtis "Ovid" Poe
This will be the copyright statement on your pod. Will only appear in the document if the =head1 COVER command is given.
=head1 COVER
cover
=for mom cover
Does not require any text after it. This is merely a boolean command telling Pod::Parser::Groffmom to create a cover page.
Pod::Parser::Groffmom
newpage
=for mom newpage
Does not require any text after it. This is merely a boolean command telling Pod::Parser::Groffmom to create page break here.
toc
=for mom toc
Does not require any text after it. This is merely a boolean command telling Pod::Parser::Groffmom to create a table of contents. Due to limitations in with groff -mom, the table of contents will be the final page of the document.
groff -mom
begin highlight
=begin highlight Perl sub add { my ( $self, $data ) = @_; my $add = $self->in_list_mode ? 'add_to_list' : 'add_to_mom'; $self->$add($data); } =end highlight
This turns on syntax highlighting. Allowable highlight types are the types allowed for Syntax::Highlight::Engine::Kate. We default to Perl, so the above can be written as:
=begin highlight sub add { my ( $self, $data ) = @_; my $add = $self->in_list_mode ? 'add_to_list' : 'add_to_mom'; $self->$add($data); } =end highlight
For a list of allowable names for syntax highlighting, see Pod::Parser::Groffmom::Color.
for mom tofile $filename
This command tells Pod::Parser::Groffmom that you're going to send some output to a file. Must have a filename with it.
begin mom tofile
Sometimes you want to include data in your pod and have it written out to a separate file. This is useful, for example, if you're writing the POD for beautiful documentation for a talk, but you want to embed slides for your talk.
=begin mom tofile <h1>Some Header</h1> <h2>Another header</h2> =end mom tofile
Any paragraph or verbatim text included between these tokens are automatically sent to the $filename specified in =for mom tofile $filename. The file is opened in append mode, so any text found will be added to what is already there. The text is passed "as is".
$filename
=for mom tofile $filename
If you must pass pod, the leading '=' sign will cause this text to be handled by Pod::Parser::Groffmom instead of being passed to your file. Thus, any leading '=' must be escaped in the format you need it in:
=for mom tofile tmp/some.html ... perhaps lots of pod ... =begin mom tofile <p>To specify a header in POD:</p> <pre><tt> =head1 SOME HEADER </tt></pre> =end mom tofile
Of course, if the line is indented, it's considered "verbatim" text and will be not be processed as a POD command:
=begin mom tofile <p>To specify a header in POD:</p> <pre><tt> =head1 SOME HEADER </tt></pre> =end mom tofile
Special characters are often encountered in POD:
Salvador FandiE<ntilde>o
To see the list of named characters we support, check Pod::Parser::Groffmom::Entities. If the character you need is not on that list, you may still enter its numeric value. The above name could also be written as:
Salvador FandiE<241>o
And should be rendered as "Salvador Fandiño".
Probably plenty.
We don't yet handle numbered lists well (they always start with '1')
List indent level (=over 4) ignored.
=over 4
Syntax highlighting is experimental.
No support for hyperlinks.
No =head4 or below are supported.
=head4
Table of contents are generated at the end. This is a limitation of mom.
The "pod2mom" in bin script in this distribution will attempt to correct that for you.
=for is ignored except for =for mom tofile $filename.
S<> sequences try to work but they're finicky.
S<>
Curtis "Ovid" Poe, <ovid at cpan.org>
<ovid at cpan.org>
Please report any bugs or feature requests to bug-pod-parser-groffmom at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-Parser-Groffmom. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-pod-parser-groffmom at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Pod::Parser::Groffmom
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-Parser-Groffmom
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Pod-Parser-Groffmom
CPAN Ratings
http://cpanratings.perl.org/d/Pod-Parser-Groffmom
Search CPAN
http://search.cpan.org/dist/Pod-Parser-Groffmom/
The latest version of this module can be found at http://github.com/Ovid/Pod-Parser-GroffMom.
Copyright 2009 Curtis "Ovid" Poe, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Pod::Parser::Groffmom, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Parser::Groffmom
CPAN shell
perl -MCPAN -e shell install Pod::Parser::Groffmom
For more information on module installation, please visit the detailed CPAN module installation guide.