Introduction
After answering the question about macro for \left( and \right) I realized that there’s a discussion worth considering behind the scene here. In particular, one can consider a beautiful solution, like the one of Herbert’s. This kind of answer, by all means, addresses the question posed. However, alongside, it also introduces several issues which might suggest that a better course of action is to be taken. Non standard code examples, like these which can be found in the question mention, as well as in many other threads in TeX.SE, have one prominent drawback, namely, they turn the code into a non standard one. I believe that for simple standard tasks (like the one dealt with in the question I started this post with) a more standard solution, in terms of TeX should be used. Let it either be code reuse or collaboration, non standard code serves as a problem. On the other hand, typing the full and standard TeX code can be sometimes be lengthy and tedious. Just like one won’t change the syntax of a for loop in any programming language, although it is being extensively used, one should not change, in my mind, the essence of TeX code.
The alternative’s, which I would like to introduce and account my way of using, goal is to enable efficient typesetting process on the one hand, and maintain the resulting source code as standard as possible. It is called code snippets.
Disadvantages of non-standard code
Before explaining what are snippets and the way I use them when processing a TeX document, I would like to mention several drawbacks of the usage of non-standard code. Indeed, non-standard code speeds up the typesetting process, but the price is attached. For example:
- Trying to reuse a code fragment which contain non-standard code will result in an involved sequence of copy-paste steps which will try to include the definitions of the non-standard code into the new setting.
- Same problem which arises when trying to reuse code will happen when trying to share parts of the code with collaborators.
- Even if one managed to “export” the code, let it either be for reuse purposes or as part of a collaboration, the resulting code is non-standard and thus harder to read. Even worse, it is harder to understand what is the original goal behind the code. When a common TeX user reads
\( (x^2) \)
he or she expects one thing, different from
\( \left( x^2 \right) \).
I hope that at this point, without referring to the advantages of standard code, I managed to convince the reader that it is, at least, worthy to consider an alternative to non-standard code; an alternative which can maintain an efficient typesetting workflow.
What is a code snippet
In short, and one should not consider this as an expert’s explanation, a code snippet is the insertion of a code’s fragment (normally fragment which should contain reserved words and additional “free-style” code) which is triggered by a short key combination. For example, hitting
into the source code, will replace
by
if (condition){
<then case>
}
else{
<else case>
}
Next, hitting
for the second time, will bring the courser to the condition’s position, and the user will be able to type in a condition. Similarly, third hitting of
will bring the courser to the else case’s part. The fourth hitting will bring the courser out side of the if statement and the user will be able to enter the rest of the code.
My way of snippets in TeX
In general, the setting I’m using for TeX-ing is emacs+AUCTeX. Thus, I’m using a snippet tool called yasnippet which stands for Yet Another Snippet.
What to download
From the project’s website (where further details can be found), download yasnippet-x.y.z.tar.bz2 and add the following to the
file:
(add-to-list ‘load-path “~/.emacs.d/plugins/yasnippet-x.y.z”)
(require ‘yasnippet) ;; not yasnippet-bundle
(yas/initialize)
(yas/load-directory “~/.emacs.d/plugins/yasnippet-x.y.z/snippets”)
Install the LaTeX extension
Follow the instruction in the yasnippet-latex‘s web site.
Fine Tuning via Examples
The snippets provided by the LaTeX bundle mentioned above is incomplete. But this can be easily adjusted as I explain in the following example.
First, I will define a snippet which produce
fragment. Save the following code as
in your
directory.
# -*- mode: snippet -*-
# key: m
# group: math
# name: Inline math \( … \)
# —
\($1\)$2
Next I will present a snippet for fractions, namely
. Save the following code as
in the same directory as above.
# -*- mode: snippet -*-
# contributor: Song Qiang <tsiangsung@gmail.com>
# key: frac
# group: math
# name: \frac{numerator}{denominator}
# —
\frac{${1:numerator}}{${2:denominator}}$0
Finally, after reloading the snippets (
), inorder to have
in the code, I will type:
. Simple… Isn’t it?
Enable recursive expansion
By default, for me, I couldn’t expand snippets recursively, as in the example. In order to enable this, I hade to add
to my
file.
Conclusion
Using code snippets one can maintain on the one hand efficient typesetting workflow and clean and standard code. This way, at the end of the day, the code is readable, easy to share and reuse, and quick and painless to enter.
Basically, every macro definition leads to non-standard code. Where to draw the line?
I think we need tools that take a piece of LaTeX and replace all instances of macros and environments that are defined in the same document with their definition. This way, we could create highly customised sets of macros but be able to share the result, too.
Every macro introduces non-standard code – that is correct. Snippets, however, are not macros. When using snippets the resulting code is standard as the snippet generate standard code – as long as the snippet author made sure this is the case. Obviously, if you use a snippet which in turn expands to non-standard code, then you achieved nothing. A good snippet, in my mind, is one which enables you to insert lengthy and standard code fragments in just few keystrokes.
droratariah, snippets have the disadvantage that they create, well, standard code, which by definition lacks semantics most of the time. I enjoy writing and—more importantly—reading
way more than
. It is true that snippets can ease writing standard code, but you will always get (relatively) unreadable code that is also hard (impossible?) to change globally later on. If I want my language symbol to look differently later I just change my
macro (and don’t change other occurrences of
).
Of course, I am just repeating advantages of defining macros for anything you repeat. But that illustrates my point: if I have to introduce non-standard code in order to work properly anyway, where to draw the line?
Personally, I would refrain from overwriting existing stuff; if somebody reads my document and finds
, they know they don’t know how that is defined. Changing the behaviour of parentheses is more dangerous as the reader won’t expect the non-standard behaviour.
I see your point now. I would say that one should use snippets for standard code fraction that pop up over and over again. For example,
, itemize environment etc. Obviously, if one expands non standard code from a snippet then we gained nothing.
As for the readability issue – well… at least in the lengthy version every code reader can understand what you wanted to obtain.
I would argue for the exact opposite. While the LaTeX expert sees what symbols I want to obtain in the end, no one knows what I want to say. Besides, which symbols I want to use might change over time, as mentioned above.
On the other hand, the short version is semantic. It hides the symbols but shows the meaning. It might be a matter of taste, but I clearly prefer showing the meaning and hiding the implementation.