1 files changed, 188 insertions, 0 deletions
diff --git a/src/cmd/mpm/README b/src/cmd/mpm/README
new file mode 100644
index 00000000..5433ccc3
--- /dev/null
+++ b/src/cmd/mpm/README
@@ -0,0 +1,188 @@
+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.