We'd like to have an ‘introduction to LaTeX’ document that falls somewhere between the brevity of sample2e.tex and the completeness of A Not So Short Introduction, with a strong focus on examples rather than discursive explanations.

What things do you think need to be included in such a document? If you were writing such an Introduction to LaTeX, of say 20 pages, how would you structure it?

With any luck, I hope that this question will lead to the writing of exactly this kind of introduction to LaTeX document. I'll set up a github later…

Even though examples are important, I'd still concisely describe the idea of semantic markup and separation of form and content, which will avoid many future problems. I'm thinking of, say, the difference between a line break (\\) and a paragraph (empty line): The first doesn't bear any content but is a mere tool of typesetting, while the latter actually implies a unit of meaning and content. If you get people started in this spirit, they'll end up as good LaTeXies :)
–
doncherryMay 20 '12 at 14:22

12

Probably not worth anything as an answer, but I think it needs some strong guidance on "things a modern TeXnician doesn't need for writing new documents" (such as dvi and postscript, perhaps?). Plus clear guidance on how to choose between the pdf- xe- and lua- TeX engines.
–
Brent.LongboroughMay 20 '12 at 14:24

3

@doncherry I couldn't agree more. I think there should be some sort of "principles of good TeX-ing" section at the start.
–
SeamusMay 20 '12 at 14:35

5

I have seen more than one person write code like If $x$ $+$ 2 $<$ 5 which is bad because the spacing is wrong, the font can be wrong, and it takes more effort to type, anyway – make sure you explain that math mode goes around the whole formula.
–
Ben AlpertMay 20 '12 at 16:28

4

Who is it for? What are the people reading the document trying to achieve? If it is supposed to help people accustomed to word processors try LaTeX and decide if they want to switch, or write a short paper with it because they have to, you should open a minimal word processor like Wordpad, look at its functions, and describe how to achieve their equivalents in LaTeX (of course, using the proper way - for example, explain that styles are more important than bold and italics). This is the functionality they want to use, and without it, they will decide that LaTeX is dumb or not worth their time.
–
rumtschoMay 20 '12 at 18:28

16 Answers
16

Here's a somewhat unstructured list of what I believe should be in an introductory-level tutorial:

Restrict attention to pdflatex:

No mention of dvi output files and viewers, or of XeTeX, LuaTeX, Plain TeX, LaTeX2.09, or any other TeX incarnations.

Choose a very small number of possible TeX distributions to discuss, say TexLive (and its MacOS implementation, MacTeX) and MiKTeX. Provide easily-digestible information about these two distributions, including how to obtain and install them.

Provide a brief intro to suitable LaTeX-aware text editors, including some that run on Unix, MacOS, and Windows machines. Recommend that only editors that can handle Unicode input correctly be used.

A very brief "Hello World!" type of "initial document" with an explanation of (i) how the tex file needs to be compiled via pdfLaTeX and (ii) what each line of code does -- including the use of the % character to create comments:

\documentclass{article} % 3 main document classes of every LaTeX2e distribution:
% article, report, and book
\begin{document} % LaTeX has many environments, the most fundamental
% being the "document" environment
Hello World! % The body of this document
\end{document} % When LaTeX encounters this instruction, all final
% processing occurs and the output file is created.

The MWE should also explain the very rudiments of TeX's "macros": (i) control sequences or macros are strings that start with \, and (ii) macros can take arguments. In the MWE above, there are three macros (\documentclass, \begin, and \end), each taking an argument that's delimited with curly braces, { and }. In contrast, the string "Hello World!" is not a macro in the TeX sense.

State that a LaTeX document is a program and must therefore satisfy some consistency criteria in order to have a reasonable chance of generating the intended output.

E.g., any typos in the macros will generate error and/or warning messages.

Explain why a "good" LaTeX document separates the document's content as much as possible from the instructions that control the formatting of the content.

Building on this very basic document, provide extensions (with copious examples) of topics such as

how to structure a document with various sectioning-related commands

how to choose fonts other than Computer Modern,

how to control page layout (geometry),

line spacing (setspace), and so on.

Explain that many useful features aren't "built into" LaTeX but may be accessed easily by loading various "packages". Explain how to load packages via the \usepackage command.

Writing macros should be in there somewhere, but otherwise I agree. +1
–
Konrad RudolphMay 21 '12 at 13:03

@KonradRudolph -- I thought about including just that subject, but dropped it because doing so might stray into the "intermediate" level of LaTeX proficiency. Remember that the document being contemplated is supposed to serve the needs of novices and beginners.
–
MicoMay 21 '12 at 13:07

3

Nevertheless, I find that macros are the most important mechanism in TeX to structure your documents. TeX only really became useful to me after I learned to use macros. Before that, using TeX was a chore (and I only used it because it looked more professional, especially for maths); after that, it was a productivity tool, and I believe it would have saved me a lot of time and frustration had I learned about them before.
–
Konrad RudolphMay 21 '12 at 13:11

@KonradRudolph: Do you use term "TeX" generically for all TeX incarnations or specifically for "Plain TeX"? I would agree wholeheartedly with the observation that one can't get much done in Plain TeX unless one knows quite a bit about macros. For novice users of LaTeX, though, I'd argue that it's quite enough (at the very beginning stage at least) to "know" that the \ symbol starts a control sequence (or "macro") and hence that strings such as \documentclass, \begin, and \end (each with an argument set off in curly braces, { and }) are macros whereas "Hello World!" is not.
–
MicoMay 21 '12 at 13:21

I was using the term generically. I’ve never used plain TeX.
–
Konrad RudolphMay 21 '12 at 13:29

MWE Adding packages and finding info with textdoc.
(Users will be on their own very soon, give them the means to find things themselves).

MWE 3 pages text to typeset within the above.
Conclude.

MWE Beamer
Most users will publish perhaps an article and need a presentation.

All the above are progressive exercises. Always using previous MWE. All above are aimed at getting beginners motivated enough to continue on their own and to be able to create a publication. You do not have to cover everything with such an intro.

I love the idea of showing everything via MWE. I think it has multiple merits, mainly: the users do not have to find out by themselves how to use the stuff in a document, they see how they should use the features. Furthermore one could structure the doc so that the reader would type/compile the MWE before reading the chapter. In the chapter the reader could be encouraged to try some changes to see outcome of those changes easier. Many of my friends tried to learn programming/latex etc. by just reading. It mostyl never worked out. So getting people to try/use stuff is neccesary I think.
–
Andreas WallnerMay 21 '12 at 13:45

@matth Thanks - I'm fairly familiar with creating MWEs. I have just never seen that used as an acronym before.
–
DasonMay 21 '12 at 14:23

No, they shouldn’t be explained but newcomers should be warned. You often come across Internet tutorials or rather old books that explain and recommend things that are not up-to-date anymore.

Package Manuals or The Dos

RTFM, dammit!

Keep calm, but really, oftentimes the answer lies in some manual and you can even learn something that you had no idea of it being even possible! Sometimes they even add some useful things on typography (e.g. booktabs),
and sometimes … they are just too overwhelming (TikZ? The whole PGF family!).

In my opinion, your focus should be on helping a beginner find the particular functionality they might want. Most people learning LaTeX don't want spend a lot of time searching through documentation, they just want to get things done...quickly. Showing them functionality will reduce the steepness of the learning curve. Open up MS Word or Libre Office and take a look around for typical things that a beginner wants to know. That will guide you. So, for example, you should cover

Setting the margins (LaTeX's default margins are too big for most people)

picking a font

setting the font size

emphasis on text (boldness, italics)

Creating a list

Spacing between lines

Spacing between paragraphs

footnotes/headers

hyperlinks

alignment (centered, left justified,...)

tables

lists

turning page numbers on/off

Inserting a picture

How to make the picture go where you want

Creating a horizontal line (eg for a signature to go on)

multicolumns

AMS-math (math/science people are ones drawn to LaTeX)

Wrap text around a picture.

colored text

You want the guide to show the user that LaTeX can do everything that other program can do plus a lot more. Whenever you introduce a package that helps (such as the geometry package for margins) then give a brief summary of the essential options for the package (and mention how they can find package documentation for more detail). If there are multiple packages for that functionality, pick one, explain why you chose that and let them know there is another alternative.

I think you'll need to have some beginner review your work because they see problems we don't. I was trying to help someone learn LaTeX recently and he wanted to know how to get extra horizontal space between words on a line; that's something that never even occurs to me. So add horizontal and vertical spacing to the list, too, as well as how to get a percent sign in their document.

After covering functionality, show how LaTeX can make things easier; eg changing article to letter in the \documentclass and inserting some commands to get a nice looking letter. If there is time/space books, bibliographies, referencing, using \include should be covered because LaTeX shines on working with long documents.

One thing I think is vital: Minimal working examples that highlight various features. I've found, for example, that some people use \documentclass{minimal} rather than \documentclass{article} and can't get code to run. Or they haven't inserted the AMS-math package. A minimal working example goes a long way towards clearing up problems!

Of course, you'll need brief covereage of document structure. I think Five Minute Guide to LaTeX is on the right track but falls short because they haven't covered enough of the basic functionality I mention and don't give MWEs.

this isn't a beginner's list, but a list for intermediate users. a beginner will most likely have a specific target, whether it's a homework assignment, a dissertation, or preparing a manuscript for submission to a journal. so for those purposes, an introduction to the proper structure of text in a latex document file, and how to find and use an appropriate document class and essential packages, are much more important and elementary.
–
barbara beetonMay 20 '12 at 17:14

1

I disagree with this answer. I think the beauty of LaTeX is that I don't have to worry about margins, fonts, font sizes, inter-line and inter-paragraph spacing, alignments etc., but instead concentrate on content. Setting the font is a pain in the appropriate place anyway. I think a beginner should be informed that the LaTeX way of creating a document differs from the MS-Word way in this sense. I also find the default margins too big, but the fullpage package solves this.
–
marczellmJan 1 '13 at 12:32

Perhaps the solution is to build a series of different introductions? "LaTeX for mathematicians" "LaTeX for humanities scholars" "LaTeX for thesis-writing" "LaTeX for programmers" "LaTeX for the computer-illiterate"…
–
SeamusMay 20 '12 at 14:51

This is problematic. An introduction into math can be something completely different than an introduction into LaTeX for mathematicians. I used a lot of math (for physics) but never required a theorem.
–
Matthias PospiechMay 22 '12 at 20:35

Tools are important. Make sure to highlight one or two good editors/IDEs and build tools each for the major platforms.

(Cross)References are a killer feature compared to word processors. Make sure to introduce those, and clearly mention that you need multiple runs to get them right (might apply to other features).

Typesetting is a minor concern to beginners, but I have learned that with a minimum of awareness towards typesetting, you learn to appreaciate LaTeX even more. So you might want to include a section that highlights some of the fundamental things, with references to more.

Presentation slides with beamer might be a good advanced example. It shows that skills developed for writing articles can be used for other documents immediately. Other possibilities include letters or CVs (moderncv).

The most important thing:

Astonishing enough, people even here on tex.stackexchange tend to forget the most important point of using LaTeX:

We do cooperate, here and in many other places in the web and we even meet once in a while in a bar with other TeXies from around our place, and we have large meetings, all around the world.

If you have a question regarding LaTeX, most probably you will get an answer. If you are lucky, by the maintainer of the package involved. How's that song in soccer stadiums? »You'll never walk alone«.

To me, this and how to write a MWE seems the most important thing to teach, apart from the command texdoc.

My first forays into LaTeX were frustrating to say the least, but with perseverance and asking a lot of questions (and a very important deadline) I made enough progress to consider it a tool worth continuing with. Eventually I came across several very good guides that allowed me to achieve what I needed to achieve. The most enduring one for me is the Visual LaTeX FAQ by Scott Pakin. For beginners there is far too much jargon and nomenclature to wade through to really understand some of these guides. People can describe what they want to do, but not in words that an experienced LaTeX user would use, which makes a web search difficult and ineefective. The visual FAQ got me through those times.

I do not want to add another list of topics, but I have given some 4-6 hour workshops for LaTeX beginners. And I think that my list of topics included in those talks covers most of what I would add to your manual. The way I teach is very likely close to your approach: I work with minimal examples all the time. However they get more complex to the end. And the exercises have quite complete preamble, but that is another story.

The Latex wikibook is an excellent introduction which fits many stated requirements. Its main value is that it reports examples for using modern packages (often updated versions of traditional packages reported in other guides) for achieving various goals.

I would lead the user by examples how to "convert" or do some word-like one-pager in LaTeX.

Page 1: LaTeX in a nutshell (it is a compiler, you need a distro, how to run a short hello world.), and an explanation what the following page 2 is all about.

Page 2: A figure of a typical Word/Office page, actually made in such a program. Should include the most basic things users want to do: Lorem Ipsum Text, Headlines/Subheadlines, Bold/Italic text, color text, a short numeric list, a short bullet list, embedded image, small table, a not too complicated formular.

Page 3+4: A double page focusing on explaining how text/paragraphs/headlines work, with two columns on the left side: first column with explanatory text how to convert the word-like text from page 2 into LaTeX, column two the resulting LaTeX source (maybe shortened with "..."). The right side shows the final renered LaTeX page so far. The advanced topics (lists, tables, ...) are not yet adressed and placeholders used in the example.

Page 5+6: Like pages 3+4, but focusing on one other element, like how to do bold/italic/color text. Again: one column explanation, one column example LaTeX output, one page the now improved page from the previous doublepage with the untouched topics still as placeholders.

Page 7+8: Another double page, this time focusing on explaining lists.

Page 9+10: Another double page, this time focusing on simple tables.

... and so forth, until the example page gets more and more sophisticated and the 20-page limit is reached.

Each double page therefor is a small mini-tutorial by itself.

Last page should be a "further reading" with pointers to where to find more advanced information, somehow grouped, e.g. like "more on figures", "more on tables", ...

I agree, because I think that TikZ is a very compelling reason to prefer using LaTeX over word processors. Whenever I show others what TikZ can do the usual reaction is: "Wow, you can do this with LaTeX?!?"
–
YoriMay 20 '12 at 22:16

4

But be careful not to scare them off; learning TikZ, although rewarding, requires significant investment, like climbing Mount Impossible.
–
Brent.LongboroughMay 21 '12 at 8:38

3

In my advanced lecture about LaTeX (40 hours in total, basic LaTeX knowledge was required) I had introduced pgf/trikz at the very end. The students where fascinated by the results and scared by the code. This is definitively not a topic for beginners.
–
Matthias PospiechMay 22 '12 at 20:31

I think the LyX documentation is excellent and would be a good place to start. It has great bits on whitespace and similar things that are unfamiliar for people coming from standard wordprocessors. It is divided into a basic tutorial so people can get started fast. A user guide which is more comprehensive, and then a set of more specialist technical manuals for embedded objects etc.

Definitely agree with ignoring dvi and other ancient things.

Use annexes for things that are irrelevant to most people. The Auctex manual is horrible in this regard - you have to wade through pages of info about compilation before you even get started with information on how to use it. Put that kind of stuff in annexes (or as with LyX, in separate documents).

Of course, looking at the 10-20 most frequently asked questions on this site and making sure they are answered would be good too!

In my own requirements for LaTeX, I would like to find a tutorial which has an introduction to the common use case: forum web sites as Math markup. To discover that LaTeX has this other expansive use case for complete documents was a heady disconnect.

Thus, my suggestion is to make a history of use which incorporates the why and wherefores of LaTeX's origin domain and adoption in other cases. When I apply LaTeX code in forums, sometimes it works and other times it doesn't. This disconnect from the origin domain leads to a complicated error process where I question both my syntax and the implementation on the forum site. Is LaTeX like other OpenSource type projects where there are different branches and thus small differences which may go uncommunicated?

The most important thing to be explained in the beginning is that there is no better system other than LaTeX. If there were such a better system then we would not discuss LaTeX anymore. This assertion will make the audience know why we discuss LaTeX rather than others.