Non-Standard Code – A Workaround

2011-12-11 by . 5 comments

Post to Twitter

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 ife+TAB into the source code, will replace ife by
if (condition){
  <then case>
}
else{
  <else case>
}
Next, hitting TAB 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 TAB 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 .emacs 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 $latex $ fragment. Save the following code as inlinemath.yasnippet in your snippets/text-mode/latex-mode/ directory.
# -*- mode: snippet -*-
# key: m
# group: math
# name: Inline math \( ... \)
# --
\($1\)$2
Next I will present a snippet for fractions, namely \frac{}{}. Save the following code as frac.yasnippet in the same directory as above.
# -*- mode: snippet -*-
# contributor: Song Qiang <[email protected]>
# key: frac
# group: math
# name: \frac{numerator}{denominator}
# --
\frac{${1:numerator}}{${2:denominator}}$0
Finally, after reloading the snippets (M-x yas/reload-all), inorder to have  \( \frac{1}{2} \) in the code, I will type:  m TAB frac TAB 1 TAB 2 TAB TAB. 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 (define-key yas/keymap [tab] 'yas/expand) to my .emacs 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.

Filed under LaTeX

5 Comments

Subscribe to comments with RSS.

  • Raphael says:

    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.

    • says:

      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.

  • Raphael says:

    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 \lang{A} = \set{a, aa, aaa, \dots} way more than \mathcal{L}\left(A\right) = \left{\ a, a, aa, \dots \ \right}. 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 lang macro (and don’t change other occurrences of mathcal).

    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 lang, 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.

    • says:

      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, \frac{}{} \binom{}{}, 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.

  • Raphael says:

    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.

  • Leave a comment

    Log in
    with Stack Exchange
    or