summaryrefslogtreecommitdiff
path: root/info/first-packages/first-packages.tex
blob: 47ce64ab1ace77fd464d768cb1919c76637f0283 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
\documentclass[11pt]{article}
% \usepackage[utf8]{inputenc}
\usepackage[urw-garamond]{mathdesign}
\usepackage[T1]{fontenc}

\usepackage[margin=1.2in]{geometry}
\usepackage{multicol}
\setlength{\columnsep}{2em}

\usepackage{graphicx}  % needed for \XeLaTeX command
\usepackage{listings}
\lstset{basicstyle = \small\ttfamily,
        keepspaces=true,
        columns=fullflexible,
        xleftmargin=10pt}

% Get ISO dates
\usepackage[style=iso]{datetime2}

% Color for links
\usepackage{xcolor}
% Color theme from Rodryggo Sylva
% https://color.adobe.com/explore?page=2
\definecolor{darkblue}{HTML}{023059}
\definecolor{lightblue}{HTML}{023E73}
% \definecolor{papyrus}{HTML}{D9D8D7}
\definecolor{papyrus}{HTML}{E4E4E4}
\definecolor{darkred}{HTML}{BF1E0F}
\definecolor{lightred}{HTML}{F24141}
\pagecolor{papyrus}

\usepackage{microtype}
\usepackage[breaklinks,hidelinks,pdfa]{hyperref}
\hypersetup{
    colorlinks=true,
    linkcolor=darkred,
    filecolor=darkred,      
    urlcolor=darkred,
}


% ? This worked for a while and then it didn't, so I wrapped \url{..}
\newcommand{\pkg}[1]{\href{https://ctan.org/pkg/#1}{\texttt{#1}}}

% Logos and acronyms, some of them to match TUGboat commands
\RequirePackage{mflogo} % for MetaPost \MP
 
\newcommand\pdfLaTeX{pdf\LaTeX}
\newcommand\PDFLaTeX{\pdfLaTeX}
\newcommand\LuaLaTeX{Lua\LaTeX}
\newcommand{\Asymptote}{\textit{Asymptote}} % as per the manual
\newcommand{\TikZ}{Ti{\em k}Z}  % from TUB

% Stuff from ltugboat.cls
\makeatletter
\def\smc{\sc}
\def\ninepoint{\small}
\DeclareRobustCommand{\SMC}{%
  \ifx\@currsize\normalsize\small\else
   \ifx\@currsize\small\footnotesize\else
    \ifx\@currsize\footnotesize\scriptsize\else
     \ifx\@currsize\large\normalsize\else
      \ifx\@currsize\Large\large\else
       \ifx\@currsize\LARGE\Large\else
        \ifx\@currsize\scriptsize\tiny\else
         \ifx\@currsize\tiny\tiny\else
          \ifx\@currsize\huge\LARGE\else
           \ifx\@currsize\Huge\huge\else
            \small\SMC@unknown@warning
 \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
}
\newcommand{\SMC@unknown@warning}{\TBWarning{\string\SMC: nonstandard
    text font size command -- using \string\small}}
\newcommand{\textSMC}[1]{{\SMC #1}}
\newcommand{\acro}[1]{\textSMC{#1}\@}

\def\tubreflect#1{%
  \@ifundefined{reflectbox}{%
    \TBerror{A graphics package must be loaded for \string\XeTeX}%
  }{%
    \ifdim \fontdimen1\font>0pt
      \raise 1.75ex \hbox{\kern.1em\rotatebox{180}{#1}}\kern-.1em
    \else
      \reflectbox{#1}%
    \fi
  }%
}
\def\tubhideheight#1{\setbox0=\hbox{#1}\ht0=0pt \dp0=0pt \box0 }
\def\XekernbeforeE{-.125em}
\def\XekernafterE{-.1667em}
\DeclareRobustCommand{\Xe}{\leavevmode
  \tubhideheight{\hbox{X%
    \setbox0=\hbox{\TeX}\setbox1=\hbox{E}%
    \lower\dp0\hbox{\raise\dp1\hbox{\kern\XekernbeforeE\tubreflect{E}}}%
    \kern\XekernafterE}}}
\def\XeTeX{\Xe\TeX}
\def\XeLaTeX{\Xe{\kern.11em \LaTeX}}
\makeatother

\def\Bib{%
  \ifdim \fontdimen1\font>0pt
     B{\SMC\SMC IB}%
  \else
     B\textsc{ib}%
  \fi
}
\def\BibLaTeX{\Bib\kern.02em \LaTeX}
\def\BibTeX{\Bib\kern-.08em \TeX}

\newcommand{\PDF}{\acro{PDF}}
\newcommand{\CTAN}{\acro{CTAN}}
\newcommand{\URL}{\acro{URL}}

% Style I chopped out of ltugboat.cls
\usepackage{dash}

% Section title styling
\usepackage{titlesec}
\titleformat{\section}[hang]{\color{darkblue}\large\bf}{}{0pt}{}
% \titlespacing{\section}{0pt}{2ex plus 0.1ex minus 0.05ex}{0.85ex plus 0.05ex}
\titlespacing{\section}{0pt}{*2.0}{*0.85}

% Give paras just a bit of room
\setlength{\parskip}{0.45ex}


\pagestyle{empty}
\begin{document}\thispagestyle{empty}
\begin{center}
  {\color{darkblue}\Large\bf A First Set of \LaTeX\ Packages}  \\[1.5ex]
  {\color{darkblue}\large Jim Hef{}feron}  
\end{center}
\vspace{1.5ex}

\begin{multicols*}{2}
If you are a \LaTeX{} beginner and ask, 
``How do I \ldots{}\,?'' 
then often you will be told that there is a package for that.
You may well next ask, 
``How would I know that?  
And if there is more than one package then which should I use?''

This list covers most of what
beginners want to do.
Its goal is to cite one 
package in each area that is capable and reliable, and 
that is in
% \textsf{Mac}\kern-0.35pt\TeX, 
Mac\kern-0.35pt\TeX, 
MiK\TeX, and \TeX\ Live.
(There are some extra comments in parentheses that
often come up along with the recommendations.)



% ==============================
\section{Introduction}
For \LaTeX{} users, the canonical archive is 
the Comprehensive \TeX{} Archive Network, 
\href{https://ctan.org}{\color{darkblue}\CTAN}.
It has the latest official versions of 
the packages in the distributions,
with documentation.
And, \href{https://ctan.org/topics/cloud}{\color{darkblue}searching by topic}
is very handy.

You can also see the package documentation installed on 
your computer by typing 
\verb!texdoc <packagename>! % space too wide?
in a terminal window.

Before the list, one more note.
If you are writing for a journal or 
institution that has its own package then of course you should 
use that.
Look on their web page and on \CTAN.



% ===================================
\section{Every document}
To change page size, margins, and orientation, use 
\pkg{geometry}.
Get multiple columns with \pkg{multicol}.

Any document containing significant amounts of mathematics should use 
the American Mathematical Society's packages
\pkg{amsmath}
and 
\pkg{amssymb}.
I also use \pkg{amsthm}
for producing theorem environments.
Notes: (1)~\pkg{amssymb} inputs \pkg{amsfonts} so you don't need to load
the latter,
(2)~many authors also use the caligraphic characters in \pkg{rfsf},
(3)~get bold math symbols with \pkg{bm}, 
(4)~load \texttt{amsthm} after \texttt{amsmath},
and (5)~don't load \texttt{amsmath} directly, instead get it by loading 
\pkg{mathtools} for some useful improvements.

You can toss in 
\pkg{microtype}.
My eye can't spot the improvements but I appreciate that
it means there are fewer awkward lines.


% ===================================
\section{Inside a document}
To tweak lists, use \pkg{enumitem}.

Enhance captions with 
\pkg{caption}
and control floating environments with 
\pkg{float}.
(In particular, this package provides the option `\texttt{H}' 
to override automatic float placement and put something
exactly where you ask.)

Get hyperlinks and turn references into links with 
\pkg{hyperref}
(this should be the last or next to last package
that you load).
Make cross-references say `Theorem~1.2' instead of just `1.2'
with the one-r-ed \pkg{cleveref}
(load it after \texttt{hyperref}).
Have \acro{URL}'s and file paths that can linebreak with 
\pkg{url}.
(If you use \texttt{hyperref} then note that it has its own 
commands for the \texttt{cleveref} and \texttt{url} functions.)

I do code listings with 
\pkg{listings},
although \pkg{minted} is also great. 
Make single quotes inside verbatim text come out correctly with 
\pkg{upquote}.

(A tangent:~copy and paste for computer code listings would be especially 
convenient.
This is a start for the \texttt{listings} package.
\begin{lstlisting}
\lstset{basicstyle = \ttfamily,
        keepspaces=true,
        columns=fullflexible}
\end{lstlisting}
But it is not a full solution.  
The results depend on the \PDF{} viewer and 
worse, if your code line begins with
blank spaces then after copy and paste those spaces are gone.) 

If you use Python, 
\pkg{pythontex}
will show code listings, but it also allows you to execute
Python and put the results in your output.
Do the same for 
the \textit{Sage} mathematics software with \pkg{sagetex},
and similar systems exist for R, Haskell, and Scheme.

There are many package that add table capabilities such as
multirow entries and breaking across pages.
I most often use \pkg{array}, which lets you define your own column
types.
To handle units, 
use \pkg{siunitx} 
(which also has a table column type for aligning on a decimal point).

Make boxes that are colored or framed, such as boxes for theorems,
with
\pkg{tcolorbox}.

% Finally, when developing a document I often want some filler text.
% I use 
% \pkg{lipsum}.


% ===================================
\section{Graphics and color}
To include graphics and do simple manipulations such as resizing, 
use \pkg{graphicx}.
Use the \acro{JPG} format for photos,
\acro{PNG} for other kinds of raster graphics,
and \PDF{} for vector graphics.
If your graphic is in another format then convert it to one of these three.
(Usually you give the file name without the extension,
as with \verb!\includegraphics{graph}!.)
Include parts of a \PDF{} document with
\pkg{pdfpages}.
Include video or sound using
\pkg{media9}.

For colors, use 
\pkg{xcolor}
(although the documentation can be hard to make out).

To make plots and graphics, I use 
\href{https://asymptote.sourceforge.io/}{\Asymptote{}},
a development of \MP{} with three dimensional
constructs.
However, many people instead draw graphics 
inside the document with 
\href{https://ctan.org/pkg/pgf}{\TikZ}.


\section{Front and back matter, headers, footers}
To style chapter and section titles, use
\pkg{titlesec}.
For page headers and footers, reach for 
\pkg{fancyhdr}.
You can tweak the format of tables of contents, lists of figures, etc., 
with
\pkg{tocloft}.

Write exercise answers to an external file so that you can read them in 
later with 
\pkg{answers}.
I like footnotes at the page bottom so I use 
\pkg{footmisc}
(but I had to hack to change the space between a footnote mark and 
the footnote).
Make an index with 
\pkg{makeindex}.

Bibliographies are a thorny area.
Often you have strict requirements, such as from the
\pkg{MLA}.
\CTAN{} is a big help here; check out the many styles for both
\href{https://ctan.org/topic/bibtex-sty}{\BibTeX}
and
\href{https://ctan.org/topic/biblatex}{\BibLaTeX}.




\section{Special documents}
Make exams and problem sets with the 
\pkg{exam} class.

There are many, many resume and CV packages.
Start with \acro{CTAN}'s
\href{https://ctan.org/topic/cv}{\textit{cv}} topic.

To make presentations, use the 
\pkg{beamer} class.
(But with this package you are entering another world, where many of the
packages discussed here do not work.
For example, section title styling happens via a completely
different mechanism.)



\section{Fonts and engines}
To see options besides the default Computer Modern fonts,
visit the 
\href{https://www.tug.org/FontCatalogue/}{\LaTeX\ Font Catalogue},
which includes copy and paste code to make each one work.

Beyond that list, you can also use any font that your computer has 
(which usually works well only if your document 
does not have much mathematics).
To convert \LaTeX{} source to \PDF{} there are
three programs, called engines.
Most people use \PDFLaTeX.
The \XeLaTeX{} engine and the \LuaLaTeX{} engine can leverage
the \pkg{fontspec}
package to use your system's fonts.
(A word about the preprint site \texttt{arXiv.org}.
If your document was produced with \XeLaTeX{} or \LuaLaTeX{} then 
you can only submit a \PDF, not the document source.)

\LaTeX{} now defaults to UTF-8 encoded input on all three engines.
Use \pkg{babel} for internationalization, such as changing the 
the title of the abstract or the bibliography.

\vspace*{2ex}
\noindent{\color{lightblue}\rule{\linewidth}{0.4pt}}

\section{Feedback?}
Contact me via 
\href{https://hefferon.net}{\color{lightblue}\texttt{hefferon.net}}.
(This version is from \today.)
% The source is at
% \href{https://gitlab.com/jim.hefferon/latexpackages}{\color{lightblue}my GitLab repository}.)
\end{multicols*}

\end{document}