\documentclass[a4paper]{ltxdoc}
\usepackage{globalvals}
\usepackage{siunitx}

\begin{document}
\title{\textsf{globalvals} -- Resuable variables \\ 
for use in large projects}
\author{Charles Baynham}
\date{2019/01/23 (v\,1.0)}
\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}