pod2rno - Convert POD data to formatted DSR input
pod2rno [--layout=string] [--chapter=number] [--section=manext] [--release=version] [--center=string] [--date=string] [--official] [--lax] [--quotes=quotes] [input [output] ...]
pod2rno --help
pod2rno is a front-end for Pod::Dsr, using it to generate DSR .RNO input from POD source. The resulting DSR code is suitable for use with the RUNOFF command.
input is the file to read for POD source (the POD can be embedded in code). If input isn't given, it defaults to STDIN. output, if given, is the file to which to write the formatted output. If output isn't given, the formatted output is written to STDOUT. Several POD files can be processed in the same pod2rno invocation (saving module load and compile times) by providing multiple pairs of input and output files on the command line.
--section, --release, --center, --date, --layout, and --official can be used to set the headers and footers to use; if not given, Pod::Dsr will assume various defaults. See below or Pod::Dsr for details.
Besides the obvious pod conversions, Pod::Dsr, and therefore pod2rno also takes care of formatting func(), func(n), and simple variable references like $foo or @bar so you don't have to use code escapes for them; complex expressions like $fred{'stuff'} will still need to be escaped, though. It takes care of several other runoff-specific tweaks. See Pod::Dsr for complete information.
$fred{'stuff'}
Inserts the given string at the head of the dsr document, typically used to set the .LAYOUT style. The default is .LAYOUT 0, but could be given as .LAYOUT n1[,n2], where n1 can be any of qw(0 1 2 3), if n1 > 0 then n2 can specify the number of lines below the last line of text on a page where the page number will appear. E.g. -l ".LAYOUT 1,2" or --layout=".LAYOUT 2,2".
.LAYOUT 0
.LAYOUT
-l ".LAYOUT 1,2"
--layout=".LAYOUT 2,2"
Inserts a .CHAPTER chapter number command into the document after the .TITLE.
.CHAPTER
Sets the centered page header to string. The default is "User Contributed Perl Documentation", but also see --official below.
Set the left-hand footer string to this value. By default, the modification date of the input file will be used, or the current date if input comes from STDIN.
Print out usage information.
Don't complain when required sections are missing. Not currently used, as POD checking functionality is not yet implemented in Pod::Dsr (See podchecker).
Set the default header to indicate that this page is part of the standard Perl release, if --center is not also given.
Sets the quote marks used to surround < text to quotes. If quotes is a single character, it is used as both the left and right quote; if quotes is two characters, the first character is used as the left quote and the second as the right quoted; and if quotes is four characters, the first two are used as the left quote and the second two as the right quote. quotes may also be set to the special value none, in which case no quote marks are added around < text.
<
none
Set the centered footer. By default, this is the version of Perl you run pod2rno under.
Set the section for the .HEADER_LEVEL command. The standard section numbering convention is to use 1 for user commands, 2 for system calls, 3 for functions, 4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous information, and 8 for administrator commands. There is a lot of variation here, however; some systems (like Solaris) use 4 for file formats, 5 for miscellaneous information, and 7 for devices. Still others use 1m instead of 8, or some mix of both. About the only section numbers that are reliably consistent are 1, 2, and 3. By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected.
.HEADER_LEVEL
If pod2rno fails with errors, see Pod::Dsr and Pod::Parser for information about what those errors might mean.
pod2rno program > program.rno runoff program pod2rno SomeModule.pm > PERL_ROOT:[LIB.POD]SomeModule.rno runoff PERL_ROOT:[LIB.POD]SomeModule.rno
You may then TYPE or PRINT out the resulting .MEM file.
If you would like to print out a lot of pod pages continuously, you probably want to use the pod2mem utility instead of pod2rno (pod2mem has yet to be written though :-).
Index entries are inserted for every =head\d directive as well as for each list element. To obtain a PRINT able or TYPE able index file run runoff with the /INTERMEDIATE qualifier then the /INDEX qualifier, as in:
runoff /intermediate program.rno runoff /index program.brn runoff program.rnx
after which you may TYPE or PRINT both the program.mem file as well as the program.mex file which holds the formatted index.
A table of contents may also be generated with the /CONTENTS qualifier to RUNOFF like so:
runoff /intermediate program.rno runoff /contents program.brn runoff program.rnt
after which you may TYPE or PRINT both the program.mem file as well as the program.mec file which holds the formatted table of contents.
Lots of this documentation is duplicated from Pod::Dsr.
POD checking and the corresponding --lax option don't work yet.
Pod::Dsr, Pod::Man, Pod::Parser, HELP RUNOFF. HELP DSR.
For additional information that may be more accurate for your specific system, see either HELP RUNOFF or HELP DSR. See also the README.runoff file that comes with the Pod2VMSHlp distribution.
The pod markup for Pod::Man and pod2man have information on typical sections to include in manual page documents.
Peter Prymmer pvhp@best.com, based on pod2man by Russ Allbery which was in turn based on the original pod2man by Larry Wall and Tom Christiansen. Large portions of this documentation, particularly the sections on the anatomy of a proper man page, are taken from the pod2man documentation by Tom.
To install Pod::Hlp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Hlp
CPAN shell
perl -MCPAN -e shell install Pod::Hlp
For more information on module installation, please visit the detailed CPAN module installation guide.