summaryrefslogtreecommitdiff
path: root/info/latex-doc-ptr/latex-doc-ptr.tex
blob: 590bebb76b76bf2531f9c6e6e336cf99e275c486 (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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
\documentclass[11pt]{article}
\usepackage{latex-doc-ptr}
\usepackage{endnotes}

\begin{document}\thispagestyle{empty}
\begin{center}
  {\color{black}\LARGE\bf A First Set of \LaTeX{} Resources}  
\end{center}
\vspace{1.5ex}

\begin{multicols*}{2}
% \section{\LaTeX}

% \LaTeX{} is a collection of commands for 
% writing documents with the \TeX{} typesetting system.
% It is by far the most popular way to use that system. 
This page suggests documentation, add-on components, and other resources
for a beginning \LaTeX{} user.

The links here are to freely available materials,
so you can click to see the documentation online.
Where the documentation is also available
offline in a typical \TeX{} installation, we provide its name as an end note.
View it
by running `\texttt{texdoc {\it name}}' in a terminal.



% ========================================================
\section{Starting}

To run \LaTeX{}, you must use an online service or 
install a distribution.
Online services are commercial; find them by entering `online latex' in
a search engine.
For distributions, your choices are
\href{https://tug.org/texlive/}{\TeX{}~Live} on
a Unix system, including GNU/Linux, or on Windows,
or the related 
\href{https://tug.org/mactex/}{Mac\TeX{}} on Macintosh,
or 
\href{https://miktex.org/}{MiK\TeX{}} on Windows or a Unix system.   

\subsection{Tutorials}
The site \href{https://www.learnlatex.org/}{\texttt{learnlatex.org}}
teaches you the basics in a sound way, and also
lets you play with the commands to see the results.
For a more traditional document, 
the most widely recommended one is 
\href{https://ctan.org/pkg/lshort-english}
 {\package{The Not-So Short Guide to \LaTeXe}}, available in many
 languages.\texdoc{lshort}
% and another good one is from the
% \href{https://tug.org/tutorials/tugindia/}{\package{Indian \TeX{} User Group}}.
% The article
% \href{http://mirror.ctan.org/info/first-latex-doc/first-latex-doc.pdf}{\package{Getting something out of \LaTeX}}
% walks a beginner through writing a sample document.

Many people use \LaTeX{} to write mathematical text and
for this the premier choice is from the American Mathematical Society. 
See their
\href{http://mirror.ctan.org/info/amslatex/primer/amshelp.pdf}
 {\package{Getting up and running with AMS-\LaTeX}},\texdoc{amshelp}
and more detail is in 
\href{http://mirror.ctan.org/macros/latex/required/amsmath/amsldoc.pdf}
 {\package{Users Guide for the {\tt amsmath} package}}.\texdoc{amsmath}




% ========================================================
\section{Documentation}


\subsection{References}  
The nearest thing to a general reference for \LaTeX{} is
\href{http://mirror.ctan.org/info/latex2e-help-texinfo/latex2e.html}
 {\package{\LaTeXe{} unofficial reference manual}}.\texdoc{latex2e}
Look for symbols in the
\href{http://mirror.ctan.org/info/symbols/comprehensive/symbols-letter.pdf}
 {\package{Comprehensive List of Symbols}}.\texdoc{comprehensive}
And, \href{https://tug.org/TUGboat/}{\package{TUGboat}}, 
the journal of the  
\href{https://tug.org}{\TeX{} Users Group},
has published many articles, at levels from beginner to expert, 
almost since the inception of \TeX{}.



\subsection{FAQs}
Many web pages offer quick help with \LaTeX{},
although they can be out of date.
Particularly useful and reliable are the
\href{https://texfaq.org/}{\package{\TeX{} FAQ}},\texdoc{faq} 
as well as
\href{https://tug.org/interest.html}{\package{\TeX{} Resources on the Web}}.
You can also get a handy general
\href{http://mirror.ctan.org/info/latexcheat/latexcheat/latexsheet.pdf}
 {\package{\LaTeX{} Cheat Sheet}},\texdoc{latexcheat}
as well as the
\href{http://mirrors.ctan.org/info/undergradmath/undergradmath.pdf}
 {\package{Math for Undergraduates Cheat Sheet}}.\texdoc{undergradmath}
Also,
\href{http://mirror.ctan.org/info/l2tabu/english/l2tabuen.pdf}
 {An essential guide to \LaTeXe{} usage}\texdoc{l2tabuen}
helps you develop sound habits, by
saying what not to do.

\subsection{Questions}
If you are stuck on an issue, the
\href{https://tex.stackexchange.com/}{\TeX{}-\LaTeX{} Stack Exchange} site 
and the mailing list
\href{https://lists.tug.org/texhax}{texhax@tug.org}
are where knowledgeable people hang out. 
You are likely to find an answer in their past discussions, which cover 
decades, and if not then you can post a question yourself.


\subsection{Books}
There are many excellent books about \LaTeX{}. 
Visit the 
\href{https://tug.org/books/}
 {\package{\TeX{} Users Group's book list}} for a selection, and for discounts.




% =========================================================
\section{Packages}

One of \LaTeX's strengths is the tremendous number of available add-on
packages. 
This list covers most of what
beginners want to do.
(There are some comments in parentheses that
often come up in conjunction with these recommendations.)


\subsection{Our archive}
The Comprehensive \TeX{} Archive Network, 
\href{https://ctan.org}{\color{darkblue}\CTAN},
has the latest official versions of 
the packages that are in the distributions,
along with documentation.
\href{https://ctan.org/topics/cloud}{\color{darkblue}Browsing by topic}
can be very handy.

% If you develop a package, please upload it to \CTAN.
If you have trouble finding something, it may be
the house package of a journal or institution. 
Look on their web page as well as on \CTAN. 



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

As referred to above, any document containing significant amounts of 
mathematics should use 
the American Mathematical Society's packages
\pkg{amsmath}\texdoc{amsmath}
and 
\pkg{amsfonts}.\texdoc{amssymb}
Also use their \pkg{amsthm}\texdoc{amsthm}
for producing theorem environments.
Notes: (1)~\pkglink{amsfonts}{amssymb} inputs \pkg{amsfonts} so load the former 
instead of the latter,
(2)~many authors also use the calligraphic characters in 
\pkg{rsfs},\texdoc{rsfs}
(3)~get bold math symbols with \pkg{bm},\texdoc{bm} 
(4)~don't load \pkg{amsmath} directly, instead get it by loading 
\pkg{mathtools}\texdoc{mathtools} for some useful improvements,
and 
(4)~load \pkg{amsthm} after \pkg{mathtools}.

Also, include
\pkg{microtype}.\texdoc{microtype}
It will make 
your document have fewer awkward lines.



\subsection{Inside a document}
Tweak the layout of lists with \pkg{enumitem}.\texdoc{enumitem}

Enhance captions with 
\pkg{caption}\texdoc{caption}
and control floating environments with 
\pkg{float}.\texdoc{float}
(In particular, this package provides the `\texttt{H}' option 
to override automatic float placement and put something
exactly where you ask.
This may cause issues\Dash what if you want to include a two inch tall
graphic on a page that has only an inch left?\Dash but it sometimes
is what you want.)

Get hyperlinks and turn references into links with 
\pkg{hyperref}\texdoc{hyperref}
(make sure to set it up, 
as with \lstinline!\hypersetup{colorlinks=true}!).
Have cross-references that say `Theorem~1.2' instead of just `1.2'
with \pkg{cleveref}.\texdoc{cleveref}
For \acro{URL}'s and file paths that can break across lines, use 
\pkg{url}.\texdoc{url}
(If you use \pkg{hyperref} then note that it has its own 
commands for the \pkg{cleveref} and \pkg{url} functions.)

Inside verbatim text, make single quotes come out correctly with 
\pkg{upquote}.\texdoc{upquote}
For including computer code, the 
\pkg{listings}\texdoc{listings} package is very popular.
% although \pkg{minted}\texdoc{minted} 
% has many things to recommend it. 
(Copy and paste for computer code is especially 
convenient.
This is a start for the \pkg{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}\texdoc{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}, % \texdoc{sagetex}? not in TL
and similar support exists for other languages.

There are many packages that add table capabilities, such as
multirow entries and breaking across pages.
The first package to try is \pkg{array},\texdoc{array} 
which lets you define your own column
types.
To handle scientific units, 
use \pkg{siunitx}\texdoc{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}.\texdoc{tcolorbox}

Use \pkg{babel}\texdoc{babel} 
for internationalization, including changing the 
title of the abstract or the bibliography.
(Note that \LaTeX{} now defaults to UTF-8 encoded input.)

Finally, when developing a document, you often want to 
generate filler text.
Use 
\pkg{lipsum}.\texdoc{lipsum}



\subsection{Color and graphics}
For colors, use 
\pkg{xcolor}.\texdoc{xcolor}

To include graphics and do simple manipulations such as resizing, 
use \pkg{graphicx}.\texdoc{graphics}
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 in your \LaTeX{} source, you give the file name without the extension,
as with \lstinline!\includegraphics{myplot}!.)
Include parts of an outside \PDF{} document with
\pkg{pdfpages}.\texdoc{pdfpages}
Include video or sound using
\pkg{media9}.\texdoc{media9}

In your plots and graphics, you want that
the fonts and notations match your document.
You have a few choices.  
Draw inside your document with 
\href{https://ctan.org/pkg/pgf}{\TikZ}.\texdoc{tikz}
You can instead draw using an external command language such as 
\href{https://asymptote.sourceforge.io/}{\Asymptote{}},\texdoc{asymptote}
and bring the results in as graphics.
And there are other options, such as that the
\href{http://www.gnuplot.info/}{\gnuplot{}} plotting software
will output \TikZ{} commands,
and the  
\href{https://inkscape.org/}{Inkscape} vector graphics editor allows
you to embed \LaTeX{}-generated equations.


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

For footnotes, use 
\pkg{footmisc}.\texdoc{footmisc}
Make an index with 
\pkg{makeindex}.\texdoc{makeindex}
With \pkg{answers}\texdoc{answers}
you can send exercise answers to an external file, where you can make them
a separate document or include them at the end of the current one. 

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




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

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

To make presentations, use the 
\pkg{beamer}\texdoc{beamer} 
class.
(However, 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}
The documentation for font use commands from the \LaTeX{} developers is 
\href{http://mirror.ctan.org/macros/latex/base/fntguide.pdf}
 {\package{\LaTeXe{} font selection}}.\texdoc{fntguide}

To move beyond the default fonts, 
visit the 
\href{https://tug.org/FontCatalogue/}{\LaTeX\ Font Catalogue},
which includes copy and paste code to make each one work.

Beyond that list, you can also use your computer system's fonts
(beware this makes your source file harder to share with friends, though).
The background is:~to convert \LaTeX{} source to \PDF{} output
there are three varieties of the \TeX{} engine.
Currently the most common is 
\href{https://tug.org/applications/pdftex/}{\package{\pdfTeX}}.\texdoc{pdftex}
For instance, this document was generated with 
\verb!pdflatex latex-doc-ptr.tex!.
Two further developments, 
\href{https://tug.org/xetex/}{\package{\XeTeX}},\texdoc{xetex}
and 
\href{http://www.luatex.org/}{\package{\LuaTeX}},\texdoc{luatex}
can leverage
the \pkg{fontspec}\texdoc{fontspec}
package to use your system's fonts,
such as OpenType and TrueType fonts,
in addition to the ones from your \TeX{} distribution.
(Mathematics requires much special tuning, though, so most
of the time you cannot use system fonts for math.)
% (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.)

More is on the 
\href{https://tug.org/fonts/}{\TeX{} Users Group's font page}.





% =========================================================
\section{Writing \LaTeX{}}

There are many ways to make writing \LaTeX{} source easier.
Most people use a source code editor, such as 
\href{https://www.texstudio.org/}{\TeX{}studio}, or 
Emacs with the add-on mode 
\href{https://www.gnu.org/software/auctex/}{\package{AUC-\TeX{}}}, 
or \href{https://pages.uoregon.edu/koch/texshop/}{\TeX{}Shop} on
a Mac.
% A new environment that is free, runs on all major 
% computer platforms, and combines the best ideas 
% from available environments while retaining simplicity, is 
% \href{https://tug.org/texworks/}{\texworks}.


% ====================================================
\section{Pronunciation}
Pronounce \LaTeX{} as
``la-tech'' or ``lay-tech,'' with emphasis on either syllable.
We prefer the first, with emphasis on the first syllable.


% ====================================================
\section{Welcome to the community!}

One reason that all of these resources are available is 
the work of the many
\href{https://tug.org/usergroups.html}{user groups}, 
including the \href{https://tug.org/}{\TeX{} Users Group}.
Please consider joining.
% The 
% \href{https://www.ctan.org/}{Comprehensive \TeX{} Archive Network}
% contains more packages than any distribution.

% \vfill\null
% \columnbreak
\vspace*{2ex}
\noindent{\color{lightblue}\rule{\linewidth}{0.4pt}}

\hbadness=10000 % we know
\theendnotes

% \subsection{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}