summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/globalvals/globalvals.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/globalvals/globalvals.tex')
-rw-r--r--macros/latex/contrib/globalvals/globalvals.tex83
1 files changed, 83 insertions, 0 deletions
diff --git a/macros/latex/contrib/globalvals/globalvals.tex b/macros/latex/contrib/globalvals/globalvals.tex
new file mode 100644
index 0000000000..723f96bf6b
--- /dev/null
+++ b/macros/latex/contrib/globalvals/globalvals.tex
@@ -0,0 +1,83 @@
+\documentclass[a4paper]{ltxdoc}
+\usepackage{globalvals}
+\usepackage{siunitx}
+
+\begin{document}
+\title{\textsf{globalvals} -- Resuable variables \\
+for use in large projects}
+\author{Charles Baynham}
+\date{2019/02/06 (v\,1.1)}
+\MaintainedBy{%
+This file is maintained by Charles Baynham.\\%
+Bug reports can be opened at\\%
+\url{https://github.com/charlesbaynham/globalvals}.
+}
+\maketitle
+
+\noindent
+The \textsf{globalvals} package allow the user to declare a variable which can then be used anywhere else in a document, including before it was declared. This can be useful in large projects, where value can be entered once and automatically updated throughout the document, without having to maintain a seperate file full of definitions.
+
+This is done by putting the definitions into the .aux files, therefore requiring two runs to get it right.
+
+It implements two commands: |\defVal{|\meta{key}|}{|\meta{value}|}| and |\useVal{<key>}|. |\defVal|
+sets up a global variable and |\useVal| recalls it.
+
+Using |\defVal| twice with the same \meta{key} will result in an error. Using |\useVal| for an undefined
+value will output the text ``\textsc{??}''.
+
+\section{Defining a value}
+\label{sec:defining}
+
+\DescribeMacro{\defVal}
+%
+Defining a macro can be done using the command
+\begin{quote}
+ |\defVal{|\meta{key}|}{|\meta{value}|}|
+\end{quote}
+
+For example, you might call
+\begin{quote}
+ |\defVal{software_version}{v1.65}|
+\end{quote}
+\defVal{software_version}{v1.65}
+
+\meta{value}s will be expanded, so you can also embed macros within your variables, e.g.:
+\begin{quote}
+ |\defVal{fractional_stability}{\SI{10E-16}{\per\sqrt\second}}|
+\end{quote}
+\defVal{fractional_stability}{\SI{10E-16}{\per\sqrt\second}}
+
+\section{Using a variable}
+
+\DescribeMacro{\useVal}
+To use a defined variable, use the command
+\begin{quote}
+ |\useVar{|\meta{key}|}|
+\end{quote}
+
+For instance, the values saved in section \ref{sec:defining} could be recalled using
+\begin{quote}
+ |\useVal{software_version}|
+\end{quote}
+and
+\begin{quote}
+ |\useVal{fractional_stability}|
+\end{quote}
+%
+to give ``\useVal{software_version}'' and ``\useVal{fractional_stability}''.
+
+Importantly, values may be used \textbf{before they are defined}. This is handy if you e.g.\ would like to refer to a quantity in your abstract but it's most sensible defined in a later chapter. Like so:
+\begin{quote}
+ |The clock's fractional accuracy is estimated as| \\
+ |\useVal{an_important_quantity}.| \\
+ ... \\
+ |\defVal{an_important_quantity}{\num{1E-18}}|
+\end{quote}
+to give
+\begin{quote}
+ The clock's fractional accuracy is estimated as
+ \useVal{an_important_quantity}.
+ \defVal{an_important_quantity}{\num{1E-18}}
+\end{quote}
+
+\end{document}