%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Contents: Specialities of the LaTeX system % $Id: spec.tex 536 2015-06-26 06:41:33Z oetiker $ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Specialities} \begin{intro} When putting together a large document, \LaTeX{} will help with some special features like index generation, bibliography management, and other things. A much more complete description of specialities and enhancements possible with \LaTeX{} can be found in the {\normalfont\manual{}} and {\normalfont \companion}. \end{intro} \section{Including \EPSi{}}\label{eps} \LaTeX{} provides the basic facilities to work with floating bodies, such as images or graphics, with the \texttt{figure} and \texttt{table} environments. There are several ways to generate the actual \wi{graphics} with basic \LaTeX{} or a \LaTeX{} extension package, a few of them are described in chapter \ref{chap:graphics}. Please refer to \companion{} and the \manual{} for more information on that subject. A much easier way to get graphics into a document is to generate them with a specialised software package\footnote{Such as XFig, Gnuplot, Gimp, Xara X \ldots} and then include the finished graphics in the document. Here again, \LaTeX{} packages offer many ways to do this, but this introduction will only discuss the use of \EPSi{} (EPS) graphics, because it is quite easy to do and widely used. In order to use pictures in the EPS format, you must have a \PSi{} printer\footnote{Another possibility to output \PSi{} is the \textsc{\wi{GhostScript}} program available from \CTAN|support/ghostscript|. Windows and OS/2 users might want to look for \textsc{GSview}.} available for output. A good set of commands for inclusion of graphics is provided in the \pai{graphicx} package by D.~P.~Carlisle. It is part of a whole family of packages called the ``graphics'' bundle.\footnote{\CTAN|pkg/graphics|} When working on a system with a \PSi{} printer available for output and with the \textsf{graphicx} package installed, use the following step by step guide to include a picture into your document: \begin{enumerate} \item Export the picture from your graphics program in EPS format.\footnote{If your software cannot export into EPS format, you can try to install a \PSi{} printer driver (such as an Apple LaserWriter, for example) and then print to a file with this driver. With some luck this file will be in EPS format. Note that an EPS must not contain more than one page. Some printer drivers can be explicitly configured to produce EPS format.} \item Load the \textsf{graphicx} package in the preamble of the input file with \begin{lscommand} \verb|\usepackage[|\emph{driver}\verb|]{graphicx}| \end{lscommand} \noindent where \emph{driver} is the name of your ``dvi to \PSi{}'' converter program. The most widely used program is called \texttt{dvips}. The name of the driver is required, because there is no standard on how graphics are included in \TeX{}. Knowing the name of the \emph{driver}, the \textsf{graphicx} package can choose the correct method to insert information about the graphics into the \eei{.dvi}~file, so that the printer understands it and can correctly include the \eei{.eps} file. \item Use the command \begin{lscommand} \ci{includegraphics}\verb|[|\emph{key}=\emph{value}, \ldots\verb|]{|\emph{file}\verb|}| \end{lscommand} \noindent to include \emph{file} into your document. The optional parameter accepts a comma separated list of \emph{keys} and associated \emph{values}. The \emph{keys} can be used to alter the width, height and rotation of the included graphic. Table~\ref{keyvals} lists the most important keys. \end{enumerate} \begin{table}[htb] \caption{Key Names for \textsf{graphicx} Package.} \label{keyvals} \begin{lined}{9cm} \begin{tabular}{@{}ll} \texttt{width}& scale graphic to the specified width\\ \texttt{height}& scale graphic to the specified height\\ \texttt{angle}& rotate graphic counterclockwise\\ \texttt{scale}& scale graphic \\ \end{tabular} \bigskip \end{lined} \end{table} \pagebreak The following example code may help to clarify things: \begin{code} \begin{verbatim} \begin{figure} \centering \includegraphics[angle=90, width=0.5\textwidth]{test} \caption{This is a test.} \end{figure} \end{verbatim} \end{code} It includes the graphic stored in the file \texttt{test.eps}. The graphic is \emph{first} rotated by an angle of 90 degrees and \emph{then} scaled to the final width of 0.5 times the width of a standard paragraph. The aspect ratio is $1.0$, because no special height is specified. The width and height parameters can also be specified in absolute dimensions. Refer to Table~\ref{units} on page~\pageref{units} for more information. If you want to know more about this topic, make sure to read \cite{graphics} and \cite{eps}. \section{Bibliography} Produce a \wi{bibliography} with the \ei{thebibliography} environment. Each entry starts with \begin{lscommand} \ci{bibitem}\verb|[|\emph{label}\verb|]{|\emph{marker}\verb|}| \end{lscommand} The \emph{marker} is then used to cite the book, article or paper within the document. \begin{lscommand} \ci{cite}\verb|{|\emph{marker}\verb|}| \end{lscommand} If you do not use the \emph{label} option, the entries will get enumerated automatically. The parameter after the \verb|\begin{thebibliography}| command defines how much space to reserve for the number of labels. In the example below, \verb|{99}| tells \LaTeX{} to expect that none of the bibliography item numbers will be wider than the number 99. \enlargethispage{2cm} \begin{example} Partl~\cite{pa} has proposed that \ldots \begin{thebibliography}{99} \bibitem{pa} H.~Partl: \emph{German \TeX}, TUGboat Volume~9, Issue~1 (1988) \end{thebibliography} \end{example} \chaptermark{Specialities} % w need to fix the damage done by the %bibliography example. \thispagestyle{fancyplain} For larger projects, you might want to check out the Bib\TeX{} program. Bib\TeX{} is included with most \TeX{} distributions. It allows you to maintain a bibliographic database and then extract the references relevant to things you cited in your paper. The visual presentation of Bib\TeX{}-generated bibliographies is based on a style-sheets concept that allows you to create bibliographies following a wide range of established designs. \section{Indexing} \label{sec:indexing} A very useful feature of many books is their \wi{index}. With \LaTeX{} and the support program \texttt{makeindex},\footnote{On systems not necessarily supporting filenames longer than 8~characters, the program may be called \texttt{makeidx}.} an index can be generated quite easily. This introduction will only explain the basic index generation commands. For a more in-depth view, please refer to \companion. \index{makeindex program} \index{makeidx package} To enable their indexing feature of \LaTeX{}, the \pai{makeidx} package must be loaded in the preamble with \begin{lscommand} \verb|\usepackage{makeidx}| \end{lscommand} \noindent and the special indexing commands must be enabled by putting the \begin{lscommand} \ci{makeindex} \end{lscommand} \noindent command in the preamble. The content of the index is specified with \begin{lscommand} \ci{index}\verb|{|\emph{key}@\emph{formatted\_entry}\verb|}| \end{lscommand} \noindent commands, where \emph{formatted\_entry} will appear in the index and \emph{key} will be used for sorting. The \emph{formatted\_entry} is optional. If it is missing the \emph{key} will be used. You enter the index commands at the points in the text that you want the final index entries to point to. Table~\ref{index} explains the syntax with several examples. \begin{table}[!tp] \caption{Index Key Syntax Examples.} \label{index} \begin{center} \begin{tabular}{@{}lll@{}} \textbf{Example} &\textbf{Index Entry} &\textbf{Comment}\\\hline \rule{0pt}{1.05em}\verb|\index{hello}| &hello, 1 &Plain entry\\ \verb|\index{hello!Peter}| &\hspace*{2ex}Peter, 3 &Subentry under `hello'\\ \verb|\index{Sam@\textsl{Sam}}| &\textsl{Sam}, 2& Formatted entry\\ \verb|\index{Lin@\textbf{Lin}}| &\textbf{Lin}, 7& Formatted entry\\ \verb|\index{Kaese@K\"ase}| &\textbf{K\"ase}, 33& Formatted entry\\ \verb.\index{ecole@\'ecole}. &\'ecole, 4& Formatted entry\\ \verb.\index{Jenny|textbf}. &Jenny, \textbf{3}& Formatted page number\\ \verb.\index{Joe|textit}. &Joe, \textit{5}& Formatted page number \end{tabular} \end{center} \end{table} When the input file is processed with \LaTeX{}, each \verb|\index| command writes an appropriate index entry, together with the current page number, to a special file. The file has the same name as the \LaTeX{} input file, but a different extension (\verb|.idx|). This \eei{.idx} file can then be processed with the \texttt{makeindex} program: \begin{lscommand} \texttt{makeindex} \emph{filename} \end{lscommand} The \texttt{makeindex} program generates a sorted index with the same base file name, but this time with the extension \eei{.ind}. If now the \LaTeX{} input file is processed again, this sorted index gets included into the document at the point where \LaTeX{} finds \begin{lscommand} \ci{printindex} \end{lscommand} The \pai{showidx} package that comes with \LaTeXe{} prints out all index entries in the left margin of the text. This is quite useful for proofreading a document and verifying the index. Note that the \ci{index} command can affect your layout if not used carefully. \begin{example} My Word \index{Word}. As opposed to Word\index{Word}. Note the position of the full stop. \end{example} \texttt{makeindex} has no clue about characters outside the ASCII range. To get the sorting correct, use the \verb|@| character as shown in the K\"ase and \'ecole examples above. \section{Fancy Headers} \label{sec:fancy} The \pai{fancyhdr} package,\footnote{Available from \CTAN|macros/latex/contrib/supported/fancyhdr|.} written by Piet van Oostrum, provides a few simple commands that allow you to customize the header and footer lines of your document. Look at the top of this page, for an application of this package. \begin{figure}[!htbp] \begin{lined}{\textwidth} \begin{verbatim} \documentclass{book} \usepackage{fancyhdr} \pagestyle{fancy} % with this we ensure that the chapter and section % headings are in lowercase. \renewcommand{\chaptermark}[1]{% \markboth{#1}{}} \renewcommand{\sectionmark}[1]{% \markright{\thesection\ #1}} \fancyhf{} % delete current header and footer \fancyhead[LE,RO]{\bfseries\thepage} \fancyhead[LO]{\bfseries\rightmark} \fancyhead[RE]{\bfseries\leftmark} \renewcommand{\headrulewidth}{0.5pt} \renewcommand{\footrulewidth}{0pt} \addtolength{\headheight}{0.5pt} % space for the rule \fancypagestyle{plain}{% \fancyhead{} % get rid of headers on plain pages \renewcommand{\headrulewidth}{0pt} % and the line } \end{verbatim} \end{lined} \caption{Example \pai{fancyhdr} Setup.} \label{fancyhdr} \end{figure} The tricky problem when customising headers and footers is to get things like running section and chapter names in there. \LaTeX{} accomplishes this with a two-stage approach. In the header and footer definition, you use the commands \ci{rightmark} and \ci{leftmark} to represent the current section and chapter heading, respectively. The values of these two commands are overwritten whenever a chapter or section command is processed. For ultimate flexibility, the \verb|\chapter| command and its friends do not redefine \ci{rightmark} and \ci{leftmark} themselves. They call yet another command (\ci{chaptermark}, \ci{sectionmark}, or \ci{subsectionmark}) that is responsible for redefining \ci{rightmark} and \ci{leftmark}. If you want to change the look of the chapter name in the header line, you need only ``renew'' the \ci{chaptermark} command. \cih{sectionmark}\cih{subsectionmark} Figure~\ref{fancyhdr} shows a possible setup for the \pai{fancyhdr} package that makes the headers look about the same as they look in this booklet. In any case, I suggest you fetch the documentation for the package at the address mentioned in the footnote. \section{The Verbatim Package} Earlier in this book, you got to know the \ei{verbatim} \emph{environment}. In this section, you are going to learn about the \pai{verbatim} \emph{package}. The \pai{verbatim} package is basically a re-implementation of the \ei{verbatim} environment that works around some of the limitations of the original \ei{verbatim} environment. This by itself is not spectacular, but the implementation of the \pai{verbatim} package added new functionality, which is why I am mentioning the package here. The \pai{verbatim} package provides the \begin{lscommand} \ci{verbatiminput}\verb|{|\emph{filename}\verb|}| \end{lscommand} \noindent command, which allows you to include raw ASCII text into your document as if it were inside a \ei{verbatim} environment. As the \pai{verbatim} package is part of the `tools' bundle, you should find it pre-installed on most systems. If you want to know more about this package, make sure to read \cite{verbatim}. \section{Installing Extra Packages}\label{sec:Packages} Most \LaTeX{} installations come with a large set of pre-installed style packages, but many more are available on the net. The main place to look for style packages on the Internet is CTAN (\url{http://www.ctan.org/}). Packages such as \pai{geometry}, \pai{hyphenat}, and many others are typically made up of two files: a file with the extension \texttt{.ins} and another with the extension \texttt{.dtx}. There will often be a \texttt{readme.txt} with a brief description of the package. You should of course read this file first. In any event, once you have copied the package files onto your machine, you still have to process them in a way that (a) tells your \TeX\ distribution about the new style package and (b) gives you the documentation. Here's how you do the first part: \begin{enumerate} \item Run \LaTeX{} on the \texttt{.ins} file. This will extract a \eei{.sty} file. \item Move the \eei{.sty} file to a place where your distribution can find it. Usually this is in your \texttt{\ldots/\emph{localtexmf}/tex/latex} subdirectory (Windows or OS/2 users should feel free to change the direction of the slashes). \item Refresh your distribution's file-name database. The command depends on the \LaTeX distribution you use: \TeX{}live -- \texttt{texhash}; web2c -- \texttt{maktexlsr}; MiK\TeX{} -- \texttt{initexmf -{}-update-fndb} or use the GUI. \end{enumerate} \noindent Now extract the documentation from the \texttt{.dtx} file: \begin{enumerate} \item Run \LaTeX\ on the \texttt{.dtx} file. This will generate a \texttt{.dvi} file. Note that you may have to run \LaTeX\ several times before it gets the cross-references right. \item Check to see if \LaTeX\ has produced a \texttt{.idx} file among the various files you now have. If you do not see this file, then the documentation has no index. Continue with step~\ref{step:final}. \item In order to generate the index, type the following:\\ \fbox{\texttt{makeindex -s gind.ist \textit{name}}}\\ (where \textit{name} stands for the main-file name without any extension). \item Run \LaTeX\ on the \texttt{.dtx} file once again. \label{step:next} \item Last but not least, make a \texttt{.ps} or \texttt{.pdf} file to increase your reading pleasure.\label{step:final} \end{enumerate} Sometimes you will see that a \texttt{.glo} (glossary) file has been produced. Run the following command between step~\ref{step:next} and~\ref{step:final}: \noindent\texttt{makeindex -s gglo.ist -o \textit{name}.gls \textit{name}.glo} \noindent Be sure to run \LaTeX\ on the \texttt{.dtx} one last time before moving on to step~\ref{step:final}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Contents: Chapter on pdfLaTeX % French original by Daniel Flipo 14/07/2004 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Working with pdf\LaTeX} \label{sec:pdftex}\index{PDF} \secby{Daniel Flipo}{Daniel.Flipo@univ-lille1.fr}% PDF is a portable \wi{hypertext} document format. Much as in a web page, some words in the document are marked as hyperlinks. They link to other places in the document or even to other documents. If you click on such a hyperlink you get transported to the destination of the link. In the context of \LaTeX{}, this means that all occurrences of \ci{ref} and \ci{pageref} become hyperlinks. Additionally, the table of contents, the index and all the other similar structures become collections of hyperlinks. Most web pages you find today are written in HTML \emph{(HyperText Markup Language)}. This format has two significant disadvantages when writing scientific documents: \begin{enumerate} \item Including mathematical formulae into HTML documents is not generally supported. While there is a standard for it, most browsers used today do not support it, or lack the required fonts. \item Printing HTML documents is possible, but the results vary widely between platforms and browsers. The results are miles removed from the quality we have come to expect in the \LaTeX{} world. \end{enumerate} There have been many attempts to create translators from \LaTeX{} to HTML. Some were even quite successful in the sense that they are able to produce legible web pages from a standard \LaTeX{} input file. But all of them cut corners left and right to get the job done. As soon as you start using more complex \LaTeX{} features and external packages things tend to fall apart. Authors wishing to preserve the unique typographic quality of their documents even when publishing on the web turn to PDF \emph{(Portable Document Format)}, which preserves the layout of the document and permits hypertext navigation. Most modern browsers come with plugins that allow the direct display of PDF documents. Even though there are DVI and PS viewers for almost every platform, you will find that \wi{Acrobat Reader} and \wi{Xpdf} for viewing PDF documents are more widely deployed\footnote{\url{http://pdfreaders.org}}. So providing PDF versions of your documents will make them much more accessible to your potential readers. \subsection{PDF Documents for the Web} The creation of a PDF file from \LaTeX{} source is very simple, thanks to the pdf\TeX{} program developed by H\`an~Th\'{\^e}~Th\`anh. pdf\TeX{} produces PDF output where normal \TeX{} produces DVI. There is also a pdf\LaTeX{}, which produces PDF output from \LaTeX{} sources. \index{pdftex@pdf\TeX}\index{pdftex@pdf\LaTeX} Both pdf\TeX{} and pdf\LaTeX{} are installed automatically by most modern \TeX{} distributions, such as te\TeX{}, fp\TeX{}, Mik\TeX, \TeX{}Live and CMac\TeX{}. To produce a PDF instead of DVI, it is sufficient to replace the command \texttt{latex file.tex} by \texttt{pdflatex file.tex}. On systems where \LaTeX{} is not called from the command line, you may find a special button in the \TeX{} GUI. Set the paper size with an optional documentclass argument such as \texttt{a4paper} or \texttt{letterpaper}. This works in pdf\LaTeX{} too, but on top of this pdf\TeX{} also needs to know the physical size of the paper to determine the physical size of the pages in the pdf file. \index{paper size} If you use the \pai{hyperref} package (see page \pageref{ssec:pdfhyperref}), the papersize will be adjusted automatically. Otherwise you have to do this manually by putting the following lines into the preamble of the document: \begin{code} \begin{verbatim} \pdfpagewidth=\paperwidth \pdfpageheight=\paperheight \end{verbatim} \end{code} The following section will go into more detail regarding the differences between normal \LaTeX{} and pdf\LaTeX{}. The main differences concern three areas: the fonts to use, the format of images to include, and the manual configuration of hyperlinks. \subsection{The Fonts} \wi{pdf\LaTeX} can deal with all sorts of fonts (PK bitmaps, TrueType, \PSi{} type~1\dots) but the normal \LaTeX{} font format, the bitmap PK fonts produce very ugly results when the document is displayed with Acrobat Reader. It is best to use \PSi{} Type 1 fonts exclusively to produce documents that display well. \emph{Modern TeX installations will be set up so that this happens automatically. Best is to try. If it works for you, just skip this whole section.} The Type 1 font set most widely used today is called Latin Modern (LM). If you have a recent \TeX{} installation, chances are that you already have a copy of them installed; all you need to do is to add \begin{code} \begin{verbatim} \usepackage{lmodern} \usepackage[T1]{fontenc} \usepackage{textcomp} \end{verbatim} \end{code} to the preamble of your document and you are all set for creating excellent PDF output with full support for the full Latin character set. If you are working with a stripped down setup, you may have to add the lm fonts explicitly. For the Russian language you may want to use C1 virtual fonts, available at \texttt{ftp://ftp.vsu.ru/pub/tex/font-packs/c1fonts}. These fonts combine the standard CM type~1 fonts from Bluesky collection and CMCYR type~1 fonts from the Paradissa and BaKoMa collection, all available on CTAN. Because Paradissa fonts contain only Russian letters, C1 fonts are missing other Cyrillic glyphs. Another solution is to switch to other \PSi{} type~1 fonts. Actually, some of them are even included with every copy of Acrobat Reader. Because these fonts have different character sizes, the text layout on your pages will change. Generally these other fonts will use more space than the CM fonts, which are very space-efficient. Also, the overall visual coherence of your document will suffer because Times, Helvetica and Courier (the primary candidates for such a replacement job) have not been designed to work in harmony in a single document. Two ready-made font sets are available for this purpose: \pai{pxfonts}, which is based on \emph{Palatino} as its main text body font, and the \pai{txfonts} package, which is based on \emph{Times}. To use them it is sufficient to put the following lines into the preamble of your document: \begin{code} \begin{verbatim} \usepackage[T1]{fontenc} \usepackage{pxfonts} \end{verbatim} \end{code} You may find lines like \begin{verbatim} Warning: pdftex (file eurmo10): Font eur... not found \end{verbatim} in the \texttt{.log} file after compiling your input file. They mean that some font used in the document has not been found. Make sure you identify and fix the offending parts of your document, as the resulting PDF document may \emph{not display the pages with the missing characters at all}. \subsection{Using Graphics} \label{ssec:pdfgraph} Including graphics into a document works best with the \pai{graphicx} package (see page~\pageref{eps}): \begin{code} \begin{verbatim} \usepackage{xcolor,graphicx} \end{verbatim} \end{code} In the sample above I have included the color package, as using color in documents displayed on the web comes quite naturally. So much for the good news. The bad news is that graphics in \EPSi{} format do not work with pdf\LaTeX{}. If you don't define a file extension in the \ci{includegraphics} command, \pai{graphicx} will go looking for a suitable file on its own, depending on the setting of the \emph{driver} option. For \texttt{pdftex} this is formats \texttt{.png}, \texttt{.pdf}, \texttt{.jpg} and \texttt{.mps} (\MP\index{metapost@\MP})---but \emph{not} \texttt{.eps}. The simple way out of this problem is to just convert your EPS files into PDF format using the \texttt{epstopdf} utility found on many systems. For vector graphics (drawings) this is a great solution. For bitmaps (photos, scans) this is not ideal, because the PDF format natively supports the inclusion of PNG and JPEG images. PNG is good for screenshots and other images with few colours. JPEG is great for photos, as it is very space-efficient. It may even be desirable not to draw certain geometric figures, but rather describe the figure with a specialized command language, such as \MP\index{metapost@\MP}, which can be found in most \TeX{} distributions, and comes with its own extensive manual. \subsection{Hypertext Links} \label{ssec:pdfhyperref} The \pai{hyperref} package will take care of turning all internal references of your document into hyperlinks. For this to work properly some magic is necessary, so you have to put \verb+\usepackage[pdftex]{hyperref}+ as the \emph{last} command into the preamble of your document. Many options are available to customize the behaviour of the \pai{hyperref} package: \begin{itemize} \item either as a comma separated list after the pdftex option\\ \verb+\usepackage[pdftex]{hyperref}+ \item or on individual lines with the command \verb+\hypersetup{+\emph{options}\verb+}+. \end{itemize} The only required option is \texttt{pdftex}; the others are optional and allow you to change the default behaviour of hyperref.\footnote{It is worth noting that the \pai{hyperref} package is not limited to work with pdf\TeX{}. It can also be configured to embed PDF-specific information into the DVI output of normal \LaTeX{}, which then gets put into the PS file by \texttt{dvips} and is finally picked up by the pdf convertor when turning the PS file into PDF.} In the following list the default values are written in an upright font. \begin{flushleft} \begin{description} \item [\texttt{bookmarks (=true,\textit{false})}] show or hide the bookmarks bar when displaying the document \item [\texttt{unicode (=false,\textit{true})}] allows the use of characters of non-latin based languages in Acrobat's bookmarks \item [\texttt{pdftoolbar (=true,\textit{false})}] show or hide Acrobat's toolbar \item [\texttt{pdfmenubar (=true,\textit{false})}] show or hide Acrobat's menu \item [\texttt{pdffitwindow (=false,\textit{true})}] adjust the initial magnification of the PDF when displayed \item [\texttt{pdftitle (=\{text\})}] define the title that gets displayed in the \texttt{Document Info} window of Acrobat \item [\texttt{pdfauthor (=\{text\})}] the name of the PDF's author \item [\texttt{pdfnewwindow (=false,\textit{true})}] define whether a new window should be opened when a link leads out of the current document \item [\texttt{colorlinks (=false,\textit{true})}] surround the links by colour frames (\texttt{false}) or colour the text of the links (\texttt{true}). The colour of these links can be configured using the following options (default colours are shown): \begin{description} \item [\texttt{linkcolor (=red)}] colour of internal links (sections, pages, etc.) \item [\texttt{citecolor (=green)}] colour of citation links (bibliography) \item [\texttt{filecolor (=magenta)}] colour of file links \item [\texttt{urlcolor (=cyan)}] colour of URL links (mail, web) \end{description} \end{description} \end{flushleft} If you are happy with the defaults, use \begin{code} \begin{verbatim} \usepackage[pdftex]{hyperref} \end{verbatim} \end{code} To have the bookmark list open and links in colour (the \texttt{=true} values are optional): \begin{code} \begin{verbatim} \usepackage[pdftex,bookmarks,colorlinks]{hyperref} \end{verbatim} \end{code} When creating PDFs destined for printing, coloured links are not a good thing as they end up in gray in the final output, making it difficult to read. Use colour frames, which are not printed: \begin{code} \begin{verbatim} \usepackage{hyperref} \hypersetup{colorlinks=false} \end{verbatim} \end{code} \noindent or make links black: \begin{code} \begin{verbatim} \usepackage{hyperref} \hypersetup{colorlinks,% citecolor=black,% filecolor=black,% linkcolor=black,% urlcolor=black,% pdftex} \end{verbatim} \end{code} When you just want to provide information for the \texttt{Document Info} section of the PDF file: \begin{code} \begin{verbatim} \usepackage[pdfauthor={Pierre Desproges},% pdftitle={Des femmes qui tombent},% pdftex]{hyperref} \end{verbatim} \end{code} \vspace{\baselineskip} In addition to the automatic hyperlinks for cross references, it is possible to embed explicit links using \begin{lscommand} \ci{href}\verb|{|\emph{url}\verb|}{|\emph{text}\verb|}| \end{lscommand} The code \begin{code} \begin{verbatim} The \href{http://www.ctan.org}{CTAN} website. \end{verbatim} \end{code} produces the output ``\href{http://www.ctan.org}{CTAN}''; a click on the word ``\textcolor{magenta}{CTAN}'' will take you to the CTAN website. If the destination of the link is not a URL but a local file, use the \ci{href} command without the 'http://' bit: \begin{verbatim} The complete document is \href{manual.pdf}{here} \end{verbatim} which produces the text ``The complete document is \textcolor{cyan}{here}''. A click on the word ``\textcolor{cyan}{here}'' will open the file \texttt{manual.pdf}. (The filename is relative to the location of the current document). The author of an article might want her readers to easily send email messages by using the \ci{href} command inside the \ci{author} command on the title page of the document: \begin{code} \begin{verbatim} \author{Mary Oetiker $<$\href{mailto:mary@oetiker.ch}% {mary@oetiker.ch}$>$ \end{verbatim} \end{code} Note that I have put the link so that my email address appears not only in the link but also on the page itself. I did this because the link\\ \verb+\href{mailto:mary@oetiker.ch}{Mary Oetiker}+\\ would work well within Acrobat, but once the page is printed the email address would not be visible anymore. \subsection{Problems with Links} Messages like the following: \begin{verbatim} ! pdfTeX warning (ext4): destination with the same identifier (name{page.1}) has been already used, duplicate ignored \end{verbatim} appear when a counter gets reinitialized, for example by using the command \ci{mainmatter} provided by the \texttt{book} document class. It resets the page number counter to~1 prior to the first chapter of the book. But as the preface of the book also has a page number~1 all links to ``page 1'' would not be unique anymore, hence the notice that ``\verb+duplicate+ has been \verb+ignored+.'' The counter measure consists of putting \texttt{plainpages=false} into the hyperref options. This unfortunately only helps with the page counter. An even more radical solution is to use the option\\ \texttt{hypertexnames=false}, but this will cause the page links in the index to stop working. \subsection{Problems with Bookmarks} The text displayed by bookmarks does not always look like you expect it to look. Because bookmarks are ``just text,'' fewer characters are available for bookmarks than for normal \LaTeX{} text. Hyperref will normally notice such problems and put up a warning: \begin{code} \begin{verbatim} Package hyperref Warning: Token not allowed in a PDFDocEncoded string: \end{verbatim} \end{code} Work around this problem by providing a text string for the bookmarks, which replaces the offending text: \begin{lscommand} \ci{texorpdfstring}\verb|{|\emph{\TeX{} text}\verb|}{|\emph{Bookmark Text}\verb|}| \end{lscommand} Math expressions are a prime candidate for this kind of problem: \begin{code} \begin{verbatim} \section{\texorpdfstring{$E=mc^2$}% {E = mc ** 2}} \end{verbatim} \end{code} which turns \verb+\section{$E=mc^2$}+ to ``E = mc ** 2'' in the bookmark area. If you write your document in Unicode and use the \verb+unicode+ option for the \pai{hyperref} package to use Unicode characters in bookmarks, this will give you a much larger selection of characters to pick from when when using \ci{texorpdfstring}. \subsection{Source Compatibility Between \LaTeX{} and pdf\LaTeX{}} \label{sec:pdfcompat} Ideally your document would compile equally well with \LaTeX{} and pdf\LaTeX{}. The main problem in this respect is the inclusion of graphics. The simple solution is to \emph{systematically drop} the file extension from \ci{includegraphics} commands. They will then automatically look for a file of a suitable format in the current directory. All you have to do is create appropriate versions of the graphics files. \LaTeX{} will look for \texttt{.eps}, and pdf\LaTeX{} will try to include a file with the extension \texttt{.png}, \texttt{.pdf}, \texttt{.jpg} or \texttt{.mps} (in that order). For the cases where you want to use different code for the PDF version of your document, simply add the package \pai{ifpdf}% \footnote{If you want the whole story on why to use this package then go to the \TeX{} FAQ under the item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ifpdf}.} to your preamble. Chances are that you already have it installed; if not then you're probably using MiK\TeX{} which will install it for you automatically the first time you try to use it. This package defines the special command \ci{ifpdf} that will allow you to write conditional code easily. In this example, we want the \PSi{} version to be black and white due to the printing costs but we want the PDF version for online viewing to be colourful. \begin{code} \begin{verbatim} \RequirePackage{ifpdf} % are we producing PDF ? \documentclass[a4paper,12pt]{book} \usepackage[latin1]{inputenc} \usepackage[T1]{fontenc} \usepackage{lmodern} \usepackage[bookmarks, % tune hyperref colorlinks, plainpages=false]{hyperref} \usepackage{graphicx} \ifpdf \hypersetup{linkscolor=blue} \else \hypersetup{linkscolors=black} \fi \usepackage[english]{babel} ... \end{verbatim} \end{code} In the example above I have included the \pai{hyperref} package even in the non-PDF version. The effect of this is to make the \ci{href} command work in all cases, which saves me from wrapping every occurrence into a conditional statement. Note that in recent \TeX{} distributions (like \TeX{}Live, Mac\TeX{} and MiK\TeX{}), the normal \TeX{} program is actually pdf\TeX{} and it will automatically switch between producing pdf and dvi according to the name it is called with: use the \verb|pdflatex| command to get pdf output and \verb|latex| for normal dvi output. \section{Working with \hologo{XeLaTeX}} \label{sec:xetex}\index{PDF}\index{XeTeX@\hologo{XeTeX}}\index{XeLaTeX@\hologo{XeLaTeX}} \secby{Axel Kielhorn}{A.Kielhorn@web.de}% Most of the things said about pdf\LaTeX\ are valid for \hologo{XeLaTeX} as well. There is a Wiki at \url{http://wiki.xelatex.org/doku.php} that collects information relevant to \hologo{XeTeX} and \hologo{XeLaTeX}. \subsection{The Fonts} In addition to the normal \texttt{tfm} based fonts, \hologo{XeLaTeX} is able to use any font known to the operating system. If you have the \texttt{Linux Libertine} fonts installed, you can simply say \begin{code} \begin{verbatim} \usepackage{fontspec} \setmainfont[Ligatures=TeX]{Linux Libertine} \end{verbatim} \end{code} % in the preamble. This will normally detect the italic and bold versions as well, so \verb|\textit| and \verb|\textbf| will work as usual. When the font is using OpenType technology you have access to many features which required switching to a separate font or using virtual fonts in the past. The main feature is the extended character set; a font may contain Latin, Greek and Cyrillic characters and the corresponding ligatures. Many fonts contain at least two kinds of numerals, the normal lining numerals and so called old style (or lower case) numerals, which partly extend below the baseline. They may contain proportional numerals (the ``1'' takes less space than the ``0'') or monospaced numerals which are suitable for tables. \begin{code} \begin{verbatim} \newfontfamily\LLln[Numbers=Lining]{(font)} \newfontfamily\LLos[Numbers=OldStyle]{(font)} \newfontfamily\LLlnm[Numbers=Lining,Numbers=Monospaced]{(font)} \newfontfamily\LLosm[Numbers=OldStyle,Numbers=Monospaced]{(font)} \end{verbatim} \end{code} Almost all OpenType fonts contain the standard ligatures (fl fi ffi) but there are also some rare or historical ligatures like st, ct and tz. You may not want to use them in a technical report but they are fine for a novel. To enable these ligatures use either of the following lines: \begin{code} \begin{verbatim} \setmainfont[Ligatures=Rare]{(font)} \setmainfont[Ligatures=Historic]{(font)} \setmainfont[Ligatures=Historic,Ligatures=Rare]{(font)} \end{verbatim} \end{code} Not every font contains both sets of ligature, consult the font documentation or just try it out. Sometimes these ligatures are language dependent; for example a ligature used in Polish (fk) is not used in English. You have to add \begin{code} \begin{verbatim} \setmainfont[Language=Polish]{(font)} \end{verbatim} \end{code} to enable the Polish ligatures. Some fonts (like the commercial Adobe Garamond Premier Pro) contain alternative glyphs that are activated by default in \hologo{XeLaTeX} distributed with \TeX Live~2010\footnote{The behavior has changed with this version, it was off by default in earlier releases.}. The result is a stylish ``Q'' with a descender reaching below the following ``u''. To disable this feature you have to define the font with disabled contextuals: \begin{code} \begin{verbatim} \setmainfont[Contextuals=NoAlternate]{(font)} \end{verbatim} \end{code} To learn about fonts in \hologo{XeLaTeX} read the \pai{fontspec} manual. \subsubsection{Where do I get OpenType fonts?} If you have \texttt{TeXLive} installed, you already have some at \url{.../texmf-dist/fonts/opentype}, just install them in your operating system. This collection does not include \texttt{DejaVu}, which is available at \url{http://dejavu-fonts.org/}. Make sure that each font is only installed \emph{once}, otherwise interesting results may happen. You can use every font installed on your computer, but remember that other users may not have these fonts. The Zapfino font used in the \pai{fontspec} manual is included in Mac OSX, but is not available on Windows computers.\footnote{A commercial version of the font called Zapfino Extra is available.} \subsubsection{Entering Unicode Characters} The number of characters in a font has grown but the number of keys on a regular keyboard has not. So, how do I enter non-ASCII characters? If you write a large amount of text in a foreign language, you can install a keyboard for that language and print out the character positions. (Most operatings system have some sort of virtual keyboard, just make a screenshot.) If you rarely need an exotic character, you can simply pick it in the character palette. Some environments (e.\,g. the X Window System) offer many methods to enter non-ASCII characters. Some editors (e.\,g. Vim and Emacs) offer ways to enter these characters. Read the manual for the tools you are using. \subsection{Compatibility Between \hologo{XeLaTeX} and \hologo{pdfLaTeX}} There are a few things that are different between \hologo{XeLaTeX} and \hologo{pdfLaTeX}. \begin{itemize} \item A \hologo{XeLaTeX} document has to be written in Unicode (UTF-8) while \hologo{pdfLaTeX} may use different input encodings. \item The \pai{microtype} packages does not work with \hologo{XeLaTeX} yet, support for character protrusion is already under development. \item Everything font related has to be reviewed. (Unless you want to stick to Latin Modern.) \end{itemize} \section{Creating Presentations} \label{sec:beamer} \secby{Daniel Flipo}{Daniel.Flipo@univ-lille1.fr} You can present the results of your scientific work on a blackboard, with transparencies, or directly from your laptop using some presentation software. \wi{pdf\LaTeX} combined with the \pai{beamer} class allows you to create presentations in PDF, looking much like something you might be able to generate with LibreOffice or PowerPoint if you had a very good day, but much more portable because PDF readers are available on many more systems. The \pai{beamer} class uses \pai{graphicx}, \pai{color} and \pai{hyperref} with options adapted to screen presentations. %La figure~\ref{fig:pdfscr} contient un exemple de fichier minimal à %compiler avec \wi{pdf\LaTeX} et le %résultat produit. % Écran capturé par ImageMagick (man ImageMagick) fonction « import » % et convertie en jpg toujours par ImageMagick. \begin{figure}[htbp] \begin{verbatim} \documentclass[10pt]{beamer} \mode{% \usetheme[hideothersubsections, right,width=22mm]{Goettingen} } \title{Simple Presentation} \author[D. Flipo]{Daniel Flipo} \institute{U.S.T.L. \& GUTenberg} \titlegraphic{\includegraphics[width=20mm]{USTL}} \date{2005} \begin{document} \begin{frame} \titlepage \end{frame} \section{An Example} \begin{frame} \frametitle{Things to do on a Sunday Afternoon} \begin{block}{One could \ldots} \begin{itemize} \item walk the dog\dots \pause \item read a book\pause \item confuse a cat\pause \end{itemize} \end{block} and many other things \end{frame} \end{document} \end{verbatim} \caption{Sample code for the \pai{beamer} class} \label{fig:code-beamer} \end{figure} When you compile the code presented in figure~\ref{fig:code-beamer} with \wi{pdf\LaTeX} you get a PDF file with a title page and a second page showing several items that will be revealed one at a time as you step though your presentation. One of the advantages of the beamer class is that it produces a PDF file that is directly usable without first going through a \PSi{} stage like \pai{prosper} or requiring additional post processing like presentations created with the \pai{ppower4} package. With the \pai{beamer} class you can produce several versions (modes) of your document from the same input file. The input file may contain special instructions for the different modes in angular brackets. The following modes are available: \begin{description} \item[beamer] for the presentation PDF discussed above. \item[trans] for transparencies. \item[handout] for the printed version. \end{description} The default mode is \texttt{beamer}, change it by setting a different mode as a global option, like \verb|\documentclass[10pt,handout]{beamer}| to print the handouts for example. The look of the screen presentation depends on the theme you choose. Pick one of the themes shipped with the beamer class or create your own. See the beamer class documentation in \texttt{beameruserguide.pdf} for more information on this. Let's have a closer look at the code in figure~\ref{fig:code-beamer}. For the screen version of the presentation \verb|\mode| we have chosen the \emph{Goettingen} theme to show a navigation panel integrated into the table of contents. The options allow us to choose the size of the panel (22~mm in this case) and its position (on the right side of the body text). The option \emph{hideothersubsections}, shows the chapter titles, but only the subsections of the present chapter. There are no special settings for \verb|\mode| and \verb|\mode|. They appear in their standard layout. The commands \verb|\title{}|, \verb|\author{}|, \verb|\institute{}|, and\\ \verb|\titlegraphic{}| set the content of the title page. The optional arguments of \verb|\title[]{}| and \verb|\author[]{}| let you specify a special version of the title and the author name to be displayed on the panel of the \emph{Goettingen} theme. The titles and subtitles in the panel are created with normal \verb|\section{}| and \verb|\subsection{}| commands that you place \emph{outside} the \ei{frame} environment. The tiny navigation icons at the bottom of the screen also allow to navigate the document. Their presence is not dependent on the theme you choose. The contents of each slide or screen has to be placed inside a \ei{frame} environment. There is an optional argument in angular brackets (\verb|<| and \verb|>|), it allows us to suppress a particular frame in one of the versions of the presentation. In the example the first page would not be shown in the handout version due to the \verb|| argument. It is highly recommended to set a title for each slide apart from the title slide. This is done with the command \verb|\frametitle{}|. If a subtitle is necessary use the \ei{block} environment as shown in the example. Note that the sectioning commands \verb|\section{}| and \verb|\subsection{}| do not produce output on the slide proper. The command \verb|\pause| in the itemize environment lets you reveal the items one by one. For other presentation effects check out the commands \verb|\only|, \verb|\uncover|, \verb|\alt| and \verb|\temporal|. In many place it is possible to use angular brackets to further customize the presentation. In any case make sure to read through the beamer class documentation \texttt{beameruserguide.pdf} to get a complete picture of what is in store for you. This package is being actively developed, check out their website to get the latest information. (\href{http://latex-beamer.sourceforge.net/}{http://latex-beamer.sourceforge.net/}) % Local Variables: % TeX-master: "lshort2e" % mode: latex % mode: flyspell % End: