There are four steps to installing a LaTeX package:
1. Extract the files Run LaTeX on the .ins file. That is, open the file in your editor and process it as if it were a LaTeX document (which it is), or if you prefer, type latex followed by the .ins filename in a command window in your temporary directory. This will extract all the files needed from the .dtx file (which is why you must have both of them present in the temporary directory). Note down or print the
185
names of the files created if there are a lot of them (read the log file if you want to see their names again).
2. Create the documentation Run LaTeX on the .dtx file. You might need to run it twice or more, to get the cross-references right (just like any other LaTeX document). This will create a .dvi file of documentation explaining what the package is for and how to use it. If you prefer to create PDF then run pdfLaTeX instead. If you created a .idx as well, it means that the document contains an index, too. If you want the index to be created properly, follow the steps in theindexing section. Sometimes you will see that a .glo (glossary) file has been produced. Run the following command instead:
makeindex -s gglo.ist -o name.gls name.glo
3. Install the files While the documentation is printing, move or copy the files created in step 1 from your temporary directory to the right place[s] in your TeX local installation directory tree — always your ’local’ directory tree, a) to prevent your new package accidentally overwriting files in the main TeX directories; and b) to avoid your newly-installed files being overwritten when you next update your ver-sion of TeX. The “right place” sometimes causes confuver-sion, especially if your TeX installation is old or does not conform to the TeX Directory Structure. For a TDS-conformant system, this is either a) for LaTeX packages, a suitably-named subdirectory of texmf-local/tex/latex/; or b) a suitably-named sub-directory of texmf-local/
for files like BIBTeX styles which are not just for LaTeX but can be used in other TeX systems. “Suitably-named” means sensible and meaningful (and probably short). For a package like paralist, for example, I’d call the directory paralist. Often there is just a .sty file to move but in the case of complex packages there may be more, and they may belong in different locations. For example, new BibTeX packages or font packages will typically have several files to install. This is why it is a good idea to create a sub-directory for the package rather than dump the files into misc along with other unrelated stuff. If there are configuration or other files, read the documentation to find out if there is a special or preferred location to move them to.
4. Update your index Finally, run your TeX indexer program to update the package database. This program comes with every modern version of TeX and is variously called depending on the LaTeX distribution you use (Read the documentation that came with your installation to find out which it is):
• teTeX, fpTeX: texhash
• web2c: mktexlsr
• MikTeX: initexmf -update-fndb (or use the GUI)
This last step is utterly essential, otherwise nothing will work.
The reason this process has not been automated widely is that there are still thousands of installations which do not conform to the TDS, such as old shared Unix systems and some Microsoft Windows systems, so there is no way for an installation program to guess where to put the files: you have to know this. There are also systems where the owner, user, or installer has chosen not to follow the recommended TDS directory structure, or is unable to do so for political or security reasons (such as a shared system where she cannot write to a protected directory). The reason for having the texmf-local directory (called texmf.local on some systems) is to provide a place for local modifications or personal updates, especially if you are a user on a shared or managed system (Unix, Linux, VMS, Windows NT/2000/XP, etc.) where you may not have write-access to the main TeX installation directory tree. You can also have a personal texmf subdirectory in your own login directory. Your installation must be configured to look in these directories first, however, so that any updates to standard packages will be found there before the superseded copies in the main texmf tree. All modern TeX installations should do this anyway, but if not, you can edit texmf/web2c/texmf.cnf yourself.
Type Directory (under texmf-local/) Description
.cls tex/latex/base Document class file
.sty tex/latex/packagename Style file: the normal package content .bst bibtex/bst/packagename BibTeX style
.mf fonts/source/public/typeface METAFONT outline
.fd tex/latex/mfnfss Font Definition files for METAFONT fonts
.fd tex/latex/psnfss Font Definition files for PostScript Type 1 fonts
.pfb /fonts/type1/foundry/typeface PostScript Type 1 outline
.afm /fonts/afm/foundry/typeface Adobe Font Metrics for Type 1 fonts .tfm /fonts/tfm/foundry/typeface TeX Font Metrics for METAFONT and
Type 1 fonts .vf /fonts/vf/foundry/typeface TeX virtual fonts
.dvi /doc package documentation
.pdf /doc package documentation
others tex/latex/packagename other types of file unless instructed oth-erwise
Table 20.1: Where to put files from packages
Chapter 21
Color
The package color adds the support for colored text: LaTeX does not support it by default. The best approach is to define the colors you want to use at the beginning of your document and then you can reference them whenever you want. For example, you can use them to type colored text or as an argument of another package that supports colors as arguments (for example, see thelistingspackage). There are some standard colors that are already defined within the package, they are white, black, red, green, blue, cyan, magenta, yellow; you can reference them simply typing their name. You can define your own colors with:
\definecolor{name}{model}{color-spec}
• name is the name of the color; you can call it as you like
• model is the way you describe the color
• color-spec is the description of the color
The models you can use to describe the color are the following:
189
model: description: color-spec: example:
gray you can only define shades of gray
just one number between 0 (black) and 1 (white), so 0.95 will be very light gray, 0.30 will be dark gray
\definecolor{light-gray}{gray}{0.95}
rgb you refer to the Red-Green-B lue model
three number given in the form red,green,blue; the quantity of each color is represented with a num-ber between 0 and 1
\definecolor{orange}
{rgb}{1,0.5,0}
cmyk you refer to the C yan M agenta
The simplest way to type colored text is by:
\textcolor{declared-color}{text}
where declared-color is a color that was defined before by \definecolor. Another possible way is by
\color{declared-color}
that will switch the standard text color to the color you want. It will work until the end of the current TeX group. For example:
this is standard black text, {\color{red} this will look red}, and this will look black again.
The difference between \textcolor and \color is the same difference between \texttt and \ttfamily, you can use the one you prefer.
Finally, you can also change the background color of the whole page by:
\pagecolor{declared-color}
Chapter 22
Hyperref
The package hyperref provides LaTeX the ability to create hyperlinks within the document. It works with pdflatex and also with standard “latex” used with dvips and ghostscript or dvipdfm to build a PDF file. If you load it, you will have the possibility to include interactive external links and all your internal references will be turned to hyperlinks. The compiler pdflatex makes it possible to create PDF files directly from the LaTeX source, and PDF supports more features than DVI. In particular PDF supports hyperlinks, and the only way to introduce them in LaTeX is using hyperref.
Moreover, PDF can contain other information about a document such as the title, the author, etc., and you can edit those using this same package.
Usage
The basic usage with the standard settings is straightforward. Just load the package in the preamble, at the end of all the other packages but prior to other settings:
\usepackage{hyperref}
This will automatically turn all your internal references into hyperlinks. It won’t affect the way to write your documents: just keep on using the standard \label/\ref system; with hyperref those “connections” will become links and you will be able to click on them to be redirected to the right page. Moreover the table of contents, list of figures/tables and index will be made of hyperlinks, too.
The package provides three useful commands for inserting links pointing outside the document:
• \hyperref[label name]{link text}: this will have the same effect as
\ref{label name} but will make the text link text a full link, instead. The two can be combined, for example in
we use \hyperref[mainlemma]{lemma \ref{mainlemma}}
If the lemma labelled as “mainlemma” was number 4.1.1, then the outputted text would be “we use lemma 4.1.1” with the hyperlink as expected.
191
• \url{my url}: it will show the URL using a mono-spaced font and, if you click on it, your browser will be opened pointing at it.
• \href{my url}{description}: it will show the string “description” using stan-dard document font but, if you click on it, your browser will be opened pointing at “my url”. Here is an example:
\url{http://www.wikibooks.org}
\href{http://www.wikibooks.org}{wikibooks home}
both point at the same page, but in the first case the URL will be shown, while in the second case the URL will be hidden. Note that, if you print your document, the link stored using \href will not be shown anywhere in the document. You can use relative paths to link documents near the location of your current document; in order to do so, use the standard unix-like notation (./ is the current directory, ../ is the previous directory, etc.)
A possible way to insert emails is by
\textbackslash{}href\{mailto:my\[email protected]\}
\{my\[email protected]\}
it just shows your email address (so people can know it even if the document is printed on paper) but, if the reader clicks on it, (s)he can easily send you an email.
Or, to incorporate the url package’s formatting and line breaking abilities into the displayed text, use1
\textbackslash{}href\{mailto:my\[email protected]\}
\{\textbackslash{}nolinkurl\{my\[email protected]\}\}
When using this form, note that the \nolinkurl command is fragile and if the hy-perlink is inside of a moving argument, it must be preceeded by a \protect command.
Customization
The standard settings should be fine for most users, but if you want to change some-thing, you can easily do it. There are several variables you can change and there are two methods to pass those to the package. You can pass the options as an argument of the package when you load it (that’s the standard way packages work), or you can use the \hypersetup package:
\hypersetup{option1, option2}
you can pass as many options as you want, separate them with a comma. Those options have to be in the form:
variable_name=new_value
1Email link with hyperref, url packages — comp.text.tex User Group
exactly the same format has to be used if you pass those options to the package while loading it, like this:
\usepackage[pdftex,option1, option2]{hyperref}
Note that you always have to use the pdftex option, otherwise you will get an error;
if you use the \hypersetup command, your code will be clearer and more readable (even if the effect is exactly the same).
Here is a list of the possible variables you can change (for the complete list, see the official documentation). The default values are written in an upright font:
variable values comment
bookmarks =true,false show or hide the bookmarks bar when displaying the document
unicode =false,true allows to use characters of non-Latin based languages in Acrobat’s bookmarks
pdfborder ={text} set the style of the border around a link e.g. {0 0 0}
gives no border
pdftoolbar =true,false show or hide Acrobat’s toolbar pdfmenubar =true,false show or hide Acrobat’s menu
pdffitwindow =true,false adjust the initial magnification of the PDF when dis-played
pdftitle ={text} define the title that gets displayed in the “Document Info” window of Acrobat
pdfauthor ={text} the name of the PDF’s author, it works like the one above
pdfsubject ={text} subject of the document, it works like the one above pdfnewwindow (=true,false) define if a new window should get opened when a
link leads out of the current document pdfkeywords ={text} list of keywords
colorlinks (=false,true) surround the links by color frames (false) or colors the text of the links (true). The color of these links can be configured using the following options (default colors are shown):
linkcolor =red color of internal links (sections, pages, etc.) citecolor =green color of citation links (bibliography) filecolor =magenta color of file links
urlcolor =cyan color of URL links (mail, web)
In order to speed up your customization process, here is a list with the variables with their default value. Copy it in your document and make the changes you want.
Next to the variables, there is a short explanations of their meaning:
\hypersetup{
bookmarks=true, % show bookmarks bar?
unicode=false, % non-Latin characters in Acrobat’s bookmarks
pdftoolbar=true, % show Acrobat’s toolbar?
pdfmenubar=true, % show Acrobat’s menu?
pdffitwindow=true, % page fit to window when opened pdftitle={My title}, % title
pdfauthor={Author}, % author
pdfsubject={Subject}, % subject of the document pdfnewwindow=true, % links in new window pdfkeywords={keywords}, % list of keywords
colorlinks=false, % false: boxed links; true: colored links linkcolor=red, % color of internal links
citecolor=green, % color of links to bibliography filecolor=magenta, % color of file links
urlcolor=cyan % color of external links }
If you don’t need such a high customization, here are some smaller but useful examples. When creating PDFs destined for printing, colored links are not a good thing as they end up in gray in the final output, making it difficult to read. You can use color frames, which are not printed:
\usepackage{hyperref}
When you just want to provide information for the Document Info section of the PDF file:
\usepackage[pdfauthor={Author’s name},%
pdftitle={Document Title},%
pdftex]{hyperref}
By default, URLs are printed using mono-spaced fonts. If you don’t like it and you want them to be printed with the same style of the rest of the text, you can use this:
\urlstyle{same}