Best practices in labeling (giving labels to equations, theorems, items, etc..)

Question

Are there some Latex style guides with part dedicating to labeling? I want to use some persistent labeling scheme, but don't know any (except for uncertain one in my mind).

What labeling scheme should I use and why? Some (but not all) of questions I want to find answer to:

1. Should it be : to separate labeled environment from label itself (eg thm:label) and why?
2. Should I use - or _ or something else as separation (eg eq:my_equations vs eq:my-equation vs eq:MyEquation)?
3. How do I do nesting labeling? (eg equations in theorem environment)

I want to find some mature labeling schemes which is good for reading, autocompletion in editors and refactoring. I would be grateful for any references.

Answer 1

1) From my personal experience, it is helpful to start with the category (i.e. thm: for theorems, eq: for equations, fig: for figures...) as you might have an equation and a figure (for example) which go together so you can call them the same and distinguish them by category.

2) For the name of the label I like to use underscore to separate words but it is only because I find very confusing not using separating characters.

3) I don't use nesting labelling in theorems but, when I have a system of equations, I use subequation environment (which labels as 1a, 1b...) and label the whole set of equations so when I reference it I get the number (1 in my example) and then I just add the letter manually. I do that because then I avoid having a lot of labels and it usually works well because I don't introduce changes in the ordering of those equations.

I hope this helps you!

Answer 2

I use the following.

1) I agree with @FerranBrosaPlannella that it is a good idea to use prefixes for categories. I also think that the prefix should be separated from the name and : is kind of standard for this. I don't think that categories like Theorem, Proposition, Lemma, Observation,… should have distinct prefixes. They mean essentially the same and I sometimes change my mind whether something should be Proposition or Lemma, so I use thm: prefix for all of them. Similarly I use def: prefix for Definition, Notation, Convention, …

2) I also like when the word are separated and I use _ for this. I sometimes use - in labels for something else. E.g. there is something called “I-space”, and if there was a theorem about decomposition of I-spaces, I would label it thm:I-space_decomposition.

3) I use nested labeling for example when I have a theorem about equivalence between several conditions. The theorem has its label and also the conditions have labels, so they can be referenced individually from outside, but also locally in the proof. I separate the nested parts of the label by ., so such label may look like thm:some_equivalence.condition_1. Such labels are long, which is impractical when used locally, so I define a set of macros to work with these local labels. An example of usage follows.

\begin{theorem} \labelblock{thm:main}
    The following are equivatent.
    \begin{enumerate}
        \item First condition. \loclabel{first}
        \item Conjunction of the following: \loclabelblock{second}
        \begin{enumerate}
            \item First part. \loclabel{part_one}
            \item Second part. \loclabel{part_two}
        \end{enumerate}
    \end{enumerate}

    \begin{proof}
        We can refer to item \locref{first} or subitem \locref{second.part_one}. To prove \locequiv{first}{second} we start with showing \locimpl{first}{second.part_one}.
    \end{proof}
\end{theorem}

Now we refer to Theorem \ref{thm:main} and to and item in a theorem: Theorem \itemref{thm:main}{second.part_two}. Now we refer to the item only: \ref{thm:main.second.part_two}.

The macro \labelblock does the same thing as \label, but additionally stores the label, so \loclabel and \locref can use it. \locref{first} expands to \ref{thm:main.first}. When multiple levels of nesting are needed (which is quite rare), \loclabelblock is used – it is a combination of \loclabel and \labelblock. The \locimple and \locequiv macros are just local versions of my macros for referencing to implications and equivalences between conditions in theorems.

Answer 3

I use type_chapter_detail style notation. The label is also identical to the source filename (if the label points to an item brought in from a file by \input or \includegraphics), so fig_theory_bandstructure would be trivial to pair up with the .pdf figure it points to. A check could easily be automated to ensure that all imported figures had both a \label and a \ref.

I tend to put tables in their own .tex files (\input{tab_theory_materials}\label{tab_theory_materials}), mainly so I can find my way around the source more easily, and compile just the table when I'm getting it right. This could easily be wrapped in a macro \input{#1}\label{#1} though I don't. This approach could be extended to complex equations.

I don't use any editor autocompletion features, so the benefits of fig:theory_bandgap style notation are lost to me.

Answer 4

One important consideration to note when assigning labels is spell checkers. Many spell checkers will pick these labels or their references as misspelled words.

Because of this, I tend to use just numbers. The numbers are often not recognized as misspelled words.