pod2fm - convert pod format to FrameMaker documents and book file
Under UNIX system (where fmbatch can be run):
pod2fm [-mmlonly | -nodoc [-lock] [-book [<book_name>] [-noopen] [-template <document> [-format <types>]...] [-toc [-stoc <suffix>]] [-index [-sindex <suffix>]] ] ] [ -dir <location> | <pod>...]
Under Win32 and Macintosh:
pod2fm [ -dir <location> | <pod>...]
This program parses all files with .pod extension and creates FrameMaker documents. You can control what is generated by arguments given on the command line. On systems where fmbatch is available (i.e.: UNIX systems)
Pod2fm can:
Generate Frame MML, MIF, and binary formats.
Generate hypertext links to a group of documents.
Create a Frame 'book' that includes all of the documents from a run.
Create Table of Contents and Index documents.
Create documents that can be used with FrameViewer for On-Line Docs.
This switch tells pod2fm if it should stop execution after it has generated the 'MML' version of the document. The document is written into a file with the '.mml' extension.
If -mmlonly is specified, it can be the only command line switch.
The default, under UNIX is '-nommlonly'. On Win32 and Macintosh, -mmlonly is always on.
Available only on UNIX systems.
The switch instructs pod2fm to use the FrameMaker tool 'fmbatch' to convert the '.doc' file, which is in MIF format, in to the binary FrameMaker format.
The default is -doc.
Pod2fm generates Hypertext Marker that allow you to click on a marked word in a document and Frame will take you to the spot in a document that the marker is pointing to. To be able to use this feature, you need to save the documents as 'locked' or 'read only'. The -lock option will cause pod2fm to generate 'locked' versions of the documents.
The -lock option only works if you are generating binary documents. (See the -doc option.)
The default is -nolock.
This switch allows pod2fm to create a FrameMaker book file that contains all of the documents that are on the command line. A book is a way to organize a group of related documents so they can operated on at the same time. A book file allows you to apply a common format to all the documents, and print all of them at the same time.
book_name is an optional argument to -book. It allows you to specify a name for the book file. If book_name is not specified, it defaults to 'perl'. In any case, the file name extension is '.book'.
If this option is on the command line, pod2mf will try to open the book it created in FrameMaker. Because this options works on the book file, you must be generating a book with the -book option.
The default is -open.
Pod2fm generates a minimal format for the documents it produces. You can use the -template option to specify a template document that pod2fm can copy the format from so that you can control the format. You can control which format in the template document to use with the -format option. The document name is required argument to -template, and specifies path to the document template.
Use family as the global font. This option has two effects: If the -template option is not used, this font family is set for all paragraphs except pod_pre, which is typeset in Courier. The other usage is for the closing tag of the C<> command.
C<>
The option -format allows you to control which format to copy from the template document specified with the -template option. You can specify one or more arguments to each -format option by giving a comma separated list of format types, like this:
-format Page,Paragraph,Character
You can also have more than one -format option on the command line.
The legal format types are:
all All type are specified (Default). Character Character Formats. Paragraph Paragraph Formats. Page Master Page Layouts. Reference Reference Page Layouts. Table Table Formats. Variables Variable Definitions. Math Math Definitions. Cross Cross-Reference Definitions. Color Color Definitions. Conditional Conditional Text Definitions.
There are two other types that can be included as an argument to control how the other types are used:
Break Preserve Page Breaks Other Preserve Other Format Changes.
When you are generating a book from a template with pod2fm, you can generate a Table of Contents and an Index by specifying the -toc and the -index options. See the "Table of Contents" and "Index" sub-sections in "TEMPLATES" of this man page, for more information.
The defaults are -notoc and -noindex.
The -stoc and -sindex allow for overriding the default suffixes `TOC' and `IDX', respectively.
By default, pod2fm will look for pod files from the standard perl install (the $installprivlib from Config.pm.) You can override this by using the -dir command line option. You can also specify the pods that you want on the command line, but you can't mix the -dir and pods in the same command.
$installprivlib
Config.pm
When specifying individual files, the order is important, i.e. pod2fm searches for items and headers first in the currently processed file and then in the other files, beginning with the first one on the command line. E.g. when converting the perl manual, one should state perlvar.pod, perlfunc.pod and perlrun.pod first, so that the explanations for functions, variables and runtime options are found there and not e.g. in perldelta.pod.
By using the -template command line option, when you are generating a book using the -book option, you can override the default formats that pod2fm produces.
A template is a FrameMaker document, the binary form or MIF, that has formats you want already applied to it. With this version of pod2fm, you can override the Master Page and Reference Page layouts, and Paragraph formats. There are other formats that you can specify, like Character formats and Color definitions, but this version of pod2fm does not do anything with them.
There are several Paragraph Formats that pod2fm uses and there is a mapping from the pod command to the paragraph format that is produced. The exception to the mapping is the =over and =back commands: they modify the paragraph format by shifting its left edge by .1" times the amount in the =over command.
You need to take this into account when you are changing the paragraph format. If you drop the size of the font in the format, you do not get a smaller amount of shifting. An =over 5 always give an indent of .5".
The paragraph formats that pod2fm uses are:
Paragraphs marked with this format contain the name of the pod. The name is automatically added to the start of each document, and this format is only used here.
You can use the pod_TITLE tag to generate a header or footer with the name of the pod in it by changing the Master Page layout. If you are generating a book, this format is exported so that you can create a Table of Contents by changing the Reference Page.
This format marks a standard paragraph. The left edge moves with each =over n and =back. The edge moves by n*.1".
This format is used for section headers. The command is used like:
=head1 text
=head1
where text is printed in this format. The =over or =back command do not change this format.
If you are generating a book, this format is exported so that you can create a Table of Contents by changing the Reference Page. Also, a Marker is placed on the text so that it can be placed in an Index.
This format is used for sub-section headers. The command is used like:
=head2 text
=head2
This format is used on ordered (numbered) lists. If the indent command is in this form:
=item n[.]
=item
where n is any number followed by an optional period. The next paragraph will be marked with this format and will print as a hanging indent that starts with an automatically generated number and a period. The start of the paragraph is shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
This format is used on unordered lists. If the indent command is in this form:
=item *
the next paragraph will be marked with this format and will print as a hanging indent that starts bullet. The start of the paragraph is shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
This format is used on description lists. If the indent command is in this form:
=item * text
the text will be printed after a bullet, on a line by itself. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
This format is used on hanging indent lists. If the indent command is in this form:
=item text
the text will be printed as a hanging indent. The next paragraph will be marked with this format and will print with the start of the paragraph shifted by the amount in the =over command. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
This format is used on implied lists. If the first line of a paragraph is in this form:
____hang_______text | | +- spaces +- tabs or tabs
the hang will be printed as a hanging indent and the text will be printed with the left edge shifted to 2.5" from the current pod_Body left edge. The rest of the lines in the paragraph are treated the same, i.e.: each line in the pod's paragraph is converted to a FrameMaker paragraph that is marked with pod_il. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
This format is used on verbatim paragraphs. If the first line of a paragraph is in this form:
____text | +- spaces or tabs
the text, including the leading white space, will be printed with the left edge shifted to the current pod_Body left edge. The rest of the lines in the paragraph are treated the same, i.e.: each line in the pod's paragraph is converted to a FrameMaker paragraph that is marked with pod_pre. Any paragraphs that come after the first are marked with pod_Body and the left edge is shifted by the amount from the =over command.
If you are producing a book, and you have a -template command line option and you are importing the Master Page Layout (-format Page or the default), you can produce a Table of Contents by adding the -toc option. Pod2fm will automatically add a generated document called book_nameTOC.doc to the book file, where book_name is the optional argument to the -book command line option. If no argument is give on the -book, you will get a document called perlTOC.doc.
To specify the format of the Table of Contents, you need to go to the reference pages of the template document and create a flow called 'TOC'. Within the flow, you need to create a picture of what the Table of Contents will look like. You can add Building block to the picture that allows you to control what is printed, things like the page number and text for the TOC entry. See the FrameMaker On-Line Help or Using FrameMaker printed manual for a complete description of how to set up a TOC Reference page.
The TOC entry is derived from paragraphs in the documents in the book that are marked with specific paragraph formats. Pod2fm uses the paragraph formats pod_TITLE, pod_head1, and pod_head2 to mark the TOC entries.
To make a TOC entry show, you need to create a new paragraph format that tracks the format used in the documents. The new paragraph have the form:
format_nameTOC
where format_name is the format name used in the document. Here is an example of TOC specification:
Paragraph tagged Specifies ---------------- --------- pod_TITLE <$paratext><$nopage> pod_head1 <$paratext>\t<$pagenum> pod_head2 <$paratext>\t<$pagenum>
would print something like this:
POD2FM NAME 1 SYNOPSIS 1 DESCRIPTION 1 OPTIONS 1 TEMPLATES 3 Paragraph Formats 3 Table of Contents 5 Index 6 BUGS 6 AUTHORS 7
An Index document is much the same as a Table of Contents document: you must be generating a book and importing Reference Page Layouts from a template, and have a -index command line option.
The format for the Index is also specified on a Reference Page in a flow called IX, and it has it's own set of Building Blocks. Please see the FrameMaker documentation for more details on how to create the Index Reference Page.
Pod2fm generates the index from any Index markers that have been place in the documents. The markers are generated on any =head or =item command, and any interior sequences (like I<>, B<>, and L<>) that refers to and =head or =item.
POD
Getopt::Long File::Find File::Basename Config vars
authors/id/PEASE/pod2fm-1.10.tar.gz
Cleanups, added support for X<>, L<...|...>.
Added checks for Win32 and Macintosh versions of Perl.
Cleaned up for newer versions of Perl (5.003 and up)
Added the -dir option to use all of the pod found in a directory as input. Fixed bug in the processing of TOC and Index.
You can't change the amount of indent using a template file (yet...).
Based on pod2html (in a galaxy long, long ago and far, far away.)
Extended for MML by Mark Pease <Mark_Pease-RXYE40@email.sps.mot.com>.
fmbatch and book support added by Tim Bunce <Tim.Bunce@ig.co.uk>.
Reviewed and enhanced by Marek Rouchal <Marek.Rouchal@siemens-scg.com>.
Please send bug reports to Mark Pease <Mark_Pease-RXYE40@email.sps.mot.com>.
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install pod2fm, copy and paste the appropriate command in to your terminal.
cpanm
cpanm pod2fm
CPAN shell
perl -MCPAN -e shell install pod2fm
For more information on module installation, please visit the detailed CPAN module installation guide.