NAME

pod2fm - convert pod format to FrameMaker documents and book file

SYNOPSIS

    pod2fm [-mmlonly |
	    -nodoc [-lock]
	    [-book [I<book_name>] [-noopen]
		[-template I<document> [-format I<types>]... [-toc] [-index]
	    ]
	]

DESCRIPTION

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

OPTIONS

-mmlonly

-nommlonly

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 is '-nommlonly'.

-nodoc

-doc

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.

-lock

-nolock

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

-book [book_name]

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 allow 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'.

-noopen

-open

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.

-template document

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.

-format type

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.

-toc

-notoc

-index

-noindex

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 of the TEMPLATES section of this man page, for more information.

The defaults are -notoc and -noindex.

TEMPLATES

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.

Paragraph Formats

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:

pod_TITLE

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.

pod_Body

This format marks a standard paragraph. The left edge moves with each =over n and =back. The edge moves by n*.1".

pod_head1

This format is used for section headers. The command is used like:

=head1 I<text>

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.

pod_head2

This format is used for sub-section headers. The command is used like:

=head2 I<text>

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.

pod_ol

This format is used on ordered (numbered) lists. If the indent command is in this form:

=item I<n>[I<.>]

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.

pod_ul

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.

pod_dl

This format is used on description lists. If the indent command is in this form:

=item * I<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.

pod_hi

This format is used on hanging indent lists. If the indent command is in this form:

=item I<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.

pod_il

This format is used on implied lists. If the first line of a paragraph is in this form:

    ____I<hang>_______I<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.

pod_pre

This format is used on verbatim paragraphs. If the first line of a paragraph is in this form:

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

Table of Contents

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:

I<format_name>TOC

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

Index

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.

BUGS

Fmbatch dies when it tries to work on a Table of Contents or an Index. This happens when both in the ImportFormats and the Update. To get around this, just open the book file in maker and do the Import Formats and Update there.

You can't change the amount of indent using a template file (yet...).

AUTHORS

Based on pod2html. Extended for MML by Mark Pease <Mark_Pease-RXYE0@email.mot.com>. fmbatch and book support added by Tim Bunce <Tim.Bunce@ig.co.uk>.

Please send bug reports to Mark Pease <Mark_Pease-RXYE0@email.mot.com>.

cpanm pod2fm

perl -MCPAN -e shell
install pod2fm