path: root/support/proof/proof.1

.TH PROOF 1 "Sep 2002" proof "TeX Typesetting Tools"
." $Id: proof.1,v 1.2 2002/09/30$
." Process this file with "groff -man -Tascii proof.1"

.SH NAME
proof \- a simple but smart editor interface to common TeX, LaTeX, METAFONT and MetaPost processing tasks

.SH SYNOPSIS
.B proof
[\fI-P\fR] [\fI-abfp123xyzs\fR] [\fI-u\fR routine] \fIfile\fR
.br
.B proof
\fI-T\fR \fIfile\fR
.br
.B proof
[\fI-hv\fR]

.SH DESCRIPTION
\fBProof\fR is a shell based auxiliary program that's able to process and view TeX, LaTeX, METAFONT and MetaPost sources and thus can be used to quickly produce snapshots of TeX related documents whenever necessary. Its main purpose however is to act as a completion to an ordinary word processing program which normally lacks appropriate facilities to process TeX sources within a common TeX/LaTeX environment. Here, \fBProof\fR completely relieves the author of doing shell related work and thus simplifies the process of preparing PostScript/PDF documents particularly in those cases where various different sources are involved. Besides \fBProof\fR offers a handy control mechanism that may be accessed from within the editor being used, an interface to common METAFONT font test algorithms and a simple back-up facility ensuring that sourcefiles can easily be restored when accidentally overwritten or deleted. For further information on how to use this program see section \fBEXAMPLE\fR please.

.SH OPTIONS
.TP
\fB-P\fR
Enter preview mode - Use this option to start \fBProof\fR in its preview mode. When given on the commandline, the file referred to is periodically checked whether changes were made. If this is the case, \fBProof\fR will attempt to compile your document and subsequently call the viewer to show its current state. This previewing facility is completed by other TeX related features you may select by including one or more of the following options in your command:
.RS
.TP
\fB\-a\fR
Leave auxiliary files untouched - Auxiliary files like \fI.aux\fR, \fI.log\fR, \fI.idx\fR and so on are normally deleted when \fBProof\fR terminates. This option switches off this default behaviour.
.TP
\fB\-b\fR
Create back-up file - Each time \fBProof\fR terminates, it creates a new back-up copy of the current sourcefile. Alternatively you can use Walter Tichy's "Revision Control System" (RCS) to save your document, which might be useful when editing larger documents. (see your \fI.proofrc\fR file for further information on RCS please)
.TP
\fB\-f\fR
Use formatfile \fImylatex\fR - A suitable formatfile can be obtained by running initex over the current LaTeX source. ("initex \e&latex mylatex.ltx sourcefile" should work properly on most platforms.) The newly created formatfile \fImylatex\fR should then be moved to the appropriate location in order to make it accessible to \fBProof\fR. (see your \fI.proofrc\fR file on where this is) Alternatively you may have \fBProof\fR create a formatfile of your own, which is the default behaviour if the \fB\-f\fR option is set and a suitable formatfile is not yet available.
.TP
\fB\-p\fR
Use PostScript-Type-1-fonts - Selects PostScript-Type-1-fonts to process dvi-files. The default is to use TeX's own font family Computer Modern. (This option is in effect only if you use Tomas Rokicki's 'dvips' driver to process dvi-files!)
.TP
\fB\-n\fR
METAFONT proofing mode n, where n can be 1, 2 or 3 - This option takes effect only when processing METAFONT files. In this case it serves to select one out of three possible methods sourcecode is processed and viewed. Just try out which method fits best to your needs.
.TP
\fB\-x\fR
Generate dvi-file
.TP
\fB\-y\fR
Generate ps-file (default)
.TP
\fB\-z\fR
Generate pdf-file
.TP
\fB\-u\fR
Call userdefined conversion routine - You may define a conversion routine of your own if you need a particular output file format \fBProof\fR does not provide. (see your \fI.proofrc\fR file on how to do this)
.TP
\fB\-s\fR
Skip viewing - Using this option causes that \fBProof\fR won't call the viewer to show changes. Only the target file requested will be generated.
.RE
.PP
Each of the options listed above may be handed over also in the sourcecode itself. (A valid sourcecode entry has to be in the form of a LaTeX comment string and must be placed on the first line, for example like this in LaTeX documents
.RS
.TP
"\edocumentclass{article} % (\fB-ab -u\fR A5)"
.RE
.PP
or this in METAFONT/MetaPost sourcecode
.RS
.TP
"% (\fB-ab2\fR)".)
.RE
.PP
\fBProof\fR looks for this entry each time a new preview cycle is lauched, so there's no need to start \fBProof\fR anew if you wish to alter the settings you made at startup. Simply enter the right option in the first line of your document prior to saving the buffer content and \fBProof\fR will show a different image of your document! This method's also recommended if you intend to work on more than one file at the same time, since it ensures that each document is processed automatically in the right manner, even if you don't remember the original settings any more. However, if you'd like to make use of this feature, keep in mind that this would make both additional small letter commandline options (except \fB-h\fR and \fB-v\fR) and existing environmental settings ineffective.
.TP
\fB\-T\fR
Leave preview mode and exit - Use this option to close your editing session! \fBProof\fR will check whether the options \fB-a\fR and \fB-b\fR are set. You'll also see a short list showing \fBProof\fR's output.
.TP
\fB\-h\fR
Print help message
.TP
\fB\-v\fR
Print version information

.SH NOTE
Omitting option \fB-P\fR when calling \fBProof\fR haves the program immediately terminate after the viewer is called. Use this to create snapshots! It's also possible to view or convert target files. "\fBproof\fR \fItext.ps\fR" for instance would simply call the viewer needed to show the file's content, whereas "\fBproof -z\fR \fItext.ps\fR" would prior to that create the corresponding PDF version of the file referred to. (See your \fI.proofrc\fR file on how to adjust a particular conversion mechanism \fBProof\fR uses.)

.SH ENVIRONMENT
You may wish to use the environment variable \fBPROOFOPTS\fR to adjust \fBProof\fR's startup behaviour if neither commandline options, nor sourcecode options are present. To do so, you just have to build a string of those options you'd like to be activated on startup. So "export \fBPROOFOPTS\fR='\fB-P -fp\fR'; \fBproof\fR \fItext.tex\fR" for instance would do exactly the same as "\fBproof\fR \fB-P -fp\fR \fItext.tex\fR" when given on the commandline.

.SH EXAMPLE
To prepare your PostScript document, let's say \fItext.ps\fR, you might proceed as follows:

At first tell \fBProof\fR which file to process, for instance by typing "\fBproof -P -fb\fR \fItext.tex\fR" on the commandline. \fBProof\fR will then attempt to compile your sourcecode using your formatfile \fImylatex\fR as requested by handing over option \fB-f\fR, and, if this worked out, call the viewer to show the compiler output. When this is done, call your favourite word processing program and prepare your document as you normally would do.

Now, if your document has grown and you'd like to see a snapshot of its current state, just save the editor's buffer content to disk. \fBProof\fR will notice when this happens and immediately update the image if the viewer's still running respectively start the viewer anew if it has been stopped by user intervention. (There are a few viewing programs however, like T. Theisen's 'Ghostview' for instance, which don't support reopen requests sent by external programs, so maybe you have to reopen the file by hand in order to make recent changes visible.)

Finally, if your document has reached a definite state, either type "\fBproof -T\fR \fItext.tex\fR" or simply hit 'Ctrl-C' in \fBProof\fR's active window. This tells \fBProof\fR to save your sourcefile \fItext.tex\fR according to the instructions fixed in your \fI.proofrc\fR file and delete each of the auxiliary files made during compilation. (To disable both commandline options \fB-f\fR and \fB-b\fR (and any environmental settings too), you would have to insert string "% (\fB-\fR)" in the first line of your document.) Your PostScript document \fItext.ps\fR, located in the current working directory, will be left untouched.

The method of procedure's just the same as above described when processing METAFONT and MetaPost sources instead. Option \fB-z\fR however, causing \fBProof\fR to produce PDF output, will be in effect only when processing TeX sources.

.SH FILES
.TP
.I proof
Shellscript.
.TP
.I proofrc
Configuration file.
.TP
.I proof.1
Manual page.

.SH REQUIREMENTS
\fBProof\fR should work properly on UNIX conformable platforms (i. e. Linux, BSD etc.) provided that there's an intact TeX/LaTeX environment (\fIhttp://www.ctan.org\fR) and GNU bash (Bourne Again Shell), version 2.03 or later (\fIhttp://www.gnu.org/software/bash/bash.html\fR). The install script provided with \fBProof\fR will show some useful information on this topic. See also this list of auxiliary programs \fBProof\fR is known to work fine with: TeX (Web2C 7.3.1) 3.14159, e-TeX (Web2C 7.3.1) 3.14159-2.1, pdfTeX (Web2C 7.3.1) 3.14159-0.13d, pdfeTeX (Web2C 7.3.1) 3.14159-0.13d-2.1, Metafont (Web2C 7.3.1) 2.7182, MetaPost (Web2C 7.3.1) 0.641, dvips v5.86, dvipdfm version 0.13.2c, GNU ghostscript 7.05, gv 3.5.8, ghostview v1.5, xdvi(k) version 22.05d-k, RCS version 5.7. 

.SH "REPORTING BUGS"
Please send bug reports or suggestions to kbosau@web.de.

.SH COPYRIGHT
Copyright (C) 2002 Klaus Bosau

This program can be redistributed and/or modified under the terms of the GNU General Public License as published by the Free Software Foundation. (The exact wording can be found at \fIhttp://www.gnu.org/copyleft/gpl.html\fR.)

.SH "SEE ALSO"
\fBtex\fR(1), \fBetex\fR(1), \fBpdftex\fR(1), \fBpdfetex\fR(1), \fBdvi2pdfm\fR(1), \fBdvipdf\fR(1), \fBmf\fR(1), \fBmpost\fR(1), \fBrcsintro\fR(1), \fImpman.pdf\fR, \fImpintro.pdf\fR, \fImetafp.ps\fR, \fImylatex.ltx\fR, \fIfontsmpl.dvi\fR