/ 
Pod2VMSHlp-1.02
River stage zero No dependents
/ pod2rno

NAME

pod2rno - Convert POD data to formatted DSR input

SYNOPSIS

pod2rno [--layout=string] [--chapter=number] [--section=manext] [--release=version] [--center=string] [--date=string] [--official] [--lax] [--quotes=quotes] [input [output] ...]

pod2rno --help

DESCRIPTION

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.

OPTIONS

-l string, --layout=string

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

-c chapter_number, --chapter=chapeter_number

Inserts a .CHAPTER chapter number command into the document after the .TITLE.

--center=string

Sets the centered page header to string. The default is "User Contributed Perl Documentation", but also see --official below.

-d string, --date=string

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.

-h, --help

Print out usage information.

--lax

Don't complain when required sections are missing. Not currently used, as POD checking functionality is not yet implemented in Pod::Dsr (See podchecker).

-o, --official

Set the default header to indicate that this page is part of the standard Perl release, if --center is not also given.

-q quotes, --quotes=quotes

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.

-r, --release

Set the centered footer. By default, this is the version of Perl you run pod2rno under.

-s, --section

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.

DIAGNOSTICS

If pod2rno fails with errors, see Pod::Dsr and Pod::Parser for information about what those errors might mean.

EXAMPLES

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.

BUGS

Lots of this documentation is duplicated from Pod::Dsr.

POD checking and the corresponding --lax option don't work yet.

SEE ALSO

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.

AUTHOR

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.