New Members ⇒ Bad Habits and Land Mines to Avoid

[LaTexLearner]

I'm learning LaTeX, but have NO programming background. I don't have that much time, either. I'm trying to create a fractions workbook and am utterly fed up with MS Word.

So, to help me save some time, perhaps you could answer this question:

What are the biggest mistakes and myths you see in beginners (with no programming background) learning to code with LaTeX? What are the biggest wastes of time?

[LaTexLearner]

FYI, This is what I've done so far:

• Drawn up many of the worksheets by hand or on MS Word (blech).
• Started going through LaTeX for Complete Novices, Version 1.4 by Nicola Talbot.
• Started using this forum and tex.stackexchange.com.

[Stefan Kottwitz]

Generally I prefere positive lists but it's true, one needs to know what should be avoided. For example, LaTeX tutorials teach about using \textbf{} for making text bold, but they often don't tell to not use it in the text. Ok, so let's put it on the list and add something I remember:

• Do not use physical commands such as \textbf{}, \textit{}, \mathrmf{} etc. directly in the text. Instead, define logical commands such as \keyword, \subject and similar, and use physical font commands only in those macros.
• Don't repeat yourself. Don't do copy and paste for similar document parts. Instead, define macros for anything what occurs several times in a similar way. Defining macros is easy! And then you can change the whole design, many things at the same time, consistently for the whole document by just modifying this macro in the preamble.
• Never use \\ for producing vertical space, or for ending a paragraph. It ends a line, but the logical paragraph continues, which affects justification and interline spacing. \\ is rather for ending lines in multiline environments, such as tabular, array, and matrices. End paragraphs by an empty line. If you really need vertical space, use \vspace{\baselineskip} for skipping a line, or commands such as \bigskip, or define your own macro which is using \vspace. Like said above. So you can stretch spacing consistently at any time.
• As I mentioned empty lines: they are for ending paragraphs, do not use them for just improving code readability! They have a real impact, as breaking a paragraph. Can be undesired (illegal) in math mode. If you need an empty line in code without such effect, just put a percent sign % at the start, which comments it out, so there's no effect.
• Never place figures or tables at fixed places, such as with the [H] option. It's easy to get in trouble with line breaks and vertical page filling (whitespace at the page end) once you get some figures or tables in a longer document, which still changes. Instead, let LaTeX do the positioning. That's what captions and numbering are for: for cross-references, because figures and tables in good books usually don't appear right at the place where they are mentioned. They appear at a near place, usually in top of a page, but more important at a place which is the best place for text flow and general figure/table distribution in the text to look nice.
• Don't save space in code. Several spaces count as one, so you can even arrange text in the code for better readability, such as in tables. Even more in math mode: be spacey! Spaces in the source are not relevant but they improve readability much. Helps in troubleshooting or later reading.
• In addition to what I above said, take care of spaces nevertheless in macro definitions. Note, also an end of the line in the code counts as a white space. Otherwise you may wonder about a space in the output caused by a line break in your code. You would be on the safe side, if you end lines in macros by a %, which comments the line break (space) out. If you don't need it.
• Don't copy huge templates or long preambles without reviewing them. Look at least at each line in the preamble, what the package or setting is for and if you need it. Otherwise you can get package conflicts or wonder about settings which you may not have intended.
• Don't use old classes, old packages, outdated packages. Check dates, maintenance, lists of obsolete packages before you really use their syntax in a long document. Choosing and changing at an early stage is easy, at a later stage one may not like to find out, that a heavily used package is not the best choice.

Stefan

[Johannes_B]

I want to add something to the last point: For a beginner, it is very hard to evaluate the quality of a post or solution given in some post, so you should slightly mistrust every post you encounter and check the date. A solution that might have been state of the art 10 years ago, could no be a very bad idea. One example i often encounter is using package subfigure, which is obsolete for 10 years now. If you need subfigures and according captions, use package subcaption.


One additional item to the list: Don't be afraid of errors
Error occur quite often, i got errors multiple times per day. With every error comes a little message by LaTeX, where or why it got stuck. Make a little document and play around a bit. Swap lines or erase single letters. Once you know, what simple little mistake issues which error, all will go down smooth from there.

[LaTexLearner]

@ Johannes_B,
I am making many, many, many, many errors and I know that's just part of the feedback loop of learning. More loops => More learning.
Regarding the obsolete code... wow. I thought I read somewhere that LaTeX hadn't changed much in the past twenty years, which is why it was so stable. Is that not correct?

[Johannes_B]

The base, the kernel, is quite stable, though there were updates and there will be updates with the new TeX Live 2015 for the kernel. Nothing to break any existing documents, though.

LaTeX, on the other hand is a huge modular project, supported by many many developers. Currently, CTAN lists over 2000 package/class authors. Code in the packages can change, some packages get completely new versions. Lately, package datetime has been replaced by the new datetime2. If i would have suggested to use datetime a month ago, i would now suggest datetime2 to get things done.

[LaTexLearner]

@ Stefan_K

• Newb question: What is the difference between a defining commands, custom environments, and macros? Or are they all the same thing?
• What is the "baselinskip" part for in the \vspace command?
• Yes, spaces in code are good! Way easier to read that way.
• How do you check the maintenance and dates of packages and classes and things like that?

[Stefan Kottwitz]

@ Stefan_K

• Newb question: What is the difference between a defining commands, custom environments, and macros? Or are they all the same thing?
• What is the "baselinskip" part for in the \vspace command?
• Yes, spaces in code are good! Way easier to read that way.
• How do you check the maintenance and dates of packages and classes and things like that?

Very good questions! I will gladly answer.

Since it's not any more about bad habits and something to avoid, it would be great to open a topic for each new question. So it can be thoroughly answered, I would do or others might, and the great benefit would be that people can finde the new topic with the new, matching title.

I guess you are not in a hurry, so we can take time together. Though of course I understand, that new questions come while talking. Let's spread the tree of questions, which will be tagged and archived so later people learning LaTeX can find specific questions and answers via google!

And by the way, we could then keep this topic open for further suggestions regarding bad habits, without distraction, maybe further fellow users would add their thoughts.

Stefan