5

I am beginning to write more and more reports which are ever growing in size, typically about 60-100 pages, containing multiple sections, appendices, etc. However, I am finding my current system/style for labeling my figures, sections, etc., is not ideal and isn't scaling that well. Soon I will be writing my PhD thesis and want to ensure that the style I decide to use will scale well and I won't regret it or try to change it further down the line.

Currently my referencing style is something along the lines of:

\documentclass{article}
\begin{document}
\section{Introduction}
\label{sec:introduction}
\subsection{Referencing}
\label{subsec:referencing}
\subsubsection{Too many nested references}
\label{subsubsec:too_many_nested_references}
Some equations, figures, tables, pseudo code, code implementations, referenced by:
%\label{eqt:equation_scaling}
%\label{fig:growth_in_labels}
%\label{tab:results_of_scaling}
%\label{algo:producing_labels}
%\label{code:python:producing_labels}
\appendix
\section{Alternatives}
\label{app:sec:alternatives}
Here we list some alternatives to appending \verb|app:| to everything.
\end{document}

With this approach I frequently find I would like a labeling syntax which has a bit more detail than the minimal \label{environment:brief_description}, but would benefit from something along the lines of \label{topic/section:environment:brief_description}. However, I am fearful of trying to include section info in the labels in the event I try to move things or re-structure the document during editing. (Often I will move a proof or discussion from one section to another).

If anybody has experience with this style of issue, or has recommended guides that address this then that would be much appreciated.

oliversm
  • 2,717

2 Answers2

9

As restructuring when writing a thesis is nearly not avoidable, I strongly object against including section and chapter names or whatever into the labels. Subsections eventually will become sections, sections will become chapters or subsections, and so on. You might include subsections from chapters 3 and 5 into chapter 2, or split section 4.2 into two new sections, one here and one in chapter 6. I think you'll get the picture.

If you label figures, tables and code, the problem is not so severe. Just make sure you use different prefixes for each of the types. Also don't use \label{fig:Fig3a} or something similar. Really try to give them unique and telling names, like \label{fig:elephant_in_the_room}, avoiding abbreviations if possible. Maybe the only exception you can make here is with subfigures, since usually you won't get more than subfigures (a) - (h), and also you probably won't mix up subfigures from different main figures. If you're about to do this, give them telling names.

Also give equations telling names, like \label{eq:Probability_to_observe_pink_elephant_when_drinking_too_much}. Just remember that many editors have an autocompletion utility that allows you to quickly reference them without the need to look up if you need to use \ref{eq:intermediate_result12b} or \ref{eq:intermediate_result11c_v3} (these last two examples are intended to show that these labels become meaningless when introducing another intermediate step, or expanding some equation etc). Really try to find telling names. the above example could be more concise, e.g. \label{eq:pink_elephant_probability}, but be sure to include enough information in order to be able to identify the equation unambiguously. If you can't come up with a telling and unambiguous name for the label, the equation etc. probably needs no referencing altogether.

Do not include anything like chapter or even section in the labels of figures, equations, tables, and the like. If you want to use a sub-structuring, then rather use logical units that will not be split rather than section or chapter titles. Maybe something like \label{eq:derivation_pink_elephant_probability:Bayesian_inference}. This allows you to shift this derivation later around, e.g. into an appendix, if your supervisor does not share your view that it should appear in the main text.

If you finish a derivation, move the result a logical step higher, i.e. the last equation in the 'Derivation of the pink elephant probability' should not include the derivation_pink_elephant_probability part in it anymore, but probably be more like \label{eq:pink_elephant_probability}. If you move the derivation of this equation later to an appendix but keep the result in the main text, it is easier to rename this one equation label in the appendix eg to \label{eq:derivation_pi…ity:end_result} if you eant to cross-reference it, while you can keep in the main text all cross-references as \ref{eq:pink_elephant_probability} instead of renaming them all.

jjdb
  • 2,238
  • Well, I actually think it's good you have to relabel when you restructure. Heavy restructuring usually means you have to reword the internal cross-links anyway, and then the chapter name in the label allows you to identify the moved links and their old-vs-new location quickly. – yo' May 08 '17 at 19:42
  • @yo' that's an interesting objection; however, I do not see the advantage of the additional work of also renaming the labels. For identification of changes I would instead rely on a version control software like git, which I strongly recommend for writing a thesis anyway, see https://tex.stackexchange.com/questions/1118/what-are-the-advantages-of-using-version-control-git-cvs-etc-in-latex-documen – jjdb May 08 '17 at 19:52
  • You won't see much on git diffs; it's actually difficult to identify restructuring details on diffs. Once you do restructuring, the work is already so heavy that the relabelling won't add much to it. – yo' May 08 '17 at 19:54
  • @yo' Well that depends on the level of your git-wizardry skills ;) I would say git diff --word-diff=color | grep 'label{eq:' is not too bad for a start… – jjdb May 08 '17 at 20:19
  • Does not give the context, which is important; how are you sure the reference makes its sense still after restructuring? Maybe you say as we mentioned in Section \ref{sect:foo} but section sect:foo is now further down the document. I really don't think you can rely on any automation for this when restructuring. However, we simply seem not to agree on this and there are probably no more arguments to show. – yo' May 08 '17 at 22:08
  • @yo' The context can be controlled by -A and -B flags in grep. Well, I didn't really understand your argument, so it's difficult for me to agree with them. Anyway, everybody has his or her way, and that's ok. – jjdb May 09 '17 at 06:43
4

Well, use hierarchical labelling:

  • Label top-most sectioning consistently, in such a long work probably something like: chap:intro, chap:prelim etc.

  • Label everything else consistently with <type>:<chapter>-<label>, like eq:prelim-RST or (in a proof of thm:bla-foo) eq:bla-foo-Cauchy or whatever. Use the <type> prefixes always.

    My <type> prefixes are: chap, sect, subsect, eq, fig, tab, (possibly other floats), thm, lemma, def, (possibly other theorem-like environments)

  • Label references in a consistent way, like doe-soe-1950 or in case of many authors ABCD-1970 or abel-etal-1970.

This has worked for me really well. The top sectioning should divide the work into reasonably long parts in which you easily identify the labels.

Community
  • 1
yo'
  • 51,322