The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Pod-Parser-Groffmom-0.042
River stage zero No dependents
++
/ Pod::Parser::Groffmom

NAME

Pod::Parser::Groffmom - Convert POD to a format groff_mom can handle.

VERSION

Version 0.042

SYNOPSIS

    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.

If you prefer, read perldoc pod2mom for an easier interface.

DESCRIPTION

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.

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.

The "mom" documentation is not needed to use this module, but it would be needed if you wish to hack on it.

CONSTRUCTOR

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_toc (creates a table of contents)

ALPHA CODE

This is alpha code. There's not much control over it yet and there are plenty of POD corner cases it doesn't handle.

MOM COMMANDS

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.

  • 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.

  • 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.

  • 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.

  • 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".

    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>
 &#61;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

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".

LIMITATIONS

Probably plenty.

  • We don't yet handle numbered lists well (they always start with '1')

  • List indent level (=over 4) ignored.

  • Syntax highlighting is experimental.

  • No support for hyperlinks.

  • No =head4 or below are supported.

  • 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.

AUTHOR

Curtis "Ovid" Poe, <ovid at cpan.org>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Pod::Parser::Groffmom

You can also look for information at:

REPOSITORY

The latest version of this module can be found at http://github.com/Ovid/Pod-Parser-GroffMom.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.