diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-17 21:41:51 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-17 21:41:51 +0000 |
commit | 487ca4806cc046076293cf6cc5fbba0db282bac7 (patch) | |
tree | 847b412ab5158dd7bdd7ed7e5a4cc3fbca94be32 /Build/source/texk/web2c/man/mpost.man | |
parent | a3d3111bfe26b8e5f5bc6049dfb2a4ca2edc7881 (diff) |
texk 1
git-svn-id: svn://tug.org/texlive/trunk@1485 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/web2c/man/mpost.man')
-rw-r--r-- | Build/source/texk/web2c/man/mpost.man | 478 |
1 files changed, 478 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/man/mpost.man b/Build/source/texk/web2c/man/mpost.man new file mode 100644 index 00000000000..f47911c9297 --- /dev/null +++ b/Build/source/texk/web2c/man/mpost.man @@ -0,0 +1,478 @@ +.TH MPOST 1 "10 November 2001" "Web2C @VERSION@" +.\"===================================================================== +.if n .ds MP MetaPost +.if t .ds MP MetaPost +.if n .ds MF Metafont +.if t .ds MF M\s-2ETAFONT\s0 +.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP +.if n .ds TX TeX +.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP for troff +.el .ds OX TeX for nroff +.\" the same but obliqued +.\" BX definition must follow TX so BX can use TX +.if t .ds BX \fRB\s-2IB\s0\fP\*(TX +.if n .ds BX BibTeX +.\" LX definition must follow TX so LX can use TX +.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX +.if n .ds LX LaTeX +.if n .ds WB Web +.if t .ds WB W\s-2EB\s0 +.\"===================================================================== +.SH NAME +mpost, inimpost, virmpost \- MetaPost, a system for drawing pictures +.SH SYNOPSIS +.B mpost +.RI [ options ] +.RI [ commands ] +.\"===================================================================== +.SH DESCRIPTION +\*(MP interprets the \*(MP language and produces PostScript +pictures. The \*(MP language is similar to Knuth's \*(MF +with additional features for including +.BR tex (1) +or +.BR troff (1) +commands and accessing features of PostScript not found in \*(MF. +.PP +Like \*(TX and \*(MF, \*(MP is normally used with a large body of +precompiled macros. This version of \*(MP looks at its command line +to see what name it was called under. Both +.B inimpost +and +.B virmpost +are symlinks to the +.B mpost +executable. When called as +.BR inimpost +(or when the +.B -ini +option is given) it can be used to precompile macros into a +.I .mem +file. When called as +.B virmpost +it will use the +.I plain +mem. When called under any other name, \*(MP will use that name as +the name of the mem to use. For example, when called as +.B mpost +the +.I mpost +mem is used, which is identical to the +.I plain +mem. Other mems than +.I plain +are rarely used. +.PP +The +.I commands +given on the command line to the \*(MP program are passed to it as the +first input line. (But it is often easier to type extended arguments +as the first input line, since UNIX shells tend to gobble up or +misinterpret \*(MP's favorite symbols, like semicolons, unless you +quote them.) The first line should begin with a filename, a +.RI \e controlsequence , +or a +.IR &memname . +.PP +The normal usage is to say +.I mpost figs +to process the file +.IR figs.mp . +The basename of +.I figs +becomes the ``jobname'', +and is used in forming output file names. If no file is named, the +jobname becomes +.IR mpout . +The default extension, +.IR .mp , +can be overridden by specifying an extension explicitly. +.PP +There is normally one output file for each picture generated, +and the output files are named \fIjobname\fP\fB\^.\^\fP\fInnn\fP, +where \fInnn\fP +is a number passed to the +.I beginfig +macro. The output file name +can also be \fIjobname\fP\fB\^.\^\fP\fIps\fP +if this number is negative. +.PP +The output files can be used as figures in a \*(TX document by including +.ce +.BI "\especial{psfile=" jobname.nnn } +in the \*(TX document. Alternatively, one can +.B \einput epsf.tex +and then use the macro +.ce +.BI "\eepsfbox{" jobname.nnn } +to produce a box of the appropriate size containing the figure. +.TP +.BI btex " TeX commands " etex +This causes +.I mpost +to generate a \*(MP picture expression that corresponds to the +\*(TX commands. If the \*(TX commands generate +more than one line of text, it must be in a +.I \evbox +or a minipage environment. +.TP +.BI verbatimtex " TeX commands " etex +This is ignored by +.I mpost +except that the \*(TX commands are passed on to \*(TX. When using \*(LX +instead of \*(TX the input file must start with a +.I verbatimtex +block that gives the +.I \edocumentstyle +and +.I "\ebegin{document}" +commands. You can use the `%&' construct in the first verbatimtex +block to ensure that the correct \*(TX format is used to process the +commands. +.PP +Since most \*(TX fonts have to be downloaded as bitmaps, the +.I btex +feature works best when the output of +.I mpost +is to be included in a \*(TX document so that +.BR dvips (1) +can download the fonts. For self-contained PostScript output that can be +used directly or included in a +.I troff +document, start your \*(MP input file with the command +.I "prologues:=1" +and stick to standard PostScript fonts. \*(TX and \*(MP use the names in the +third column of the file +.IR trfonts.map , +which can be found in the directories with support files for \*(MP. +.PP +\*(MP output can be included in a +.I troff +document via the +.I "-m pictures" +macro package. In this case +.I mpost +should be invoked with the +.B -T +flag so that the commands between +.I btex +and +.I etex +or between +.I verbatimtex +and +.I etex +are interpreted as +.I troff +instead of \*(TX. (This automatically sets +.I "prologues:=1" +). +.\"===================================================================== +.SH OPTIONS +This version of \*(MP understands the following command line options. +.TP +.B -file-line-error +.rb +Print error messages in the form +.I file:line:error +which is similar to the way many compilers format them. +.TP +.B -no-file-line-error +.rb +Disable printing error messages in the +.I file:line:error +style. +.TP +.B -file-line-error-style +.rb +This is the old name of the +.B -file-line-error +option. +.TP +.B -halt-on-error +.rb +Exit with an error code when an error is encountered during processing. +.TP +.B -help +.rb +Print help message and exit. +.TP +.B -ini +.rb +Be +.BR inimpost , +for dumping bases; this is implicitly true if the program is called +as +.BR inimpost . +.TP +.BI -interaction \ mode +.rb +Sets the interaction mode. The mode can be one of +.IR batchmode , +.IR nonstopmode , +.IR scrollmode , +and +.IR errorstopmode . +The meaning of these modes is the same as that of the corresponding +commands. +.TP +.BI -jobname \ name +.rb +Use +.I name +for the job name, instead of deriving it from the name of the input file. +.TP +.BI -kpathsea-debug \ bitmask +.rb +Sets path searching debugging flags according to the bitmask. See the +.I Kpathsea +manual for details. +.TP +.BI -mem \ mem +.rb +Use +.I mem +as the name of the mem to be used, instead of the name by which +\*(MP was called or a +.I %& +line. +.TP +.BI -output-directory \ directory +.rb Write output files in +.I directory +instead of the current directory. Look up input files in +.I directory +first, the along the normal search path. +.TP +.B -parse-first-line +.rb +If the first line of the main input file begins with +.I %& +parse it to look for a dump name or a +.B -translate-file +option. +.TP +.B -no-parse-first-line +.rb +Disable parsing of the first line of the main input file. +.TP +.BI -progname \ name +.rb +Pretend to be program +.IR name . +This affects both the format used and the search paths. +.TP +.B -recorder +.rb +Enable the filename recorder. This leaves a trace of the files opened +for input and output in a file with extension +.IR .fls . +.TP +.B -T +.rb +Produce TROFF output. +.TP +.BI -translate-file \ tcxname +.rb +Use the +.I tcxname +translation table. +.TP +.B -troff +.rb +As +.BR -T . +.TP +.B -version +.rb +Print version information and exit. +.\"===================================================================== +.SH ENVIRONMENT +See the Kpathsearch library documentation (the `Path specifications' +node) for the details of how the environment variables are use when +searching. The +.B kpsewhich +utility can be used to query the values of the variables. +.PP +If the environment variable +TEXMFOUTPUT is set, \*(MP attempts to put its output +files in it, if they cannot be put in the current directory. +.PP +Here is a list of the environment variables affect the behavior of +.IR mpost : +.TP +.TP +MPINPUTS +Search path for +.I input +files. +.TP +MFINPUTS +Auxiliary search path for +.I input +files with +.I .mf +extensions. +.TP +MPSUPPORT +Directory for various tables for handling included +.I tex +and +.IR troff . +.TP +MPXCOMMAND +The name of a shell script that converts embedded typesetting commands +to a form that \*(MP understands. Defaults: +.I makempx +for +.I tex +and +.I troffmpx +for +.IR troff . +.TP +TEX +The version of \*(TX \- or \*(LX \- to use when processing +.I btex +and +.I verbatimtex +commands. Default +.IR tex . +This version of \*(MP allows you to use a `%&format' line instead. +.TP +TROFF +The +.I troff +pipeline for +.I btex +and +.I verbatimtex +commands. Default +.I eqn -d\e$\e$ | troff +.TP +MPEDIT +A command template for invoking an editor. +.PP +A +.I .mem +file is a binary file that permits fast loading of macro packages. +.I mpost +reads the default +.I plain.mem +unless another +.I .mem +file is specified at the start of the first line with an +.I & +just before it. There is also an +.I mfplain.mem +that simulates plain \*(MF so that +.I mpost +can read +.I .mf +fonts. (Plain \*(MF is described in +.IR "The \*(MF\^book" ). +.PP +Experts can create +.I .mem +files be invoking +.I inimpost +and giving macro definitions followed by a +.I dump +command. +.PP +The \*(MP language is similar to \*(MF, but the manual +.I A User's Manual for \*(MP +assumes no knowledge of \*(MF. \*(MP does not have bitmap +output commands or \*(MF's online display mechanism. +.\"===================================================================== +.SH FILES +.TP +.I mpost.pool +Encoded text of \*(MP's messages. +.TP +.I *.mem +Predigested \*(MP mem files. +.TP +.I plain.mp +The standard mem file. +.TP +.I mfplain.mp +The \*(MF-compatible mem file. This is loaded when +.I virmp +is invoked via a symbolic link as +.IR mfmp . +.TP +.I $TEXMFMAIN/metapost/base/*.mp +The standard \*(MP macros included in the original distribution. +.TP +.I $TEXMFMAIN/metapost/support/* +Various tables for handling included +.I tex +and +.IR troff . +.TP +.I $TEXMFMAIN/metapost/support/trfonts.map +Table of corresponding font names for +.I troff +and PostScript. +.TP +.I psfonts.map +Table of corresponding font names for +.I tex +and PostScript. +.TP +.I $TEXMFMAIN/doc/metapost/examples.mp +The source file for a few sample figures +that are part of a \*(LX document +.I $TEXMFMAIN/doc/metapost/mpintro.tex +that describes the \*(MP system +in a little more detail. +.\"===================================================================== +.SH NOTES +This manual page is not meant to be exhaustive. The complete +documentation for this version of \*(MP can be found in the info manual +.IR "Web2C: A TeX implementation" . +.\"===================================================================== +.SH "SUGGESTED READING" +Donald E. Knuth, +.I "The \*(MF\^book" +(Volume C of +.IR "Computers and Typesetting" ), +Addison-Wesley, 1986, ISBN 0-201-13445-4. +.br +John D. Hobby, +.IR "A User's Manual for \*(MP" , +CSTR 162, AT&T Bell Labs, +.br +John D. Hobby, +.IR "Drawing Graphs with \*(MP" , +CSTR 164, AT&T Bell Labs, +.br +.I TUGboat +(the journal of the \*(TX Users Group). +.\"===================================================================== +.SH "SEE ALSO" +.BR tex (1), +.BR mf (1), +.BR dvips (1). +.\"===================================================================== +.SH AUTHORS +\*(MP was designed by John D. Hobby, incorporating algorithms from +\*(MF by Donald E. Knuth. It was originally implemented on Unix, +incorporating system-dependent routines from +.BR web2c , +while not relying on it except for the actual \*(WB-to-C translator. +.PP +Ulrik Vieth adapted \*(MP to take advantage of the advanced path +searching features in more recent versions of +.B web2c +and worked towards fully integrating \*(MP into the canonical Unix +\*(TX distribution. He also updated and extended this manual page. +.\"===================================================================== +.SH TRIVIA +Unlike \*(TX and \*(MF, \*(MP originally didn't use any fancy logo. +John Hobby says he prefers the spelling ``MetaPost'', yet Don Knuth +has updated the \*(MF +.I logo.mf +font to be able to typeset a proper \*(MP logo similar to the \*(MF +logo. Feel free to use whatever you think is more appropriate! |