src/cmd/mpm/README

An experiment in page makeup for troff output...

-mpm is a version of standard -ms that causes extra
information for vertical justification and figure
placement to be included in troff output.  Commands that
have been augmented to provide paddable space are

	.SH and .NH
	.PP and .LP	no space if \n(PD is 0; normally .nr PD 0.3v; leave at least 1u
	.IP and .QP	also
	.EQ and .EN
	.TS and .TE	no space if \n(TS is 0; normally .nr TS 0.5v
	.PS and .PE
	.P1 and .P2	display programs in CW font
	.DS and .DE
	.QS and .QE

Other commands, registers, strings, etc.:

	.SP n		explicit paddable space, just like .sp n.
			generally you should ALWAYS use .SP instead of .sp.
			if you need exactly a given vertical space, you can say
				.SP 3i exactly
			this space won't be padded.
	.Tm words	prints "words" and the output page number on stderr
			sorry about the spelling; -ms pre-empted .TM
	.NE n		like .ne.  note: does not cause a break

			Others may be added as the need arises.

	.nr FO n	Set the page length.  This value is the bottom of
			the text on the page; a bottom title may lie below.
			default is 10i (== 10 inches).
	%o, %e		are strings containing odd and even page titles
	%#		is the current page number (often useless)
	.PT		is a macro invoked at the top of each "page";
			it will normally use %e, %o and %#.  There is also
			a .BT for page bottoms if desired.
	.BP		force a page break
	.FL		force all waiting figures out before any more running text
	.1C, .2C	multiple columns;  number registers CW and GW set
			the column and gutter width if you don't like the default.
			absent a .FC command, all two-column contents collect
			together on the page
	.FC		freeze current two-column contents and start afresh.
			necessary if you want to switch between 1 and 2 column
			text and keep the relative order among them.

Usage is some variant of

	... | troff -mpm

/usr/lib/tmac/pm is the page-justifier itself;  it is called automatically
by the -mpm macro package.  If you are installing this yourself, you will
have to edit the 2nd line of tmac.pm to arrange that pm is called directly
from troff.

There are several lines in tmac.pm that say
	.so /n/coma/usr/bwk/...
You should delete these;  they are placeholders for some experiments.

If you use -mm, you are more or less out of luck, although we will be
happy to provide a crude and incomplete program that purports to convert
-mm to -ms.  It may suggest what you need but it won't do the job.

To compile pm, you need a C++ compiler, preferably release 2.0 or later.
Put the .c and .h files in a directory, and type
	make
This process may well fail.  The usual cause is that different systems
put function declarations in different header files, and C++ insists that
all functions be properly declared.  You can almost always get through this
part by adding function declarations.  The most likely offender is malloc;
a line like
	extern char *malloc(int);
near the top of slug.c will solve this one.


Bugs, etc.:

	not all -ms commands have been decorated;  in particular,
	the rich variety of document types (TM, CSTR, etc.,) is not
	really supported.

	there are problems with funny first pages and troff input
	that moves back up the page.

	multiple columns:  only .2C is available.  The program does not check
	whether something is wide or narrow:  user has responsibility to mark
	which with .1C or .2C.

	headings are a bit tricky if you want things like
	running titles that include the current section title.
	normally a two-pass procedure using .Tm is needed.
	
	It's a pain to force a blank vertical space of specified height.
	Try this:
		.de x
		\v'\\$1'\0\h'-\w'\0'u'\c
		..
		.x 2.5i


If you want to roll your own, the following components are
included in pm's "command language".  They are inserted in
the troff output in the form of "x X ..." commands, which
are created either by \X'...' or by the .X macro in -mpm.
Look at how they are used in /usr/lib/tmac/tmac.pm for examples.


BS n	breakable stream	n = min # lines that must appear on page
				use:  PP, LP, IP, ...

US	unbreakable stream	use:  KS/KE, DS/DE, TS/TE, EQ/EN, PS/PE, etc.

BF v	breakable float		v = preferred vertical location of box center
				use:  FS/FE
				use two successive BF's to give two preferences

UF v	unbreakable float	v = preferred vertical location of box center
				use:  KF/KE
				use two successive UF's to give two preferences

PT	page title		use:  user has absolute control between PT and END
				no SP's or other pm commands inside are processed

BT	bottom title		use:  user has absolute control between BT and END

END	end			end a US, BF, UF, PT, or BT
				all constructs nest, but a float within another float
				or a US block will not float within or outside the block

NE n	need			break page if a VBOX of height n would not fit on page
				use:  .NE n

SP n	space			paddable space of n
				use:  .SP n

PARM NP v			top of pm text at v
	new page

PARM FO v			bottom of pm text at v
	footer			length of text on page = FO-NP

PARM PL v			physical page ends at v
	page length		default = FO + NP

PARM MF x			tolerance to prevent padding
	minimum fullness	default = 0.9

PARM CT x			tolerance for two-column operation
	column tolerance	default = 0.5

PARM DBG x			debugging flag

TM str	message			.Tm words prints <pageno> <tab> <words> on stderr

MC n o	multiple column		n columns, offset o.
				Only 1 and 2 columns will work.

CMD BP	break page		force page break

CMD FL	flush			force all queued figures out before any more
				stream material is output

CMD FC	freeze columns		force out current two-column contents;
				start a fresh one

Something like this will probably have to be added:

NC	new column		HARD!

Known botches in the existing implementation of pm:

If a footnote is split across two pages, any associated separator line
will not be copied.  If there are multiple footnotes on one page, there
will be multiple separators too.  -mpm's .FS macro does not provide a
separator.  If you want a separator line, put it in explicitly with
a call to the .FA macro.

There are not enough settable parameters;  in particular, the
way to control the height is a botch.


Historical note:  There is a simpler version of pm and -mpm
called pj and -mpj that only does vertical justification of
pages that have already been laid out by conventional means.
This simpler version may be adequate, but it is no longer
supported and memory of how it works is growing dim.