Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

Lets say I have the following LaTeX code

\subsection{Convex sets}
A set \( \mathcal{S} \)
in \( \mathbb{R}^n \)
is said to be convex if 
\[ \mathbf{x}_1, \mathbf{x}_2 \in \mathcal{S} \implies \lambda \mathbf{x}_1 +
(1-\lambda) \mathbf{x}_2 \in \mathcal{S} \text{~~~for all~~~} 0 < \lambda < 1 \]

I find that even after formatting it like this with a new line after each inline math environment it gets pretty unreadable after a while. I find that for texts that are full of math, in general, it is really hard to produce readable code.

Is there some best practices how to write more readable math in LaTeX?

I there something like LyX but with the possibility to write pure LaTeX and have commands being processed in the editor. Like if I write \textbf{b} then b would show as bold and the \textbf{} part would disappear. The when I hover with mouse over or place cursor behind b \textbf{} shows up again. Maybe this is possible with LyX?

share|improve this question
4  
related? –  Marc van Dongen Dec 11 '12 at 10:57
    
The link provided by @MarcvanDongen is good. I would put a blank line after the heading, not break up the inline math, but on the other hand use plenty of line breaks and indents in the displaymath, splitting logical places such as the relation \implies and before the condition \text{...}. –  Andrew Swann Dec 11 '12 at 11:16
2  
I would as well use \quad\text{for all}\quad instead of \text{~~~for all~~~} and if you use it a lot, define \newcommand\qtext[1]{\quad\text{#1}\quad} and possibly \newcommand\qqtext[1]{\qquad\text{#1}\qquad} if you use larger space somewhere as well. –  tohecz Dec 11 '12 at 11:58
2  
The title of this question is an oxymoron. –  morbusg Dec 11 '12 at 13:09
2  
This is what LyX does by default. Go to math mode (e.g. ctrl+m and then type \textbf{ and you will see what happens) –  Xu Wang Dec 11 '12 at 15:39
show 2 more comments

6 Answers

up vote 27 down vote accepted

Most of what I say is covered by other answers, but I will write here my thoughts.

First of all, if you write a lot in LaTeX format, I think you should leave LyX and go for any plain text editor. In the (near) future you will be faster (reading and writing code).

About writing readable code. Here are some tips to make it readable:

  • One of the main features I found in LaTeX is the ability you have to write what you want. But don't fail at deciding what you want! I mean, in your code you (shouldn't want) don't want x to be bold (mathbf), you must want x to be a vector (\vec{x}). You will decide later what a vector looks like, but at first, you don't have to worry about it.
  • Next, if you usually define some sets you can define \set command (and later you will worry about how sets are displayed), but, as David Carlisle pointed, you can define shorter commands.
  • This is a must have in my documents: \R (\mathbb{R}) to define the real numbers. It is an entity so I define a command to call them. But I wouldn't define \Rn for \mathbb{R}^n, because then you aren't writing what you want, you are fastening your code input (which shouldn't be done that way).
  • May be \quad is not easy readable for you, but I think it will in the future.
  • This example is no so long, so you can't see how indenting your code benefits the reading of your code, but it really does.
  • I use \[,\] but I don't use \( and \) because I don't read math really good between those delimiters. So I changed them to $.
  • Personally, I don't write comments in my code unless I need to edit it later or something (I use comments as reminders). If you read code fast you don't need comments which explains what are you doing (in my case, they break my concentration).

This is how I would write your code:

\documentclass{article}
\usepackage{mathtools}
\usepackage{amsfonts}

\renewcommand\vec[1]{\mathbf{#1}}
\newcommand\set[1]{\mathcal{#1}}
\newcommand\R{\mathbb{R}}

\begin{document}
\subsection{Convex sets}
A set $\set{S}$ in $\R^n$ is said to be convex if 
\[
    \vec{x}_1, \vec{x}_2 \in \set{S} \implies \lambda \vec{x}_1 + (1-\lambda) \vec{x}_2 \in \set{S} \quad \text{for all } 0 < \lambda < 1 
\]
\end{document}

After that, I think you should differentiate writing code and fastening your input. Most of people defines commands to write faster (like \newcommand\vx{\vec x} from Niel de Beaudrap). I don't agree with that. To write faster you should use an editor (or a third party app) which lets you create snippets (i.e. I would make a snippet with \vec{x} which would be called when you type vx).

At last, to fasten your code-reading you must use a program which shows your code with colors (a color for math, a color for commands, a color for text,…). This is an example of my code (the theme and font I show here is not the usual, but I'm not in my main operating system, however I don't hate this setup): enter image description here

Summary

These are my ideas:

  1. Write what you want (but don't misunderstand what you really want). The commands you use have to be entities, not just 'shortcuts'. Later, you will care about how will it look like.
  2. Don't use commands as snippets (use a good editor or a third party app to make use of snippets).
  3. Indent your code.
  4. Use an editor which displays the code with different colors.
  5. Again, if you want your code to be readable don't use \mathbf{x} \in \mathbb{R}^n or \vx \in \Rn. I would go for \vec{x} \in \R^n.
share|improve this answer
    
What editor are you using? –  azetina Dec 11 '12 at 20:30
    
I'm using TextMate (only works in Macintosh at this moment). –  Manuel Dec 11 '12 at 20:34
1  
I know that this says a lot that has been said in the earlier answers. I accepted this one mainly because it points out that "you must want x to be a vector (\vec{x}). You will decide later what a vector looks like, but at first, you don't have to worry about it." –  evading Dec 12 '12 at 7:43
    
@Manuel What font are you using? –  Jörg Dec 14 '12 at 12:25
    
@Jörg In this image Monaco is used. But in my main computer I'm still undecided between Monaco, Menlo, Inconsolata and Anonymous Pro. –  Manuel Dec 14 '12 at 15:15
show 3 more comments

There probably are editors that do the kind of textual substitution that you describe (emacs on your example already makes the section heading in a different font, although it doesn't hide the \subsection markup, it clearly could given sufficient lisp definitions).

Perhaps I'm just an old Luddite but I find the font changes in the editor distracting and certainly if the editor starts hiding markup it seems simpler for simple things but for anything more complicated, or if things start to go wrong it makes things a lot harder to understand as you are never sure if what you are seeing is what is actually being processed.

What can help is to give more semantically relevant names to the markup so that it reads more naturally. Here I think you are using calligraphic to denote sets, blackboard bold to denote the common number fields, and upright bold (I prefer bold math italic myself) to denote vectors. so after some simple definitions such as

\newcommand\sets{\mathcal}
\newcommand\R{\mathbb{R}}
\newcommand\V{\mathbf}

You could have a perhaps more readable source

\subsection{Convex sets}
A set \( \sets{S} \)
in \( \R^n \)
is said to be convex if 
\[ \V{x}_1, \V{x}_2 \in \sets{S} \implies \lambda \V{x}_1 +
(1-\lambda) \V{x}_2 \in \sets{S} \text{~~~for all~~~} 0 < \lambda < 1 \]

Of course, there are many variants, if you don't have too many sets you could define \S to be \mathcal{S} and use \S instead of \sets{S} or whatever you find most natural.

share|improve this answer
3  
The text would be a little bit more readable still if dollar syntax was used (e.g., $\sets{S}$), although there are reasons some prefer the Latex syntax (see tex.stackexchange.com/questions/510/…). –  Charles Stewart Dec 11 '12 at 10:53
    
@CharlesStewart +1 I as well prefer the single-$ syntax (not the double-$$ one tho), especially with a proper syntax highlight it seems to be much clearer (even clearer than \(...\) with a proper highlight). –  tohecz Dec 11 '12 at 11:52
    
@tohecks - Right, the case of the $ syntax doesn't apply to the $$ syntax, which definitely should be avoided in Latex. –  Charles Stewart Dec 11 '12 at 12:13
1  
@DavidCarlisle -- \S is the section sign; not good to redefine (and you'd be told that as soon as you tried \newcommand\S{...}). –  barbara beeton Dec 11 '12 at 13:43
1  
Basically +1, but instead of your \V I'd agree with Manuel's answer and use \vec instead, and \renewcommand{\vec}{\mathbf}. And since I'm lazy, it'd be \vec x instead of \V{x}, which is actually faster to type on my German keyboard ({,} require a key combination, while space is the most trivial key to hit) –  Tobias Kienzler Apr 4 '13 at 7:30
add comment

In addition to Davids answer, you can use unicode with Luatex to make the code more readable. I know that this is difficult to input, and therefore not suitable for everyone, but I wanted to show what is possible:

\documentclass{article}

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{unicode-math}

\setmathfont{Asana Math}

\newcommand\set{\mathcal}
\renewcommand\vec{\mathbf}

\begin{document}

A set \( \set{S} \) in \( ℝ^n \) is said to be convex if 
\[ \vec{x}_1, \vec{x}_2 ∈ \set{S} ⇒ λ \vec{x}_1 + (1-λ) \vec{x}_2 ∈ \set{S} 
    \text{~~~for all~~~} 0 < λ < 1 \]
\end{document}

Edit: As pointed out, the boldface x is U+1D431 𝐱 and the calligraphic S is U+1D4aE 𝒮. You can then leave out the command definitions, and write:

A set \( 𝒮 \) in \( ℝ^n \) is said to be convex if 
\[ 𝐱_1, 𝐱_2 ∈ 𝒮 ⇒ λ 𝐱_1 + (1-λ) 𝐱_2 ∈ 𝒮 
    \text{~~~for all~~~} 0 < λ < 1 \]
share|improve this answer
2  
Yes +1 you could complete the transformation by using U+1D431 (mathematical bold small x) 𝐱 and U+1D4aE 𝒮 –  David Carlisle Dec 11 '12 at 11:09
7  
I'd argue that yours is a prime example of bad practice because you hardcoded the style. For example, what if you want to change your \mathcal{S} to a different typeface? Do a global find-and-replace? Fine, but what if that also changes just changes the one \mathcal{S} that shouldn't have changed? –  Marc van Dongen Dec 11 '12 at 11:25
2  
@MarcvanDongen It is not really hardcoded any more than $a + b + c$ hardcoded a choice of computer modern italic. In both cases the actual fonts can be set up elsewhere. It isn't always the right choice but it as advantages and disadvantages like any choice. –  David Carlisle Dec 11 '12 at 11:41
1  
@MarcvanDongen (Remark: I'm not a fan of the "unicode-for-everything" approach) You can make the unicode char "subscript-2" \active (it is \active anyways) and then define it as _{2}. –  tohecz Dec 11 '12 at 11:54
3  
@MarcvanDongen It all depends... Personally I'd rather my input was all ascii markup with the minimum of syntax highlighting. I prefer to see xml/html that way too. But I have learned that I'm in a minority, and the OP specifically asked to see less markup, and using a unicode based system is a reasonable approach to achieving that. It also helps if you are sharing expressions with non-Tex users eg Word more or implements the inline Unicode math described in unicode.org/notes/tn28 which is rather close to the end result of using unicode for everything in xetex/luatex. –  David Carlisle Dec 11 '12 at 12:52
show 9 more comments

One interesting option could be using Unicode symbols, e.g. instead of \int and instead of \mathbb{R}, and use \DeclareUnicodeCharacter.

There's the neo keyboard layout (German site, sorry) which offers six layers (instead of the usual two switched via shift), one of which serves to input the most common mathematical symbols:

The disadvantage is that the layout also remaps your Latin letters (it's an attempt to improve German typing, similar to Dvorak). But you can see this as an inspiration to modify your QWERTY (or whatever layout you prefer) to include this additional layer. (Sidenote: You can create Windows keyboard layouts with MSKLC)

The neo-layout website also has a German wiki article on how to set this up with LaTeX or XeTeX, and they provide the uniinput package for the mentioned \DeclareUnicodeCharacter of probably all relevant unicode symbols (including e.g. greek letters).

update I figured out there actually is a Unicode block Mathematical Alphanumeric Symbols including bold letters so you could write 𝐱 instead of \mathbf{x}. Typing that could be implemented via a deadkey, e.g. AltGr+b followed by x. So your example could be input as

\subsection{Convex sets}
A set \( 𝒮 \)
in \( ℝⁿ \)
is said to be convex if 
\[ 𝐱₁, 𝐱₂ ∈ 𝒮 ⇒ λ 𝐱₁ +
(1-λ) 𝐱₂ \in 𝒮 ∀ 0 < λ < 1 \]

which looks pretty readable to me. (I took the liberty of replacing your for all as well)

share|improve this answer
    
This will neither save you trouble after changing your mind to use \mathcal instead of \mathbb later on nor display \textbf conveniently though, you'll have to use e.g. LyX for that... –  Tobias Kienzler Dec 11 '12 at 17:21
1  
Do you know if there is something like this ready to be used with US-international as the first layer? (for GNU/Linux, or Ubuntu in particular) –  alfC Dec 11 '12 at 20:40
    
@alfC Unfortunately not, maybe someone at unix.stackexchange.com does. But you can download their Linux files or browse the SVN repository to see how it's done and then adapt it yourself... (and then put a link here so others can benefit as well ;) –  Tobias Kienzler Dec 12 '12 at 7:24
1  
I opened a question in askubuntu.com/q/228050/15943 –  alfC Dec 12 '12 at 7:59
    
I tried but the code seems quite cryptic svn.neo-layout.org/linux/xmodmap/neo_de.xmodmap –  alfC Dec 14 '12 at 5:37
show 3 more comments

I do a lot of my early draft writing in LaTeX, so I place a substantial value in being able to quickly read my own LaTeX code.

As a result, I adopt a style which is half-way between the "LaTeX way" (of using the correct delimiters for math environments and semantic names for macros) and quick-and-dirty macro usage (to save not only on keystrokes made, but on characters to re-read). The following is a typical way that I would render your code-segment.

% In the pre-amble
% ====================

% A semantic command for vectors
\renewcommand\vec[1]{\mathbf{#1}}

% A syntactic command for special symbols which I would
% consistently use for a given purpose.
\newcommand\R{\mathbb{R}}
\newcommand\cS{\mathcal{S}}

% In the document body
% ====================

\subsection{Convex sets}

A set $\cS$ in $\R^n$ is said to be \emph{convex} if
\begin{align}
  \vec x_1, \vec x_2, \in \cS
  &\implies
  \lambda \vec x_1 + (1-\lambda) \vec x_2 \in \cS
  &
  \text{for all $0 < \lambda < 1$.}
\end{align}

I don't bother adding newlines in the middle of sentences, except for things such as footnotes and ends of lines (which is useful to do if you use a content revision system to track changes). But I add them liberally in my displayed math to better reveal the structure of what I'm writing, especially in tabulated environments such as align. You could also just use an equation environment instead, in which case I would write:

\begin{equation}
  \vec x_1, \vec x_2, \in \cS
  \implies
  \lambda \vec x_1 + (1-\lambda) \vec x_2 \in \cS
  \quad
  \text{for all $0 < \lambda < 1$.}
\end{equation}

Some further remarks on my approach to defining the macros:

  • If you only have a few vectors in your text, you can make your mathematics somewhat more terse by defining

    \newcommand\vx{\vec x}
    

    to speed up your (or your collaborators') personal lexing process; how this affects one's ability to parse the mathematics is another matter. As with \cS, this sort of naming convention depends on the reader (most probably just you, but also any collaborators) becoming accustomed to parsing the name of the macro as an adjective-noun couplet: a "calligraphic S", a "vector x", and so on.

  • As for \R, this sort of naming convention ought only to be used for a single style thoughout all of your documents for symbols representing very important objects (such as blackboard-bold symbols denoting number-sets which you are likely to refer to in any given paper).

Use such shortcuts with discretion, both for your own sanity and those of your colleagues who might also work on the document with you.

share|improve this answer
add comment

I personally use emacs with AUCTeX and fold-mode. AUCTeX renders math, figures, and titles and shows them exactly as they will look like in the final document. All you need to do is the type C-c C-p C-d to generate all the images. When your caret moves to a generated images it is converted back to text so you can edit the LaTeX.

emacs auctex

This is what it looks like when editing a generated image with AUCTeX:

enter image description here

For things that AUCTeX doesn't handle, like plain text \emph{}, \cite{}, enumerate (and friends), and \ref{} (and others) I use fold-mode. fold-mode can work alone if you do not want to use AUCTeX for full rendering. When used without AUCTeX It will handle titles and footnotes (previously handled by AUCTeX) and will use unicode characters for math symbols; you can see the letter \lambda and \in in the screenshot.

emacs fold-mode

The "[c]" is a hidden citation, hidden by fold-mode, to see or edit it just move the caret to it. Same for "[f]" which is a hidden footnote by fold-mode, while with AUCTeX it is given its proper number "1" as displayed in the second image. The green italic "convex" is "\emph{convex}", rendered like this by fold-mode.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.