diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /usergrps/uktug/baskervi/8_1/thanh.tex |
Initial commit
Diffstat (limited to 'usergrps/uktug/baskervi/8_1/thanh.tex')
-rw-r--r-- | usergrps/uktug/baskervi/8_1/thanh.tex | 527 |
1 files changed, 527 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/8_1/thanh.tex b/usergrps/uktug/baskervi/8_1/thanh.tex new file mode 100644 index 0000000000..73655e8c86 --- /dev/null +++ b/usergrps/uktug/baskervi/8_1/thanh.tex @@ -0,0 +1,527 @@ +\makeatletter +\def\Program#1{\textsf{#1}} +\def\bs{{\protect\normalfont\ttfamily\char'134}} +\def\Lcs#1{\mbox{\normalfont\ttfamily\bs#1}} +\def\Lfile#1{\mbox{\normalfont\ttfamily#1}} +\def\Lmcs#1{\mbox{\normalfont\ttfamily\bs#1}} +\def\Lpack#1{\textsf{#1}} +\def\arraybackslash{\let\\=\@arraycr} +\newcolumntype{P}[1]{>{\raggedright\arraybackslash}p{#1}} +\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}} +\newcolumntype{H}[1]{>{\raggedright\hangindent=.5em\arraybackslash}p{#1}} +\newcolumntype{M}[1]{>{\raggedright\arraybackslash}m{#1}} +\def\Email#1{(\url{mailto:#1})} +% +\def\parkey#1#2{{\normalsize\ttfamily#1}\lcb#1\rcb} +\def\xparkey#1#2{{\normalsize\ttfamily#1} #1} +\def\lcb{{\protect\normalfont\ttfamily\char'173}} +\def\rcb{{\protect\normalfont\ttfamily\char'175}} +\def\lsb{{\protect\normalfont\ttfamily\char'133}} +\def\rsb{{\protect\normalfont\ttfamily\char'135}} +\def\lab{{\protect\normalfont\ttfamily\char'074}} +\def\rab{{\protect\normalfont\ttfamily\char'076}} +\newsavebox{\boxdef} +\newenvironment{BDef}{\begin{lrbox}{\boxdef}\def\arraystretch{1.0}% + \begin{tabular}{@{}l@{}l@{}l@{}}}% + {\end{tabular}\end{lrbox}% + \BCmd\fbox{\usebox\boxdef}\endBCmd} +\newcommand{\Larg}[1]{{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}} +\newcommand{\Largb}[1]{\lcb{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}\rcb} +\newcommand{\Largs}[1]{\lsb{\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/}\rsb} +\newcommand{\Largr}[1]{({\normalfont\itshape\fontsize{11}{10pt}\selectfont#1\/})} +\newenvironment{BCmd}{\fboxsep=3pt\flushleft\vskip8pt} + {\endflushleft} +\def\DefC#1{\Lmcs{#1}} +\newcommand{\DefCmmmm}[5]{\Lmcs{#1}\Largb{#2}\Largb{#3}\Largb{#4}\Largb{#5}} +\newcommand{\DefCmm}[3]{\Lmcs{#1}\Largb{#2}\Largb{#3}} +\newcommand{\DefCm}[2]{\Lmcs{#1}\Largb{#2}} +\newcommand{\DefCx}[2]{\Lmcs{#1}\Larg{#2}} +\newcommand{\BDefCmmmm}[5]{\begin{BCmd}\fbox{\DefCmmmm{#1}{#2}{#3}{#4}{#5}}\end{BCmd}} +\newcommand{\BDefCmm}[3]{\begin{BCmd}\fbox{\DefCmm{#1}{#2}{#3}}\end{BCmd}} +\newcommand{\BDefCm}[2]{\begin{BCmd}\fbox{\DefCm{#1}{#2}}\end{BCmd}} +\newcommand{\BDefCx}[2]{\begin{BCmd}\fbox{\DefCx{#1}{#2}}\end{BCmd}} +\def\pdftex{pdf\TeX} +\makeatother +\author[Han The Thanh] +{Han The Thanh\\ +Faculty of Informatics,\\ +Masaryk University, \\Brno,\\ Czech Republic\\ +\texttt{thanh@informatics.muni.cz}} +\title{The \pdftex{} user manual} +\date{January 1998} +\begin{Article} +\section{Introduction} +The \pdftex{} project started in 1996 at the Faculty of Informatics, +Masaryk University, Brno, Czech Republic. It forms a primary part of +the MSc and PhD research of Han The Thanh, under the supervision of +Ji\v r\'\i{} Zlatu\v ska and Petr Sojka. The main purpose of the +project was to create an extension of \TeX{} that could create PDF +directly from \TeX\ source files and improve/enhance the result of \TeX\ +typesetting with the help of PDF. \pdftex{} contains \TeX\ as a subset. +When PDF output is not set, it produces normal DVI output; when PDF +output is selected, \pdftex{} produces PDF output that looks identical to +the DVI output. The next stage of the project, apart from fixing +any errors in the program, is to investigate alternative justification +algorithms, possibly making use of multiple master fonts. + +\pdftex{} is based on the original \TeX\ sources and \Program{web2c}, +and has been successfully compiled on Unix, Amiga, Win32 and DOS +systems. It is still under beta development and all features are +liable to change. + +This manual was compiled by Sebastian Rahtz from notes and examples by +Han The Thanh. Many thanks are due to members of the pdf\TeX{} mailing +list (most notably Hans Hagen), whose questions and answers have +contributed much to this manual. + +\section{Implementation details} +The implementation of \pdftex{} consists of two parts: the changes to +\TeX, and the addition of `driver' features. The \TeX-specific part +is written as a change file to the original source of \TeX\ and +contains: +\begin{itemize} +\item a part that generates PDF code visually equivalent to DVI commands; +\item virtual font processing; +\item implementation of new primitives for PDF control. +\end{itemize} + +The `driver' part is written as several source files in C, and +implements +\begin{itemize} +\item font mapping, +\item font inclusion and partial downloading, +\item font re-encoding, +\item PNG picture insertion (using the public domain \texttt{libpng} code), +\item text compression (using the public domain \texttt{zlib} code). +\end{itemize} + +\subsection{Compilation} +\pdftex{} is supplied as a set of additions to the standard Unix +\Program{Web2c} setup, and is a standard part of \Program{Web2c} 7.2 +(from January 1998); compilation should present no problems on most +Unix systems. Porting it to other setups will require a little work, +because of the requirement to combine the normal \TeX{} Web output, +and the parts written in C. + +For Win32 systems (Windows 95, Windows NT) there are two packages +that contain \pdftex, both in \url{CTAN:systems/win32}. +\Program{Web2c} for Win32 is maintained by Fabrice Popineau +\Email{popineau@ese-metz.fr}, and \Program{MikTeX} by Christian Schenk +\Email{cschenk@berlin.snafu.de}. + +A binary version of \pdftex{} for Amiga is made available +(\url{CTAN:systems/pdftex/bin/Amiga}) by Andreas Scherer +\Email{Scherer@Physik.RWTH-Aachen.De}. + +To make the situation more complicated, a Win32 binary version of \pdftex{} +compiled with Cygnus tools will also be made available +in \url{CTAN:systems/pdftex/bin/Win32}. This version will be compiled in +the same way as Unix systems. + +\subsection{Search paths} +When runing \pdftex, some extra search paths need to be set up beyond those +normally requested by \TeX{} itself; in \Program{web2c} these are: + +\begin{description} +\item{VFFONTS} the path where \pdftex{} looks for virtual fonts. +\item{T1FONTS} the path where \pdftex{} looks for Type1 and TrueType + fonts. +\item{TEXPSHEADERS} the path where \pdftex{} looks for the font mapping + file (\texttt{pdftex.map}), PNG pictures and encoding files + (\texttt{*.enc}). +\end{description} + +%--------------------------------------------------------------- +\section{Fonts} +\pdftex{} can only work with Type~1 and TrueType fonts at present, and +a source must be available for all fonts used in the document, except +for the 14 base fonts supplied by Acrobat Reader (Times, Helvetica, +Courier, Symbol and Dingbats). It is \emph{not} possible to use +\MF-generated fonts in \pdftex---apart from the technical reasons, the +resulting Type~3 fonts render very poorly in Acrobat Reader. Given the +free availability of Type~1 versions of all the Computer Modern fonts, +and the ability to use standard PostScript fonts without further ado, +most existing \TeX{} users should be able to experiment with \pdftex. + +\pdftex{} reads a map file called \texttt{pdftex.map}. Reencoding and +partial downloading for each font is specified in this file. Every +font must be listed in this file, each on a separate line. The +syntax of each line is similiar to \Program{dvips}' map files (but may +be changed later). Each line contains the following fields (some of them +are optional): + +{\ttfamily\small\flushleft\begin{tabular}{lllll} +texname&basename&fontflags&fontfile&encoding\\ +\end{tabular} +\endflushleft} + +\begin{description} +\item{\texttt{texname}}: the name of the TFM file +\item{\texttt{basename}}: the base font name (PostScript font name) +\item{\texttt{fontflags}}: an integer number specifying the most + important characteristics of the font. This number is significant + only in the case that the font file is \emph{not} included, and + Acrobat Reader is asked to simulate missing font using its multiple + master defaults. It is a PDF font descriptor (see PDF + manual, section 7.9.2) which is a 32-bit integer containing a + collection of Boolean attributes, with bit 1 being the least + significant. Attributes are true if the + corresponding bit is set to 1 in the integer. The meanings of the + bits is as follows: + +\begin{tabular}{ll} +1 &Fixed-width font\\ +2 &Serif font\\ +3 &Symbolic font\\ +4 &Script font\\ +5 &(reserved)\\ +6 &Uses the Adobe Standard Roman Character Set\\ +7 &Italic\\ +8--16 &(reserved)\\ +17 &All-cap font\\ +18 &Small-cap font\\ +19 &Force bold at small text sizes\\ +20--32 &(reserved)\\ +\end{tabular} + +Bit 6 indicates that the font's character set is the Adobe Standard +Roman Character Set, or a subset of that, and that it uses the +standard names for those characters. About bit 19, the PDF specification says +\begin{quote} +\ldots used to determine +whether or not bold characters are drawn with extra pixels even at +very small text sizes. Typically, when characters are drawn at small +sizes on very low resolution devices such as display screens, features +of bold characters may appear only one pixel wide. Because this is the +minimum feature width on a pixel-based device, ordinary non-bold +characters also appear with one-pixel wide features, and cannot be +distinguished from bold characters. If bit 19 is set, features of bold +characters may be thickened at small text sizes. +\end{quote} +It should be stressed that the font flags provided for many fonts in +the currently distributed \Lfile{pdftex.map} are not correctly derived. +\item{\texttt{fontfile}}: the name of the font source file. This must + be a Type~1 or TrueType font file. If it is preceded by a \texttt{<} + then the font file will be partly downloaded; if it preceded by a + double \verb|<<| then the font file will be included entirely. + Otherwise the font is not included, and only the font parameters are + extracted. Note that the font file \emph{must} always be available + at runtime, even if it not downloaded. +\item{\texttt{encoding}}: the encoding vector used for the font. It + may be preceded by a \texttt{<}, but the effect is the same. The + format is identical to that used by \Program{dvips}. +\end{description} + +Here are some sample lines from \texttt{pdftex.map}: + +\noindent Include font entirely without reencoding --- +\begin{verbatim} + pgsr8r GillSans 34 <<pgsr8a.pfb +\end{verbatim} +\noindent Include font partly without reencoding --- +\begin{verbatim} + pgsr8r GillSans 34 <pgsr8a.pfb +\end{verbatim} +\noindent Do not include font, or reencode it, but extract parameters +from font file --- +\begin{verbatim} + pgsr8r GillSans 34 pgsr8a.pfb +\end{verbatim} +\noindent Include font entirely and reencode --- +\begin{verbatim} + pgsr8r GillSans 34 <<pgsr8a.pfb 8r.enc +\end{verbatim} +\noindent Partially include font and reencode --- +\begin{verbatim} + pgsr8r GillSans 34 <pgsr8a.pfb 8r.enc +\end{verbatim} +\noindent Do not include font but extract parameters from font file and + reencode --- +\begin{verbatim} + pgsr8r GillSans 34 pgsr8a.pfb 8r.enc +\end{verbatim} +\noindent A TrueType font can be used in the same way as a Type 1 +font --- +\begin{verbatim} + Cxr10 Cxr10 34 <Cxr10.ttf Cxtext.enc +\end{verbatim} +\noindent A base font can also be reencoded; +the name of the font file is simply + ignored --- +\begin{verbatim} + phvr8r Helvetica 32 <Helvetica.pfb 8r.enc +\end{verbatim} + +%--------------------------------------------------------------- +\endmulticols +\hrule + +\section{New primitives} +Here is a short description of new primitives added by \pdftex: + +\BDefCx{pdfoutput}{=n} Integer parameter specifying whether the output +format should be DVI or PDF. Positive value means PDF output, +otherwise DVI output. This parameter cannot be specified \emph{after} +shipping out the first page. + + +\BDefCx{pdfcompresslevel}{=n} +Integer parameter specifying the level of text +compression via \texttt{zlib}. +Zero means no compression, 1~means fastest, 9~means +best, 2..8 means something in between. + +\BDefCx{pdfpagewidth}{=dimen} +\BDefCx{pdfpageheight}{=dimen} +Dimension parameters specifying the +page width and page height of PDF output. +If not specified then they are calculated as $\Lcs{hsize} \mbox{ or } +\Lcs{vsize} + 2 \times (1in + \Lcs{hoffset}\mbox{ or }\Lcs{voffset})$, +when \pdftex{} writes the first page. + + +\BDefCm{pdfliteral}{pdf text} Like \Lcs{special} in normal \TeX, this +can be used to insert raw PDF code into the output. This allows +support of color, and text transformation. + +\BDefCx{pdfinfo}{ \parkey{author}{author name} +\parkey{title}{title} +\parkey{subject}{subject text} +\parkey{keywords}{keywords}} +Specify document information. All keys are optional; if this +information is provided, it can be seen in Acrobat Reader with the +menu option \textsf{Document Information $\leadsto$ General} + +\BDefCx{pdfcatalog}{ \parkey{pagemode}{mode} \parkey{uri}{URI}} +Document display information. Both keys are optional. +\emph{URI} provides the base URL of the document, and +\emph{pagemode} determines how Acrobat displays the document on startup. +The possibilities are: +\begin{flushleft} +\begin{tabular}{>{\ttfamily}lP{.75\textwidth}} +/UseNone & + Open document with neither outline nor thumbnails visible.\\ +/UseOutlines& Open document with outline visible.\\ +/UseThumbs& Open document with thumbnails visible.\\ +/FullScreen& + Open document in full-screen mode. In full-screen mode, there is +no menu bar, window controls, nor any other window present.\\ +\end{tabular} +\end{flushleft} +The default is \texttt{/UseNone}. + +\BDefCx{pdfimage}{ \xparkey{height}{dimen} \xparkey{width}{dimen} filename} +Insert a bitmap image in PNG format, optionally changing width, height +or both. Dimensions which are not specified will be treated as zero. If both +height and width are zero then the box takes the natural size of the +image. If one of them (width or height) is zero and the second is not, +then the first one (the zero one) will be set to a value proportional +to the second one so as to make the box have the same proportion of width +and height as the image natural size. If both width and height are +positive then the image will be scaled to fit these dimensions. + +\BDefCx{pdfform}{ num} + Write out the \TeX{} box \emph{num} as a Form object to the PDF file. +\BDefCx{pdflastform}{} +Returns the object number of the last Form written to the PDF file +\BDefCx{pdfrefform}{ \Lcs{name}} +Put in a reference to the PDF Form called \Lcs{name}. + +These macros support a feature called ``object reuse'' in \pdftex. The +idea is to create a Form object in PDF. The content of the Form object +corresponds to the content of a \TeX\ box, which can also contain pictures +and references to other Form objects as well. After that the Form can +be used by simply referring to its object number. This feature can be +useful for large document with a lot of similiar elements, as it can +reduce the duplication of identical objects. + +\BDefCx{pdfannottext}{ + \xparkey{width}{dimen} + \xparkey{height}{dimen} + \xparkey{depth}{dimen} + \parkey{attr}{attributes} + \Largb{text}} +Attach a text annotation at the current point in the text. The +attributes can be used to specify the default appearance of the +annotation (e.g., \texttt{/Open true} or \texttt{/Open false}), as well +as many other features (see Table 6.8 of the PDF manual). + +\BDefCx{pdfdest}{ + \xparkey{num}{n} + \parkey{name}{refname} + appearance} + +Establish a destination for links and bookmark outlines; the +link must be identified by either a number or a symbolic name, and the +way Acrobat is to display the page must be specified; +\emph{appearance} must be one of +\begin{flushleft} +\begin{tabular}{>{\ttfamily}ll} +fit & fit whole page in window\\ +fith & fit whole width of page \\ +fitv & fit whole height of page \\ +fitb & fit whole `Bounding Box' page \\ +fitbh & fit whole width of `Bounding Box' of page \\ +fitbv & fit whole height of `Bounding Box; of page \\ +\end{tabular} +\end{flushleft} + +\BDefCx{pdfannotlink}{ % + \xparkey{height}{dimen} + \xparkey{depth}{dimen} + \parkey{attr}{attributes} + action +} + +Start a hypertext link; if the optional dimensions are not specified, +they will be calculated from the box containing the link. The +\emph{attributes} (explained in great detail in section 6.6 of the PDF +manual) determine the appearance of the link. Typically, this is used +to specify the color and thickness of any border around the link. Thus +\texttt{/C [0.9 0 0] /Border [0 0 2]} specifies a color (in RGB) of +dark red, and a border thickness of 2 points. + +The \emph{action} can do many things; some possibilities are +\begin{flushleft} +\begin{tabular}{lP{.7\textwidth}} +goto num \emph{n} & \\ +goto name \Largb{refname} & Jump to a point established as +\emph{name} with \Lcs{pdfdest}\\ +goto file \Largb{filename} & Open a local file; this can be used +\emph{with} + a \emph{name} or \emph{num} +specification, to point to a specific location on the +file. Thus +\verb|goto file{foo.pdf} name{intro}|\\ +thread num \Largb{n} & \\ +thread name \Largb{refname} & Jump to thread identified by \emph{n} +or \emph{refname}\\ +user \Largb{spec} & +Perform user-specified action. Section 6.9 of the PDF manual explains +the possibilities. A typical use of this is to specify a URL, e.g.\ +\texttt{/S /URI /URI (http://www.tug.org/)}. +\end{tabular} +\end{flushleft} + + +\BDefCx{pdfendlink}{} +Ends link; all text between +\Lcs{pdfannotlink} and \Lcs{pdfendlink} will be treated as +part of this link. \pdftex{} may break the result across lines (or +pages), in which case it will make several links with the same content. + +\BDefCx{pdfoutline}{ + action + \xparkey{count}{n} + \Largb{text} +} + +Create a outline (or bookmark) entry. The first parameter specificies +the action to be taken, and is the same as that allowed for +\Lcs{pdfannotlink} (see above, though note that the +\texttt{Page} key does not work properly at present). +The \emph{count} specifies the number +of direct subentries under this entry, 0 if this entry has no +subentries (in this case it may be omitted). If the number is +negative, then all subentries will be closed and the absolute value of +this number specifies the number of subentries. The \emph{text} is +what will be shown in the outline window (note that this is limited to +characters in the PDFEncoding vector). + +\BDefCx{pdfthread}{ \xparkey{num}{n} \parkey{name}{refname} } +Start an article thread; the corresponding \Lcs{pdfendthread} must be +in the box in the same depth as the box containing \Lcs{pdfthread}. All +boxes in this depth level will be treated as part of this thread. An +identifier (\emph{n} or \emph{refname}) must be +specified; threads with same identifier will be joined together. + +\BDefCx{pdfendthread}{} +Finish the current thread. + +\BDefCx{pdfthreadhoffset}{=dimen} +\BDefCx{pdfthreadvoffset}{=dimen} +Specify thread margins. + + +One way to learn more about how to use these primitives is to have a +look at the file \Lfile{example.tex} in the \pdftex{} distribution. + +\hrule + +\multicols{2} +\section{Graphics and color} +Probably the biggest single usage problem with \pdftex{} at the +present time is the inclusion of graphics. The program only directly +supports graphic inclusion in one bitmap format, PNG (Portable Network +Graphics). + +Two commonly-used techniques are not available --- the inclusion of +Encapsulated PostScript figures, and the inclusion of raw PostScript +commands (the techique utilized by the \Lpack{pstricks} package). +Although PDF is a direct descendant of PostScript, it lacks any +programming language commands, and cannot deal with arbitrary +PostScript. There are two ways to proceed with existing EPS files: +firstly, convert them to PNG (using programs like Image Magick, Image +Alchemy, or Ghostscript); or secondly, try converting them to simple +PDF. If the picture has no special fonts, the chances are quite good +that Ghostscript's pdf writer will produce a file containing a single +PDF object, which can be included using \Lcs{pdfliteral} commands +(this is managed by the standard \LaTeX{} graphics package). + +Other alternatives for graphics in \pdftex{} are: +\begin{enumerate} +\item \protect\LaTeX{} picture mode: since this is implemented simply in terms + of font characters, it works in exactly the same way as usual; +\item Xy-pic: If the PostScript backend is not requested, Xy-pic uses + its own Type~1 fonts, and needs no special attention; +\item tpic: The `tpic' \Lcs{special} commands (used in some macro + packages) can be redefined to produce literal PDF, using macros by + Hans Hagen; +\item MetaPost: although the output of MetaPost is PostScript, it is + in a highly simplified form, and a MetaPost to PDF conversion + (written by Hans Hagen and Tanmoy Bhattacharya) is implemented as + a set of macros which read MetaPost output and support all of its + features; +\item It is possible to insert a ``pure'' PDF file (PDF that has + only one page without fonts, bitmaps or other resources) using a + macro package that reads the external PDF file line by line. +\end{enumerate} +The two latter macro packages are part of CON\TeX{T} +(\Lfile{supp-pdf.tex} and \Lfile{supp-mis.tex}), but also work with +\LaTeX{} and are distributed separately. + +For new work, the MetaPost route is highly recommended. For the +future, Adobe have announced that they will define a specification for +`encapsulated PDF', and this should solve some of the present +difficulties. + +\section{Macro packages supporting \pdftex} +\begin{itemize} +\item For \LaTeX{} users, Sebastian Rahtz' \Lpack{hyperref} package + has substantial support for \pdftex, and provides access to most of + its features. In the simplest case, the user merely needs to load + \Lpack{hyperref} with a `pdftex' option, and all cross-references + will be converted to PDF hypertext links. PDF output is + automatically selected, text compression turned on, and the page + size is set up correctly. Bookmarks are created to match the table + of contents. +\item The standard \LaTeX{} \Lpack{graphics} and \Lpack{color} + packages have \texttt{pdftex} options, which allow use of normal + color, text rotation, and graphics inclusion commands. Only PNG + and MetaPost files can be included. +\item The Con\TeX{}T macro package by Hans Hagen + \Email{pragma@pi.net} has very full support for \pdftex{} in its + generalized hypertext features. +\item Hypertexted PDF from \texttt{texinfo} documents can be created + with \texttt{pdftexinfo.tex}, which is a slight modification of the + standard \texttt{texinfo} macros. This is part of the \pdftex{} + distribution. +\item A similiar modification of the \texttt{webmac}, called + \texttt{pdfwebmac.tex}, allows production of hypertexted PDF versions of + program written in WEB. This is part of the \pdftex{} distribution. +\end{itemize} +Some nice samples of \pdftex{} output can be found on the TUG +Web server, at \url{http://www.tug.org/applications/pdftex/}. + +\end{Article} + |