diff options
Diffstat (limited to 'Master/texmf/doc/dvipdfm/dvipdfm.tex')
| -rw-r--r-- | Master/texmf/doc/dvipdfm/dvipdfm.tex | 1304 |
1 files changed, 0 insertions, 1304 deletions
diff --git a/Master/texmf/doc/dvipdfm/dvipdfm.tex b/Master/texmf/doc/dvipdfm/dvipdfm.tex deleted file mode 100644 index 8ebfc3011a7..00000000000 --- a/Master/texmf/doc/dvipdfm/dvipdfm.tex +++ /dev/null @@ -1,1304 +0,0 @@ -% $Header$ -% \special{ pdf: pagesize width 8.5truein height 11.0truein} -\special{ pdf: docview <</PageMode /UseOutlines>>}% -\catcode`\ =11\def\space{ }\catcode`\ =10 -% Page layout -\tolerance=2000 -\magnification\magstephalf -\advance\hoffset by 0.5truein -\advance\voffset by 0.5truein -\advance\hsize by -1.0truein -\advance\vsize by -1.0truein -\def\makefootline{\baselineskip=40pt\line{\the\footline}} -% -% Some helpful symbols -\def\rtm{{\font\r=cmss10 at 4pt -\font\c=cmsy5 -\setbox0\hbox{\c\char13}\skip0\wd0\box0\setbox0\hbox{\r R}\advance\skip0 by -\wd0\kern-0.5\skip0\box0}} -\def\tm{{\font\r=cmss10 at 4pt \hbox{\r TM}}}% -% -% Verbatim mode borrowed from manmac macros -% -\outer\def\begindisplay{\obeylines\startdisplay} -{\obeylines\gdef\startdisplay#1 - {\catcode`\^^M=5$$#1\halign\bgroup\indent##\hfil&&\qquad##\hfil\cr}} -\outer\def\enddisplay{\crcr\egroup$$} -\chardef\other=12 -\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other - \catcode`\}=\other \catcode`\$=\other \catcode `\&=\other - \catcode`\#=\other \catcode`\%=\other \catcode `\~=\other - \catcode`\_=\other \catcode`\^=\other - \obeyspaces \obeylines \tt} -{\obeyspaces\gdef {\ }} -\outer\def\begintt{$$\let\par=\endgraf\ttverbatim \parskip=0pt - \catcode`\|=0 \rightskip=-5pc \ttfinish} -{\catcode`\|=0 |catcode`|\=\other - |obeylines % end of line is now active - |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}} -\catcode`\|=\active -{\obeylines\gdef|{\ttverbatim\spaceskip=\ttglue\let^^M=\ \let|=\endgroup}} -\newskip\ttglue -\ttglue=0.5em plus 0.25em minus 0.15em -% -% -% Some color definitions -% -\def\begincolor#1{\special{pdf:bc #1}}% -\def\endcolor{\special{pdf:ec}}% -\def\colored#1#2{% - \begincolor{#1}#2\endcolor} -\def\red{[0.8 0.5 0]}% -\def\green{[0 1 0]}% -\def\blue{[0 0.4 0.8]}% -\def\yellow{[0.8 0.9 0.1]}% -\def\linkcolor{[0.5 0.0 0.7]}% -% -% Small help for images -\def\reserve#1#2#3{\setbox0\hbox{}\wd0=#1 - \ht0=#2\special{#3}\box0} -\def\nreserve#1#2#3{\setbox0\hbox{}\wd0=#1 - \ht0=#2{#3}\box0} -% -% Some font definitions -% -\font\maintitlefont=cmti12 at 20.74pt -\font\headingfont=cmss12 at 14.4pt -\font\subheadingfont=cmss12 at 12pt -% -% -% Miscellaneous token lists -% -\newtoks\title\newtoks\author\newtoks\version -\newtoks\date -% -% Bibliography counters -\newcount\biblioitems\biblioitems=0 -\def\bibitem{\medskip\advance\biblioitems by 1\item{[\the\biblioitems]}} -% -% Counters for section levels -% -\newcount\sectioncount\newcount\ssectioncount\newcount\sssectioncount -\sectioncount0\ssectioncount0\sssectioncount0 -% -\newskip\indentlevel\indentlevel=\parindent -\newskip\secskip\secskip=24pt plus 1pt minus 2pt -\newskip\subsecskip\subsecskip=16pt plus 1pt minus 2pt -\def\beginlist{\par\nobreak\advance\leftskip by \indentlevel\advance\rightskip by -\indentlevel\medskip\nobreak} -\def\endlist{\par\advance\leftskip by -\indentlevel\advance\rightskip by --\indentlevel\medskip} -% -% -\def\settitle{% - {\maintitlefont\colored{\blue}{\the\title}}% - \special {pdf: docinfo << /Title (\expandafter\the\title) >>}} -% -\def\setauthor{% - {\headingfont\colored{\blue}{\the\author}}% - \special {pdf: docinfo << /Author (\the\author) >>}}% -% -\def\setversion{% - {\subheadingfont{\the\version}}% -}% -\def\setdate{% - {\subheadingfont{\the\date}}% -}% -\def\setlink#1{\colored{\linkcolor}{#1}}% -% -\def\setheading#1{% - {\headingfont\colored{\blue}{#1}}\raise\baselineskip - \hbox{\special{pdf: outline 1 << /Title (#1) /Dest [ -@thispage /FitH @ypos ] >> }}}% -% -\def\setsubheading#1{% - {\subheadingfont\colored{\blue}{#1}}\raise\baselineskip - \hbox{\special{pdf: outline 2 << /Title (#1) /Dest [ -@thispage /FitH @ypos ] >> }}}% -% -% \def\link#1#2{\setbox0\hbox{\setlink{#1}}% -% \leavevmode\special{pdf: ann width \the\wd0\space height \the\ht0\space depth \the\dp0 -% << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo -% /D (#2) >> >>}\box0\relax}% -\def\link#1#2{% - \leavevmode\special{pdf: bann - << /Type /Annot /Subtype /Link /Border [ 0 0 0 ] /A << /S /GoTo /D (#2) ->> ->>}\setlink{#1}\special{pdf: eann}\relax} -% -\def\dest#1{\hbox{\raise14pt\hbox{\special{pdf:dest (#1) [ @thispage /FitH -@ypos ]}}}}% -% -\def\maketitle{\noindent\settitle\hfill\setauthor\par - \hrule height 1.0pt\medskip - \noindent\setversion\hfill\setdate\vskip0.3in}% -% -\def\section#1{\advance\sectioncount by 1\ssectioncount0 -\vskip-\lastskip\vskip\secskip\goodbreak -\noindent\setheading{\the\sectioncount. #1}\medskip\nobreak}% -\def\subsection#1{\vskip-\lastskip\advance\ssectioncount by 1% -\vskip\subsecskip\noindent -\setsubheading{\the\sectioncount.\the\ssectioncount\ - #1}\par\nobreak\smallskip}% -% -\def\display#1{\medskip\line{\quad #1\hfil}\medskip} -\def\example{\medskip\noindent{\it Example:\quad}\nobreak} -\def\note{\medskip\noindent{\it Note:\quad\nobreak}} -\def\syntax{\medskip\noindent{\it Syntax:\quad}\nobreak} -\def\description{\medskip\noindent{\it Description:\quad}\nobreak} -% -\def\newpage{\vfill\eject} -% -\def\dvipdfm{{\tt dvipdfm}}% -% -\title{Dvipdfm User's Manual} -\author{Mark A. Wicks} -\version{Version 0.12.4b} -\date{September 19, 1999} -\maketitle -\section{Introduction} -This package is a DVI (\TeX) to PDF conversion utility, -having the following features: - -\beginlist -\item{$\bullet$} {\it Support for outline entries (also called bookmarks), named destinations, -and \link{annotations}{Annotate} (including hyperlinks, forms and widgets).} Nearly -every Acrobat Distiller pdfmark is approximated. - -\item{$\bullet$} {\it Support for ``standard'' DVI specials such -as Hyper\TeX\ (HTML), TPIC, color specials, |PSfile|, and other PostScript specials.} - -\item{$\bullet$} {\it Native support for inclusion of -\link{MetaPost}{postscript} output and -inclusion of arbitrary \link{PostScript}{postscript} files with help from an external program.} - -\item{$\bullet$} {\it Support for thumbnails with a little help from GhostScript to -generate the thumbnails.} - -\item{$\bullet$} {\it Support for arbitrary, nested linear transformations -of typeset material.} Any material on the page, including -\TeX\ text, may be \link{scaled and rotated}{textxform}. - -\item{$\bullet$} {\it Ability to include the first page of a \link{PDF file}{pdfimage} as -an encapsulated object along with its embedded resources such as fonts.} -Included PDF images may be cropped by supplying a bounding box. -Note: Currently, this doesn't work if the contents stream -has multiple segments. - -\item{$\bullet$} {\it Ability to include \link{JPEG}{jpegimage} and -PNG bitmapped images as encapsulated objects.} - -\item{$\bullet$} {\it An internal color stack.} A color stack allows you to change the current color, pushing the -current color onto a stack. At any time, the original color -can be popped from the stack. This is useful, for example, in -headlines, that may have a different color from the current text. -The headline macro can restore the current color without knowing -what it is. - -\item{$\bullet$} {\it Support for partial font embedding and Flate compression -to reduce file size} - -\item{$\bullet$} {\it Support for font reencoding to work around encodings -that aren't fully supported by the Acrobat suite of products.} - -\item{$\bullet$} {\it Balanced page and destination trees.} Balancing -these trees improves reader access speed -on very large documents. - -\endlist - -The electronic version of the document exercises -some of the hypertext features and serves as -a sample input file for |dvipdfm|. -It assumes the reader has some familiarity with the basic features -of the Portable Document Format. The PDF specification -is distributed by Adobe Systems\link{[1]}{pdfmanual}. -An excellent source for information about PDF documents -in general is \link{[2]}{pdfprimer}. Information about -using \TeX\ to construct PDF documents (mainly using Distiller) is the -AcroTeX home page\link{[3]}{acrotex}. - -Currently, the widely accepted method to generate PDF file from \TeX\ -is to use Adobe's Acrobat Distiller on a PostScript -file produced by {\tt dvips}. -The hyperlink features are accessed by using \TeX\ |special| primitives -to embed pdfmarks in the PostScript produced by |dvips|. -H\`an Th\'e Th\`an's PDF\TeX\ project is an alternative method -of generating PDF from \TeX\ source. -Although quite good and fairly mature, the PDF\TeX\ project -modified \TeX\ itself to add primitives that support the PDF features. -I prefer to work with \TeX\ unmodified, as released by Donald Knuth -(call me a purist). -There is an existing DVI to PDF driver called -|dvipdf| written by Sergey Lesenko. At present, it's not widely -available, so I haven't used it. I wrote |dvipdfm| -mainly as an exercise to get at the features -of PDF I was trying to use. This |dvipdfm| project demonstrates that many features -of PDF can be accessed by using a DVI driver. -The PDF features are activated in the driver via -\TeX\ |special| primitives. - -Even though Distiller is the best method of generating PDF (and -probably will remain so for some time) I have several reasons for -seeking alternatives to Distiller. -First, Distiller isn't available for my principle operating -system---Linux. - -My second objection is philosophical. -\TeX\ is a programming language. -A DVI file is a page description consisting of very -simple program instructions that have no branching or -decision instructions. -Similarly PostScript is a complete programming language, -while PDF is a page description language consisting -of simple program instructions -without any branching or decision capabilities. -\TeX\ is like PostScript (without the graphics) -while DVI is like PDF (without the graphics or the hyperlinks). -Creating PDF from DVI using Distiller requires converting a page description to a program, -and converting that program back to a page description. -To continue this analogy, -Pdfmarks are PostScript ``escapes'' and are meant for the Distiller. -\TeX\ |\special| primitives are \TeX\ ``escapes'' and are meant for the DVI driver. -It seems natural to go directly from DVI to PDF, where \TeX\ replaces -PostScript, the DVI driver replaces Distiller, -and \TeX\ |\special| primitives replace the pdfmarks. - -Unfortunately, until graphics software -begins to produce PDF content streams or encapsulated -PDF objects, PostScript will remain the easiest -way to include graphics in \TeX\ documents. -I would hope that in the future, graphics programs -will begin to produce PDF content streams or PDF objects that -may be included using a DVI to PDF translator. Either -of these may be easily embedded using \dvipdfm\ or a similar driver. - -\section{Command Line Options} -\link{Table~1}{commandline} lists the options -that are available on the command line. -\par\noindent -Note: Several flags may be specified at once: -\example -\begintt -dvipdfm -ecz 9 test.dvi -\endtt - -\topinsert -{\dest{commandline}} -\centerline{\colored{\blue}{\subheadingfont Table~1---Command line options -recognized by |dvipdfm|}} -\bigskip\nobreak -\centerline{\vbox{\halign{{\tt #}\hskip -1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr -\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr -\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} --c&{\it Disable color specials} Specifying this option -forces all color commands to be ignored. This is useful for printing a color document -on a black and white printer.\cr -\noalign{\smallskip} --e&{\it Disable partial font embedding.} This may be useful -for forms which need complete fonts, or if you run accross a PFB -file that \dvipdfm\ cannot correctly parse.\cr -\noalign{\smallskip} --f&{\it Set font map file name}. See -the \link{Font Mapping}{fontmap} section for additional information.\cr -\noalign{\smallskip} --m {\it number}&{\it Specify an additional magnification for -the document}.\cr -\noalign{\smallskip} --o {\it filename}&{\it Set the output PDF file name}.\cr -\noalign{\smallskip} --p {\it papersize}&{\it Specify the output papersize.} -Valid paper sizes are |letter|, |legal|, |ledger|, |tabloid|, -|a4|, or |a3|. The default is |letter|. Arbitrary paper -sizes can be specified via \TeX\ special commands, -which is the recommended method.\cr -\noalign{\smallskip} --l&{\it Landscape the document.} This is only -meaningful for paper sizes specified on the command line.\cr -\noalign{\smallskip} --s {\it page\_ranges}&{\it Select a subset of pages from the DVI file.} -The {\it page\_ranges} specifier is a set of comma-separated page -ranges---e.g., |dvipdfm -s 10-12,10-20|. If the first -page in a range is empty (e.g., |dvipdfm -s -10|), it represents -the beginning of the document. If -the last page in a range is empty (e.g., |dvipdfm -s 10-|), it selects the end of the document.\cr -\noalign{\smallskip} --t&{\it Embed thumbnail images.} The thumbnails must be generated by a -separate program. Details are discussed \link{later}{thumbnails} in this document\cr -\noalign{\smallskip} --d&{\it Delete thumbnail images after embedding.}\cr -\noalign{\smallskip} --x {\it number}&{\it Specify the horizontal offset -for the document.} The default is 1.0in.\cr -\noalign{\smallskip} --y {\it number}&{\it Specify the vertical offset -for the document.} The default is 1.0in.\cr -\noalign{\smallskip} --z {\it number}&{\it Specify the compression level.} -Valid compression levels range from 0 to 9, with 0 indicating -no compression. A compression level of 9 is the default.\cr -\noalign{\smallskip} --v&{\it Be verbose.} Among other things, dvipdfm -will display complete file names as various files are opened.\cr -\noalign{\smallskip} --vv&{\it Be more verbose.}\cr}}} -\endinsert - -\section{General Concepts and Syntax for TeX Specials} -Each \TeX\ |\special| -represents a separate command to the \dvipdfm\ -driver. Each |special| must begin with ``|pdf:|'' -to identify that ||special|| as a command for the \dvipdfm\ driver. -A |\special| beginning with any other characters is ignored -by the driver. Leading spaces are ignored. The characters ``|pdf:|'' -are immediately followed by a \dvipdfm\ command. These commands -are documented in \hbox{Sections~3--6}. - -\subsection{PDF Object Syntax and Variable Expansion} -With one exception, the syntax used for PDF objects -within each |\special| specials follows -the PDF specification. -The one exception is variable expansion. -In the syntax specifications that follow, {\it PDF\_Object} -means that an arbitary PDF object is expected. Similarly -{\it PDF\_Array} indicates that a PDF array is expected, {\it PDF\_Dict} -inciates that a PDF dictionary is expected, etc. -See the \link{reference manual}{pdfmanual}\ -for a complete list of PDF object types. - -The single extension implemented in this driver -allows a symbol name of the -form |@|{\it name} whereever any PDF object is expected. -The {\it name} may contain any characters allowed -in a PDF name. -A user-defined symbol beginning with |@| expands to an indirect -reference to the user-defined PDF object. This feature replaces -the |{|{\it name}|}| syntax used with pdfmarks. -In addition to the user-defined names, some names -are defined by the driver. -The driver defined variables are for -referencing objects such as the current page, future pages, -or the current location on the current page. -The driver defined variables appear in \link{Table~2}{drivervariables}. -\topinsert -{\dest{drivervariables}} -\centerline{\colored{\blue}{\subheadingfont Table~2---List of driver -defined variables}} -\bigskip\nobreak -\centerline{\vbox{\halign{{\tt #}\hskip -1em&\vtop{\leftskip0pt\rightskip0pt\hsize=3.0in\noindent #}\cr -\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr -\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} -@catalog&A reference to the document's catalog.\cr -\noalign{\smallskip} -@names&A reference to the document's /Names dictionary.\cr -\noalign{\smallskip} -@pages&A reference to the root of the document's /Pages tree.\cr -\noalign{\smallskip} -@resources&A reference to the current page resource dictionary.\cr -\noalign{\smallskip} -@thispage&A reference to the current page.\cr -\noalign{\smallskip} -@page{\it n}&A reference to page {\it n}.\cr -\noalign{\smallskip} -@nextpage&A reference to the page following |@thispage|.\cr -\noalign{\smallskip} -@prevpage&A reference to the page preceding |@thispage|.\cr -\noalign{\smallskip} -@ypos&A {\it number} representing the current vertical position in units of PDF points.\cr -\noalign{\smallskip} -@xpos&A {\it number} representing the current horizontal position in units of PDF points.\cr -}}} -\endinsert - -In the syntax specifications that follow, several -standard conventions are followed. Terminal -characters that appear in the command -are typeset in the |\tt| font, e.g., |object|. -Nonterminal symbols are typeset in italics. -Optional parameters are surrounded by brackets, e.g., -[{\it optional\_argument}]. An item followed -by~``{*}'' represents an item that may appear -zero or more times. An item followed by~``{+}'' -represents a required item that may appear multiple times. - -\subsection{Dimensions and transformations} -Interaction with the |dvipdfm| driver consists -of short commands with a few arguments delimited by white space. -Typically the arguments are PDF objects. -Two exceptions are dimension specifications and transformations. - -In the \TeX\ style, a dimension specification consists of one of the keywords -|width|, |height|, or |depth| followed by a dimension -consisting of a numerical value, followed by a unit for the dimension. The -unit will typically be |pt| (which represents a \TeX\ point, not a -PDf point) but |mm|, |cm| and |in| are also allowed. -If the document is magnified, the ``true'' dimensions |truept|, -|truemm|, |truecm|, and |truein| may be used. The notation -{\it dimension\/} in a syntax description means a dimension is expected. - -A transformation consists of one of the keywords |scale|, |xscale|, -|yscale|, or |rotate| followed by a numerical value. In the -case of |rotate| the value is the rotation angle in degrees. -The notation -{\it transformation} means a transformation is expected. -In the case of included images originating from -PDF/PostScript files, a clipping or bounding box may be specified -as part of the ``transformation.'' The bounding -box specification consists of the keyword |bbox| -followed by four numerical values, which are -the standard PostScript |llx|, |lly|, |urx|, and |ury| -coordinates of the bounding box. - -\section{Document Construction Commands} -All commands are executed via \TeX\ |\special| primitives -prefixed with the characters ``|pdf:|''. -\example -\begintt -\special{ pdf: out 1 << /Title (Introduction) - /Dest [ 1 0 R /FitH 234 ] >> -\endtt - -\dest{Annotate} -\subsection{Annotate} -\hbox to 0pt{\hskip-1.0in\special{pdf: ann width 3.0in height 36pt << /Type /Annot /Subtype /Text -/Contents (This is a /Text Annotation that looks like a sticky note.) >>}\hss} -\syntax -{\tt annotate} [{\tt @}{\it name}] {\it dimension}+ {\it PDF\_dictionary} -\description -The |annotate| (|annot| or |ann|) command defines an annotation. -Annotations are typically used for -notes, hyperlinks, forms, or widgets. -The parameter {\it name} is an optional alphanumeric identifier -and {\it PDF\_dictionary} is a valid PDF dictionary after variable expansion. -If {\tt @}{\it name} is specified, it may be used in -other PDF objects to refer to this annotation. -One or more {\it dimension} parameters are required -and each consists of the keyword -{\tt height}, {\tt width}, or {\tt depth} followed -by an appropriate length, specified as per \TeX\null. -The |width| must be nonzero and either the |height| or |depth| -must be nonzero. -Each length is a number followed by a unit, such as {\tt pt}, -{\tt in}, or {\tt cm}. Since these values -would typically be entered by \TeX, a {\tt pt} -is a \TeX\ point, not a PDF point. - -\example The annotation in this subsection -was typeset with -\begintt -\special{pdf: ann width 3.0in height 36pt - << /Type /Annot /Subtype /Text - /Contents (This is a /Text Annotation - that looks like a sticky note.) >>} -\endtt - -\subsection{Begin Annotation} -\syntax -{\tt beginann} {\it PDF\_dictionary} -\description -The |beginann| (|bann| or |bannot|) command begins a breakable annotation. -Dvipdfm tries to determine the boundaries of the annotation automatically. -Such an annotation may be broken over several lines (or even several pages). -Unlike |annot|, the annotation may be not be referred to by name later, -since there may be more than once instances of the annotation. -The |beginann| command needs not dimension because |dvipdfm| -computes the correct bounding box on the fly. - -Note: Link breaking is easily fooled at page breaks. If you have problems -with the header or footer wanting to become part of the link, you can -insert a |nolink| command at the beginning of the footer and a |link| -command at the end of the footer. - -\subsection{End Annotation} -\syntax -{\tt endann} -\description -The |endann| (|eann| or |eannot|) terminates a breakable annotation. - -\subsection{Link} -{\tt link} -\description -The |link| command instructs the link breaking algorithm to resume its -operation after a |nolink| command. - -\subsection{Nolink} -{\tt nolink} -\description -The |nolink| command instructs the link breaking algorithm to suspend -it operation. This is only required if there is material inserted -on the page in the {\it middle} of a link. For example, when a link -is broken at the end of a page, the header and footer are inserted -in the middle of the link, but are not part of the link. Material -that is inserted between a |nolink| and |link| will not become -part of the link. The |nolink| and |link| escapes are not necessary -with the standard LaTeX header and footer lines, but may become necessary -if these are changed. - -\subsection{Dest} -\syntax -{\tt dest} {\it PDF\_String} {\it PDF\_Dest} -\description -The |dest| command defines a named destination. -The {\it PDF\_String} is a PDF string naming -the destination. This string may be used in the destination -fields of annotations and outline entries to refer to -this destination. {\it PDF\_Dest} is a PDF -destination object (typically an array). -\example -\begintt -\special{pdf: dest (listofreferences) [ @thispage /FitH @ypos ]} -\endtt - -\subsection{Docinfo} -\syntax -{\tt docinfo} {\it PDF\_dictionary} -\description -The |docinfo| command adds the keys in the specified dictionary to the -document's |/Info| dictionary. All keys are optional, but may include -the keys |/Author|, |/Title|, |/Keywords|, |/Subject|, -and |/Creator|. -\example -\begintt -\special{pdf: docinfo << /Author (Mark A. Wicks) - /Title (This Document) >>} -\endtt - -\subsection{Docview} -\syntax -{\tt docview} {\it PDF\_dictionary} -\description -The |docview| command adds the keys in the specified dictionary to the -document's |/Catalog| dictionary. All keys are optional, but may include -the keys |/PageMode|, -|/URI|, |/OpenAction|, |/AA| -and |/ViewerPreferences|. See the PDF Reference Manual -for documentation of these keys and additional keys. -\example -\begintt -\special{pdf: docview << /PageMode /UseThumbs >> } -\endtt - - -\subsection{Object} -\syntax -{\tt object} [@{\it name}] {\it PDF\_Object} -\description -The |object| (also |obj|) command creates a -PDF object. The parameter {\it PDF\_Object} is any valid PDF object. The -parameter {\it name} may be used to provide an indirect reference -to this object within other -objects. It will be expanded anywhere within -a {\tt special} where a PDF object is -expected. Typically {\it object} is an array -or dictionary. It may be an empty array or -dictionary that can be constructed dynamically via -the {\tt put} command. -\example -\begintt -\special{pdf: object @mydict << /Firstpage @thispage >>} -\endtt - -\subsection{Out} -\syntax -{\tt out} {\it number} {\it PDF\_dictionary} - -\description -The |out| (also |outline|) command adds an outline (also called a ``bookmark'') entry -to the document. -The parameter {\it level\/} is an integer representing the -level of the outline entry (beginning with 1) and -{\it PDF\_dictionary\/} must contain -the two keys {\tt /Title} and either {\tt /Dest} or {\tt /A}. -It may also contain the {\tt /AA} key. These keys are documented -in the PDF Reference Manual. -\example -\begintt -out 1 << /Title (Section 1) /Dest [ @thispage /FitH @ypos ] >> -\endtt -which may be followed by -\begintt -out 2 << /Title (Section 1.1) /Dest [ @thispage /FitH @ypos ] >> -\endtt -\note -You may not skip levels. A level~2 outline entry -must follow a level~1 outline -entry. A level~3 outline entry must follow a level~2 outline -and cannot immediately follow a level 1 outline entry. - -\subsection{Pagesize} -\syntax -{\tt pagesize} {\it dimension}+ -\description -The |pagesize| command specifies the document's physical -paper size. The |pagesize| command must be specified on -the first page and must precede the first annotation -or background color specification on the page. -In other words, it should occur as close to the -beginning of the document as possible. -\example -\begintt -pagesize width 11.0truein height 8.5truein -\endtt - -\subsection{Put} -\syntax -\beginlist -{\tt put} @{\it name} {\it PDF\_Object}+ -\endlist -or -\beginlist -{\tt put} @{\it name} {\it PDF\_Dictionary} -\endlist -\description -The |put| command modifies an existing PDF object created with |obj|, -or one of the following internally defined objects: |@catalog|, -|@names|, |@pages|, |@thispage|, or |@resources|. -The first form is used when @{\it name} is an array. The second -form is used when @{\tt name} is a dictionary. More than -one object may be added to an array at once. -All keys in {\it PDF\_Dictionary} -are added to the dictionary represented by @{\it name}. -\example -\begintt -\special{pdf: put @mydict << /Nextpage @thispage >>} -\endtt - -\subsection{Thread} -\syntax -{\tt thread} {\tt @}{\it name} {\it dimension}+ [ {\it PDF\_dictionary} ] - -\description -The |thread| (or |art|) command adds a bead to an article. -An article is a collection of boxed regions in the document that should be -read consecutively. -Each bead using the same {\it name} belongs to the same article. -The {\it name} parameter is required. The {\it dimension} parameter -defined the rectangular area belonging to the bead in -the same manner as for |annot|. -The optional PDF dictionary -should supplied on one of the beads. Its keys are -similar to the |/Info| dictionary accessed via the |docinfo| command -and would typically include the |/Title| and |/Author| keys. -Keys in the dictionary may be overwritten by subsequent {\tt thread} commands. -\example -\begintt -\special {pdf: thread @somearticle << /Title (Some title) - /Author (Me) >>} -\endtt - -\subsection{Close} -\syntax -{\tt close} @{\it name} -\description -The |close| writes the named PDF object created with |obj| to the PDF file. -No further |put| commands may be executed for this object. -The object may continue to be referenced using @{\it name} -indefinitely. If the object is never closed, it will -be closed when |dvipdfm| finishes processing the document. - -\section{Form XObjects} -The PDF specification allows an object to be stored once -and displayed at multiple locations throughout the document. -The following commands give access to this facility. - -\subsection{Beginxobj} -\syntax -{\tt beginxobj} @{\it name} {\it dimension}+ -\description -The |beginxobj| (or |bxobj|) command begins the definition of -a Form XObject. All material typeset between the -|beginxobj| and |endxobj| commands will be captured -into the XObject. The material can be displayed later -at an arbitrary location with the |usexobj| command. -The {\it name} may be used to refer to the object later, -either via the |usexobj| command or as an indirect -reference to the XObject if {\it name} is -used within the context of a {\it PDF\_Object}.. -The required {\it dimension} identifies the extent -(i.e., bounding box) of the area to be captured. -It is specified in the same way as for |annot|. - -The material will not display during the object definition. -In other words, if you are typsetting with \TeX\ you -should place the XObject in a box of dimension 0 so -you don't leave a white space hole where the object was -defined. -\example -\begintt -bxobj @myform width 2.0in height 24pt -\endtt - -\subsection{Endxobj} -\syntax -{\tt endxobj} -\description -The |endxobj| (or |exobj|) command ends the previous -|beginxobj| definition. Note that XObject definitions -may not be nested. XObjects can be {\it used} within -other XObjects, however. -\example -\begintt -exobj -\endtt - -\subsection{Usexobj} -\syntax -{\tt usexobj} @{\it name} -\description -The |usexobj| (or |uxobj|) command displays the -form XObject previously defined and -associated with {\it name}. -\example -\begintt -uxobj @myform -\endtt - -\section{Text Transformation Commands} -The commands in this section deal with transformation -of arbitrary material, which may include -material typeset by \TeX. These -may also be used on included graphics images -if the commands in Section~8 won't do the job. - -\subsection{BeginTransform} -\syntax -{\tt begintransform} {\it transformation}+ - -\description -The |begintransform| (|btrans| or |bt|) applies -the specified transformation to all subsequent text. -The scaling is applied first, followed by the rotation. -The reference point of a box following -the |\special| remains fixed. Such transformations -may be nested to perform rotations within rotated text, for exmaple. - -\example -\begintt -\special{pdf: bt rotate 90 xscale 2.0 } -\endtt - -\subsection{BeginTransform} -\syntax -{\tt endtransform} -\description -The |endtransform| (|etrans| or |et|) concludes -the action of the immediately preceding |begintransform| -command. All transformations must be closed -on the same page. The driver will close -any pending unclosed transformations at the -end of the page and issue a warning message. -All material to be transformed -should probably be enclosed in a single box -to prevent any break. -\example -\begintt -\special{pdf: et} -\endtt - - -\section{Color Commands} -The commands in this section deal with manipulation of the color -stack. - -\subsection{Setcolor} -\syntax -{\tt setcolor} {\it PDF\_Number$\vert$\it PDF\_Array} -\description -The |setcolor| (|scolor| or |sc|) command uses its -argument to set the default color for future marking operators. -The current color is replaced and may be retrieved -only by a subsequent |setcolor| command. The argument -may be a single number, which is interpreted as a grayscale -value; a three element array, which is interpreted as an RGB -color space coordinate; or a four element array, which -is interpreted as a CMYK color space coordinate. -\example -\begintt -\special{ pdf: sc [ 1 0 0 ] } -\endtt - -\subsection{Begincolor} -\syntax -{\tt begincolor} {\it PDF\_Number$\vert$\it PDF\_Array} -\description -The |begincolor| (|bcolor| or |bc|) command uses its -argument to set the default color for future marking operators. -The current color is pushed on the color stack. The argument -may be a single number, which is interpreted as a grayscale -value; a three element array, which is interpreted as an RGB -color space coordinate; or a four element array, which -is interpreted as a CMYK color space coordinate. -\example -\begintt -\special{ pdf: bc [ 1 0 0 ] } -\endtt - -\subsection{Endcolor} -\syntax -{\tt endcolor} -\description -The |endcolor| (|ecolor| or |ec|) -changes the default color to -match the color on the top -of the stack. It removes -the color from the stack. -\example -\begintt -\special{ pdf: ec } -\endtt - -\subsection{Bgcolor} -\syntax -{\tt bgcolor} {\it PDF\_Number$\vert$\it PDF\_Array} -\description -The |bgcolor| (|bbc| or |bgc|) command uses the value -of its argument to set the default color for the page -background. The interpretation -fo the argument is the same as for the |begincolor| command. -The stack is not involved here. There is no way -to go back to the previous background color. -\example -\begintt -\special{ pdf: bc [ 1 0 0 ] } -\endtt - -\section{Image Commands} -The commands in this section deal with embedding -graphics into your PDF document. The present -driver supports PDF, PNG, and JPEG graphics inclusion. - -\subsection{Epdf} -\syntax -{\tt epdf} [|@|{\it name}] [{\it dimension}$\vert${\it transformation}]* {\it PDF\_String} - -\description -The {\tt epdf} command ``encapsulates'' the first page of a PDF -file named by {\it PDF\_String} -into a PDF XObject. The resulting XObject is drawn -with the lower left corner at the current location of the page. -The optional @{\it name} parameter may be used -to reference this object within other objects. If a -{\it dimension} is supplied, the object will be scaled to fit -that dimension. A {\it transformation} consists of one of the keywords -|scale|, |xscale|, |yscale|, or |rotate| -followed by a number representing -the scaling factor or rotation angle in degrees. Both {\it transformation} and {\it dimension} -parameters can be supplied as long as they are not logically -inconsistent. - -Note: The object is stored as an XObject and can be redisplayed later by using the -|usexobj| function and specifying {\it name}. - -\example -\begintt -\special{pdf:epdf yscale 0.50 width 4.0in - rotate 45 (circuit.pdf)} -\endtt - -\subsection{Image} -\syntax -{\tt image} [@{\it name}] [{\it dimension} $\vert$ {\it transformation}]* {\it PDF\_String} - -\description -The {\tt image} command ``encapsulates'' an image -taken from the file named by {\it PDF\_String}. -This command functions just like |epdf|. Value -image types may be PDF, JPEG, or PNG images. -This special will eventually replace the |epdf| special. - -Note: The object is stored as an XObject and can be redisplayed later by using the -|usexobj| function and specifying {\it name}. - -\section{Raw Page Marking Commands} -The commands in this section deal with embedding -raw PDF graphics operators into your PDF document. - -\subsection{Bop} -\syntax -{\tt bop} {\it stream} -\description -The |bop| command specifies a marking -stream to be generated at the top of each page. -The parameter {\it stream} is any sequence -of marking operators and is added to the page's content stream. -The stream is applied {\it to all pages} regardless -of where it appears in the document. -\example The two horizontal lines appearing -at the top of each page in this document -were set with -\begintt -\special {pdf: bop q 0 w 0.8 0.5 0 RG - 54 740 m 504 740 l 504 740.25 l 54 740.25 l b - 36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q } -\endtt -\special {pdf: bop q 0 w 0.8 0.5 0 RG - 54 740 m 504 740 l 504 740.25 l 54 740.25 l b - 36 760 m 504 760 l 504 760.25 l 36 760.25 l b Q } - -\subsection{Content} -\syntax -{\tt content} {\it stream} -\description -The |content| command specifies a marking -stream to be added to the current page at -the current location. While it -is possible to change the color -state, etc., with this command, it is -not advised. Use the color management -commands to change colors. - - -\subsection{Eop} -\syntax -\beginlist -{\tt eop} {\it stream} -\endlist -\description -The {\tt eop} specifies a marking stream to be generated at the end -of each page. The parameter {\it stream} is any sequence -of marking operators and is added to the page's content stream. -The stream is applied {\it to all pages} regardless -of where it appears in the document. - -\section{Graphics Examples} - -The examples in this section illustrate some of the transformation -and image inclusion capabilities of \dvipdfm. - -\dest{textxform} -\subsection{Text Transformation} -Tables with slanted entries are possible as shown -in \link{Table~3}{rotatedtable}. This table was achieved using -various ``|bt rotate 35|'' commands. - -The following line of text was done with nested -combinations of ``|bt rotate 10|'' and ``|bt rotate -10|''. - -\def\up#1{\special{pdf:bt rotate 10}\hbox{#1}} -\def\down#1{\special{pdf:bt rotate -10}\hbox{#1}} -You \down{can} nest \down{the} \up{text} -trans\up{form}ation \up{capa}\down{bili}ties \down{to} -achieve \down{effects} \down{like} -{this}. -\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et} -\special{pdf:et}\special{pdf:et}\special{pdf:et}\special{pdf:et} -\special{pdf:et} -\vskip 0.5in - - -\def\rvr{\colored{\red}{\vrule}}\def\entry#1{\special{pdf:bt rotate 35}% -{\vbox to 0pt{\vss\hbox{\quad\colored{\blue}{#1}\quad}\vskip 1pt\colored{\red}{\hrule}}\special{pdf:et}}} -\topinsert -\dest{rotatedtable} -\bigskip -\centerline{\colored{\blue}{\subheadingfont Table 3---Example of rotated -text set in Computer Modern Roman}} -\bigskip -\centerline{\vbox to 0.45in{\vss\offinterlineskip\halign{#&#&#&#&#&#\cr -\entry{1994}& -\entry{1995}& -\entry{1996}& -\entry{1997}& -\entry{1998}& -\entry{1999}\cr -\noalign{\colored{\red}{\hrule}} -\strut\rvr&\rvr&\rvr&\rvr&\rvr&\rvr\crcr}}} -\bigskip -\endinsert - -\dest{imageinclude} -\subsection{Image Inclusion} - -The image in \link{Figure~1}{jpegimage} was included from a JPEG file. -The image shown in \link{Figure~2}{rotatedimage} comes from the same file, -but is loaded at a 50\% scale and a 45$^\circ$ rotation. - -\topinsert -\dest{jpegimage} -\bigskip -\centerline{\reserve{1.50in}{2.05in}{pdf: image (mwicks.jpeg)}} -\medskip -\centerline{\subheadingfont -\begincolor{\blue}Figure~1---A JPEG image of the author.\endcolor} -\bigskip -\endinsert - -\topinsert -\dest{rotatedimage} -\bigskip -\centerline{\reserve{0.75in}{1.25in}{pdf: image rotate 45 scale 0.50 (mwicks.jpeg)}} -\medskip -\centerline{\subheadingfont -\begincolor{\blue}Figure~2---Image of the author scaled by 0.5 and rotated -by 45$^\circ$.% -\endcolor} -\bigskip -\endinsert - -By default, JPEG files are included -at a resolution of 100dpi so if you know the pixel size -of the image, you know how much space to reserve. -Any \TeX\ magnification is applied to the image -in addition to any scaling defined in the |\special|. -For example, this document sets |\magnification=\magstephalf|, -so the images are actually scaled by 1.095. The first -image in this section has a printed width of 1.643in -even though 1.50in was specified in the |\special|. - -Several command line utilities exist that read -the pixel dimensions of a JPEG file. For PDF files, -you can |grep| on |/MediaBox| to get an indication -of the image size. The |/MediaBox| dimensions are -in PDF points. - -The image in \link{Figure~3}{pdfimage} was produced by embedding a PDF file -using |epdf|. - -\topinsert -\dest{pdfimage} -\centerline{\reserve{2.41in}{2.6in}{pdf: epdf width 2.41in (transistor.pdf)}} -\medskip\centerline{\subheadingfont -\begincolor{\blue}Figure~3---An embedded PDF object. -\endcolor} -\endinsert -Notice that any resources required for the object -are also embedded. In this case, the Times Roman font -resource was embedded along with the content stream. - -\dest{thumbnails}\section{Thumbnails} -Thumbnails can be inserted automatically by |dvipdfm| -using the |-t| command line option. However, |dvipdfm| -is unable to generate the thumbnails by itself. This -must be done by some other program such as GhostScript. -The typical two-pass process to include thumbnails would be -\item{1.} -Run |dvipdfm| without the |-t| option (probably -using command line options optimized for speed and not space) -\item{2.} -Run GhostScript to generate the thumbnail images of -each page. -\item{3.} -Run |dvipdfm| with the |-t| or |-dt| option. - -The |dvipdfm| distribution includes a sample -shell script called |dvipdft| which is a wrapper -for |dvipdfm| that generates thumbnails. - -|Dvipdfm| searches for the thumbnail images -in the directory specified by the TMP or TEMP -environment variables, or in the current directory. -The thumbnails must have the same base name as the PDF output -file with an extension indicating the number of the page. -For example, to create a thumbnailed document named |foo.pdf| -you would need to generate thumbnail images in files named -|foo.1|, |foo.2|, etc. - -\dest{fontmap}\section{Font Mapping} -\TeX\ font names can be -mapped into arbitrary physical (PostScript) font names via -the map file named |t1fonts.map|. The file is -similar to the |psfonts.map| file used by |dvips| -and other drivers. Each line in the -file consists of one to three fields delimited -by white space, followed by options that apply to that font. -The complete list of recognized options -appears in \link{Table~4}{options}. - -Sample map file lines are\nobreak -\begintt -cmr10 ot1 -r -ptmro8r 8r Times-Roman -s 0.167 -pncbo8r 8r pncb8a -s 0.167 -\endtt - -The first field of each line -is the \TeX\ font name. The second -field, which is optional, is the encoding name (|.enc| will -be appended to this name, if necessary -to locate an encoding file). The -encoding files have the same format -as those used for |dvips|. -The third optional field is {\it either} the PostScript font -name (if one of the standard PostScript fonts) {\it or} -the file name of a Type~1 binary font file (PFB file). -The {}.pfb extension is assumed by the program. -three fields. If the encoding field is unspecified, -|dvipdfm| used the default encoding supplied with -the Type~1 font. If the name field is unspecified, -|dvipdfm| looks for a Type~1 binary font file -having the same name as the \TeX\ font name. -If there is {\it no} line in the map file, -the behavior is as if a line was specified -without the second or third field. -The keywords |default| or |none| are -recognized in the encoding field so that -a third field may be specified while still -having default behavior in the second field. - -Currently, three options may be specified for each font -as shown in \link{Table~4}{options}. -\topinsert -{\dest{options}} -\centerline{\colored{\blue}{\subheadingfont Table~4---Font options -recognized by |dvipdfm| in the font map file}} -\bigskip\nobreak -\centerline{\vbox{\halign{{\tt #}\hskip -1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr -\omit\hfil\it Option\hfil&\omit\hfil \it Description \hfil\cr -\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} --r&{\it Remap the font to eliminate control characters.} This -option attempts to work around bugs in Acrobat reader that seem -to be triggered by characters that are encoded in certain positions. -Unfortunately, standard \TeX encodings normally use these positions.\cr -\noalign{\smallskip} --e {\it number}&{\it Extend the font horizontally, multiplying the natural -width of the font by the specified number.} This is useful -for generating new fonts by widening existing fonts.\cr -\noalign{\smallskip} --s {\it number}&{\it Slant the font using the specified number}. -This option is useful for building a slanted fonts from a font -for which there is no slanted font.\cr}}} -\endinsert - -\section{Configuration file} -{\dest{configuration}}Dvipdfm reads default command line options, such -as paper size, from a configuration -file contained in the |dvipdfm| directory of the TeX tree. -The format of this file is similar to the |dvips| file configuration -file format. Each line consists of a single command line switch -followed by any arguments. See the configuration file supplied -with the |dvipdfm| distribution for examples. - -\section{Including PostScript graphics images} -{\dest{postscript}}Dvipdfm provides support for illustrations -contained in external PostScript files. -It recognizes two distinct kinds of PostScript files---those -created by MetaPost and everything else. - -MetaPost -files output only a subset of PostScript and -are interpreted {\it natively} by |dvipdfm| -with its own internal minimal PostScript interpreter. -Also, MetaPost output files contain \TeX\ font information in their header -comments, so that they can be easily integrated with \TeX\ by DVI -drivers. Dvipdfm recognizes this font information and uses the \TeX\ -fonts defined in the MetaPost header. - - -All other PostScript files require an external -program to convert the image to PDF format before -|dvipdfm| can include the image. -The freely available GhostScript is capabable of performing this conversion -for most images. - -The user must specify the command line required -to invoke an external program to perform this conversion. -The command line required to invoke the conversion -program is specified using the |-D| command -line (or configuration file) option. The string passed to the |-D| command -line option is a C-style string that is parsed by |dvipdfm|. Within the string, -expansions are performed as described in \link{Table~5}{expansion}. -For example, to use GhostScript, one might use the -command line - -\bigskip - -{\tt -D "cat \%i \vrule\ gs -q -sDEVICE=pdfwrite -sOutputFile=\%o - -c quit" } - - -\topinsert -{\dest{expansion}} -\centerline{\colored{\blue}{\subheadingfont Table~5---Expansions -performed in the -D string.}} -\bigskip\nobreak -\centerline{\vbox{\halign{{\hfil\tt #\hfil}\hskip -1em\strut&\vtop{\leftskip0pt\rightskip0pt\hsize=3.5in\noindent #}\cr -\omit\hfil\it Variable\hfil&\omit\hfil \it Description \hfil\cr -\noalign{\smallskip\begincolor\red\hrule\endcolor\smallskip} -\%i&{\it Expanded to the full path of the EPS file to be included}\cr -\noalign{\smallskip} -\%o&{\it Expanded to the full path name of the PDF file to be -generated}. The command line must be able to create a file -with the name supplied by dvipdfm.\cr -\noalign{\smallskip} -\%b&{\it Expanded to the ``basename'' of the EPS file that is being included.} -The ``basename'' is the full path of the EPS file with the -last ``.'' and any trailing name extension removed.\cr -}}} -\endinsert - -\section{Compatibility with other DVI drivers} -Compatibility with other DVI drivers is achieved -by support for the following ``standard'' special calls. -Many legacy DVI files can be processed by |dvipdfm|, -so long as they use fairly standard special commands. -For example, |dvipdfm| can process DVI files generated -that use the -|\color|, |\rotatebox|, and |\includegraphics| macros -from the standard La\TeX\ Graphics bundle even if |dvips| was the target DVI driver, -e.g., - -\begintt -\usepackage[dvips]{graphics} -\usepackage[dvips]{color} -\endtt - -Specifically, |dvipdfm| understands the following standard special commands: - -\beginlist -\item{$\bullet$} The TPIC specials. - -\item{$\bullet$} The HyperTeX (HTML) hyperlink specials. - -\item{$\bullet$} The ``color'' specials supported by |dvips| and -other drivers. - -\item{$\bullet$} The ``PSfile'' and ``plotfile'' specials for PS/EPS file inclusion -supported by |dvips| and other drivers. Dvipdfm uses a user-specified -external program to convert the PostScript file to PDF format -before including it. - -\item{$\bullet$} The raw PostScript ``ps:'' special supported by |dvips| and -other drivers. Only a few PostScript operators are supported; -|dvipdfm| does not include a complete PostScript interpreter. -Complex PostScript code, such as that embedded by the PSTricks -package, is not supported. -\endlist - -\section{LaTeX Support and Ebb} -Support for the La\TeX\ graphics bundle and |hyperref| -are available. A driver file named |dvipdfm.def| -is distributed with the standard La\TeX -graphics bundle. The latest version -of the |dvipdfm.def| file is supplied -with the |dvipdfm| distribution. -The file required for |hyperref| -support is called |hdvipdfm.def|. - -To facilitate La\TeX\ support, I distribute a companion program -called |ebb|, which extracts bounding boxes from graphics files. If -you want to include JPEG, PNG, or PDF files in your document, you can run -|ebb| on the JPEG, PNG, or PDF file to create the |.bb| files. -The bounding box file will be similarly named with an extension of |.bb|. -For DOS 8+3 compatibility, an original file name extension -of |.jpg|, |.png|, or |.pdf| is removed before creating the name of -the |.bb| file. An extension of |.jpeg| is also recognized and similarly removed. - -\newpage -\section{References} -\tolerance=1000\hbadness=1000 -\bibitem\dest{pdfmanual}{\it Portable Document -Format Reference Manual}, Version 1.2, Adobe Systems Incorporated, 1996. -Available at the following URL: {\tt http://www.adobe.com}. - -\bibitem\dest{pdfprimer}Thomas Merz, -{\it Web Publishing with Acrobat/PDF}, -Springer-Verlag, 1997, ISBN 3-540-63762-1. Chapter~6 of this book is available -at the URL: |http://http://www.ifconnection.de/~tm|. - -\bibitem\dest{acrotex}D. P. Story, {\it AcroTeX}, The AcroTeX home page -is located at the URL: |http://www.math.uakron.edu/~dpstory/acrotex.html|. - -\bye |