[tex-k] Re: dvips documentation is old [with patch]

[Frank Küster]

Hi,

a couple of weeks ago I wrote:

> the dvips documentation is heavily outdated. The section labeled "@node
> EPSF macros" in dvips.texi is especially weird. Unfortunately, this time
> I don't have a useful patch.

So here comes a suggestion. The patch includes also the additions for
papersize options, as discussed in a separate thread.

Regards, Frank

-- 
Frank Küster, Biozentrum der Univ. Basel
Abt. Biophysikalische Chemie

-------------- next part --------------
--- tetex-bin-2.96.1.20040322/texk/dvipsk/dvips.texi.orig	Fri May 21 17:38:48 2004
+++ tetex-bin-2.96.1.20040322/texk/dvipsk/dvips.texi	Tue May 25 18:30:31 2004
@@ -55,7 +55,7 @@
 * Installation::                How to compile and install Dvips.
 * Invoking Dvips::              Command-line options, configuration files, etc.
 * Paper size and landscape::    Changing the paper dimensions.
-* Interaction with PostScript:: TeX meets Dvips meets PostScript.
+* Including graphics and more:: TeX meets Dvips meets PostScript.
 * PostScript fonts::            Installing and using PostScript fonts.
 * Color::                       Using color with Dvips.
 * Index::                       General index.
@@ -1052,13 +1052,15 @@
 @var{papertype} of @samp{landscape}, which rotates a document by 90
 degrees.  To rotate a document whose paper type is not the default, you
 can use the @samp{-t} option twice, once for the paper type, and once
-for @samp{landscape}.
+for @samp{landscape}.  Note that you should not use any @samp{-t} option
+when TeX wrote a @samp{\papersize} special into the dvi file. This is
+done by some La at TeX{} packages, e.g. hyperref.sty.
 
 @item -T @var{hsize,vsize}
 @opindex -T @var{hsize,vsize}
 Set the paper size to (@var{hsize}, at var{vsize}), a comma-separated pair
 of dimensions such as @samp{.1in,-.3cm} (@pxref{papersize special}).  It
-overrides any paper size special in the DVI file.
+overrides any paper size special in the DVI file. 
 
 @item -u @var{psmapfile}
 @opindex -u @var{psmapfile}
@@ -1594,7 +1596,11 @@
 printing decision, such information should be given in the @TeX{} file
 and not on the Dvips command line.  For this reason, Dvips supports a
 @samp{papersize} special.  It is hoped that this special will become
-standard over time for @TeX{} previewers and other printer drivers.
+standard over time for @TeX{} previewers and other printer drivers. 
+
+Note that some La at TeX{} packages, e.g. hyperref.sty, write a papersize
+special into the dvi file - then you do not need, and even should not
+try to specify it manually.
 
 @menu
 * papersize special::           Specifying the paper size in TeX.
@@ -1795,15 +1801,15 @@
 @end itemize
 
 
- at node Interaction with PostScript
- at chapter Interaction with PostScript
+ at node Including graphics and more
+ at chapter Including graphics and more
 
- at cindex interaction with PostScript
+ at cindex Including graphics and more
 @cindex PostScript interaction
 
 Dvips supports inclusion of PostScript figure files (e.g., Encapsulated
 PostScript), downloading other header files (e.g., fonts), including
-literal PostScript code, and hypertext.
+literal PostScript code, and hypertext. 
 
 @menu
 * PostScript figures::          Including an Encapsulated PostScript figure.
@@ -1822,6 +1828,7 @@
 
 @menu
 * Bounding box::                The %%BoundingBox EPS comment.
+* \includegraphics macro::      Including the file in LaTeX.
 * EPSF macros::                 Including the file in TeX.
 * psfile special::              The basic special.
 * Dynamic creation of graphics:: Handling compressed or generated figures.
@@ -1926,18 +1933,79 @@
 the file.
 
 
+ at node \includegraphics macro
+ at subsection LaTeX: Using the \includegraphics macro
+
+ at cindex \includegraphics macro
+ at cindex macros for epsf inclusion
+
+Once the figure file has a bounding box comment (see the previous
+section,) you are ready it the graphic into a La at TeX{} document. For
+LaTeX 2e, you can use the epsf, graphics or graphicx packages, but the last
+one is preferrable - it has the most flexible syntax, and is described
+here. Further information can be found in @file{grfguide} or
+ at file{epslatex}, which should be included in your LaTeX distribution as
+dvi, pdf or ps files. Just put the following command into your preamble:
+
+ at example
+\usepackage[dvips]@{graphicx@}
+ at end example
+
+(If you are still using La at TeX{} 2.09, use epsf.sty).
+
+Depending on your system, a suitable driver setup may already be
+present, so that LaTeX automatically produces dvi files suitable for
+dvips. In this case you can leave out the @samp{[dvips]} parameter.
+
+Now, at the point you want to include a file, enter a line such as:
+
+ at example
+\includegraphics@{foo.eps@}
+ at end example
+
+However, it is usually preferrable to leave out the file extension and
+only use 
+
+ at example
+\includegraphics@{foo@}
+ at end example
+
+because then you can process the same LaTeX file with different @TeX{}
+engines or dvi converters if you also provide suitable graphics files
+for them, e.g. a foo.pdf or foo.png along with the foo.eps. 
+
+ at cindex bounding box, supplying to @TeX{}
+The \includegraphics command has a lot of options in
+ at samp{key=value}-syntax that allow you to resize, rotate or trim the
+included graphic - see @file{grfguide} or @file{epslatex}.  If your file
+does not have a bounding box comment, you can supply the numbers as
+determined in the previous section, in the same order they would have
+been in a normal bounding box comment:
+
+ at example
+\includegraphics[bb=100 100 500 500]@{foo.ps@}
+ at end example
+
+ at noindent
+Now, save your changes and run La at TeX{} and Dvips; the output should
+have your graphic positioned at precisely the point you indicated,
+occupying the proper amount of space. Note that Postscript graphics have
+there origin in the lower left corner. Therefore, in @TeX{}, it will
+occupy a box that extends far above the line where it is put in, but has
+depth zero below it. Combining @samp{\includegraphics} with
+ at samp{\parbox} commands or minipages can sometimes be confusing when
+this is not taken into account.
+
+
 @node EPSF macros
 @subsection Using the EPSF macros
 
 @cindex EPSF macros
 @cindex macros for epsf inclusion
 
-Once the figure file has a bounding box comment (see the previous
-section,) you are ready it the graphic into a @TeX{} document.  Many
-packages for using EPS files exist.  One distributed with Dvips is the
-files @file{epsf.tex} (for plain @TeX{}) and @file{epsf.sty} (for
-La at TeX{}).  For plain @TeX{}, add a line like this near the top of your
-input file:
+If you are using plain @TeX{} or La at TeX{} 2.09, you need @file{epsf.tex}
+(for plain @TeX{}) and @file{epsf.sty} (for La at TeX{}).  For plain
+ at TeX{}, add a line like this near the top of your input file:
 
 @flindex epsf.tex
 @example
@@ -1946,7 +2014,7 @@
 
 @noindent
 If you are using La at TeX{} 2e, use the @samp{graphics} or @samp{graphicx}
-package.  
+package (see @xref{\includegraphics macro}).  
 @flindex epsf.sty
 If you are using La at TeX{} 2.09, add the @samp{epsf} style option, as in: