The concepts related to cross-referencing in LaTeX 2ε
LaTeX 2ε provides both items of numbered sectioning and a mechanism for cross-referencing the items of numbered sectioning.
Items of numbered sectioning are produced by macros like \chapter, \section, \subsection, \subsubsection (etc), \item (within an enumerate-like environment) and \caption (within environments for denoting floating objects with numbered captions like the figure-environment or the table-environment).
The mechanism for cross-referencing the items of numbered sectioning is formed by
cross-referencing-labels. A cross-referencing-label is a data-record which is given a name and which holds data needed for cross-referencing.
the macro \label which serves the purpose of writing to the .aux-files a cross-referencing-label/which serves the purpose of writing to the .aux-files a record of cross-referencing-data needed for cross-referencing (including the name of that record).
the cross-referencing-macros \ref, \pageref, \nameref, \autoref, \hyperref, etc. The cross-referencing-macros serve the purpose of accessing the records of cross-referencing-data and placing into the output-file (.pdf-file) the desired cross-referencing-phrases.
You always need to provide an argument holding the name of a record of cross-referencing-data/holding the name of a cross-referencing-label to these macros—e.g., \label{⟨name of cross-referencing-label⟩},
\ref{⟨name of cross-referencing-label⟩},
\pageref{⟨name of cross-referencing-label⟩},
\nameref{⟨name of cross-referencing-label⟩},
\autoref{⟨name of cross-referencing-label⟩},
\hyperref[⟨name of cross-referencing-label⟩]{⟨text⟩}, etc.
There are elements that connect the items of numberd sectioning and the mechanism for cross-referencing the items of numbered sectioning:
The internal macros that hold the current cross-referencing-data. (When further below in the text going into details, you will in this context stumble over macro-names which contain the phrase "@current", e.g., \@currentlabel, \@currentlabelname and \@currentHref.)
Items of numbered sectioning internally use the macro \refstepcounter
- both for incrementing counters
- and—in case the hyperref-package is loaded—for placing anchors=targets=named destinations for hyperlinks
- and for redefining/updating some of the internal macros that hold the current cross-referencing-data.
When the hyperref-package is loaded items of numbered sectioning internally use the macro \NR@gettitle for updating that internal macro which holds the name/title of the item of numbered section in question. That macro also belongs to the macros that hold the current cross-referencing-data.
In short you can say that during a LaTeX-run the current cross-referencing-data
- always stems from the last item of numbered sectioning encountered so far.
- is always reachable via expanding the internal macros that hold the current cross-referencing-data.
As already said, the command \label{⟨name of cross-referencing-label⟩} serves the purpose of writing to the .aux-files a record of cross-referencing-data needed for cross-referencing (including the name of that record).
The name of that record comes from the ⟨name of cross-referencing-label⟩-argument.
The cross-referencing-data comes from using/expanding the internal macros that hold the current cross-referencing-data.
The cross-referencing-data-records written to the .aux-files in turn are used by the cross-referencing-macros (\ref, \pageref, \nameref, \autoref, \hyperref, etc).
In fact, the .aux-files from the previous LaTeX-run—if existing—are read at the beginning of the current LaTeX-run.
Hereby a macro \r@⟨name of cross-referencing-label⟩ gets defined for each record of cross-referencing-data that was written by the \label-macro to the .aux-file during the previous LaTeX-run. Thus that \r@⟨name of cross-referencing-label⟩-macro expands to the record of cross-referencing-data written to the .aux-file by the \label-macro along with the corresponding ⟨name of cross-referencing-label⟩ during the previous LaTeX-run. Thus the cross-referencing-data delivered/displayed by referencing-macros in the current LaTeX-run stems from the previous LaTeX-run.
After at the beginning of the current LaTeX-run reading the .aux-files created during the previous LaTeX-run, the .aux-files of the previous LaTeX-run do get destroyed, and .aux-files will, during the current LaTeX-run, be created anew.
Referencing-macros just expand the \r@⟨name of cross-referencing-label⟩-macro belonging to the label which they shall refer to, and from the expansion/the obtained record of cross-referencing-data extract the data they need. (E.g., \pageref needs the number of the page, \ref needs the number of the section, ... )
At the end of the LaTeX-run, the records with cross-referencing-data from the previous LaTeX-run are still reachable via the \r@⟨name of cross-referencing-label⟩-macros, while the records with cross-referencing-data created during the current LaTeX-run are now available via the anew-created .aux-files.
Thus, at the end of the LaTeX-run the anew-created .aux-files are read for comparing the records of cross-referencing-data from the previous LaTeX-run to the records of cross-referencing-data written during the current LaTeX-run. In case cross-referencing-data changed and therefore another LaTeX-run is needed for having cross-referencing-commands display the changed data, via console and .log-file a message will be provided for informing the user about the need to re-run LaTeX: LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.)
Why at all going the .aux-file-route?
I don't see any other way of making available data needed for cross-referencing items of numbered sectioning that in the text appear after the cross-references.
By now I tried to give a rough overview about "how the machinery's cogwheels do mesh".
Let's now look at some details:
When LaTeX encounters a \label-command, this will cause writing a record of cross-referencing-data to the auxiliary-files at the time when the page which LaTeX is about to build while encountering/processing the \label-command in question is shipped out.
(Internally an \immediate\write is not used for the underlying writing-mechanism as this might yield, e.g., wrong page-numbers with \pageref-references as the process of building the page in question might not yet be finished at the time of processing the \label-command in question, and thus the page-counter might at the time of processing the \label-command in question still hold the value of the page that was build previously. Instead a so-called "delayed \write" is used, i.e., a \write which is not prefixed by \immediate and which thus does not get carried out at the time of processing the \label-command in question but does get carried out at the time of shipping out the page which LaTeX was about to build when encountering/processing the \label-command in question.
Actually internally a tricky combination of \protected@edef (which does perform total expansion of non-protected control-sequences immediately) and delayed \write (which does not expand things immediately but does expand and write things at the time of shipping-out the page in question) is used for implementing the underlying \protected@write-mechanism.)
The records of cross-referencing-data that get written to the auxiliary files when LaTeX encounters a \label-command are organized in so called \newlabel-entries. A \newlabel-entry within the auxiliary-files is of the following pattern:
When the hyperref-package is loaded:
\newlabel{<Name of cross-referencing-label>}%
{%
{<The printing of the value which that counter had right
after having been "refstepped" which was incremented via
\refstepcounter as the last one before encountering the
\label-command.
[\refstepcounter in turn is called by macros like \chapter,
\section, \item (within an enumerate-like environment),
\caption (within environments for denoting floating objects
with numbered captions like the figure-environment or the
table-environment.)]
\refstepcounter provides this piece of data to the \label-
command by (re)defining the macro \@currentlabel to provide
the expansion of the sequence \p@<counter>\the<counter>
belonging to the <counter> that is "refstepped".
This piece of data is retrieved by the \ref-command.>%
}%
{<The printing of the number of the page which LaTeX was about
to build when encountering the \label-command.
This piece of data comes from expanding the macro \thepage
at the time of shipping out the page.
This piece of data is retrieved by the \pageref-command.>%
}%
{<The name/title of the sectioning-item which caused
\refstepcounter to increment the counter mentioned above.
If, e.g., the causing sectioning-item was a command
\section{About mice and elephants}, this will be the phrase
"About mice and elephants". If, e.g., the causing
sectioning-item was a a table-environment or a figure-
environment, this will be the phrase "table 4" or the phrase
"figure 5". If, e.g., the causing sectioning-item was an
\item-command within an enumerate-environment, this will be
the phrase "item 23".
This piece of data is to be provided by the items of
sectioning via (re)defining the macro \@currentlabelname.
Redefining \@currentlabelname is not done by the macro
\refstepcounter but often is done by the macro \NR@gettitle.
This is because \refstepcounter only takes the name of a
LaTeX-counter as its argument for dealing with that
counter and with named destinations/targets/anchors related
to that counter and therefore has no information about
the name/title of the corresponding item of sectioning.
Info about the name/title of the corresponding item of
sectioning often is passed to \NR@gettitle by sectioning-
commands. \NR@gettitle in turn calls \GetTitleString for
pre-processing things and hereby handling things that are
undesired when referencing and then redefines
\@currentlabelname. E.g., if somebody does
\section{Title of the section\label{label of the section}}
, then you don't want the label to be placed with each
reference to the title of the section. Therefore the
\label-command needs to be removed. \GetTitleString does
such things and more.
This piece of data is retrieved by the \nameref-command.>%
}%
{<The name of the anchor for hyperlinks whose automatic
placement was caused by the \refstepcounter-command
mentioned above, that also incremented the counter mentioned
above.
The sequence which forms the name of the counter incremented
by \refstepcounter as the last one before encountering the
\label-command usually is a subset of the sequence that
forms the name of the anchor that was placed automatically
as the last one by \refstepcounter (or by \phantomsection as
a special case) before the \label-command in question was
encountered.
In oder to ensure unique anchor names, the sequence forming
the anchor-name besides the counter-name has elements that
come from expanding \theH<counter>. Therefore with the
hypperref package to each <counter> a macro \theH<counter>
must exist which expands to that counter's value in a way
where uniqueness of names of anchors is ensured throughout
the entire document.
\refstepcounter will provide this piece of data to the
\label-command by (re)defining the macro \@currentHref.
This piece of data is retrieved by the \autoref-command and
by all other cross-referencing-commands that besides
delivering a textual phrase also deliver a hyperlink, e.g.
\ref, \pageref, \nameref, \hyperref. (The starred variants
\ref*, \pageref*, \nameref* do not deliver hyperlinks.)>
}%
{<An empty data-field. In case the auxiliary-file in question
does not belong to this document but is imported by the
command \externaldocument of the xr package or the
xr-hyper-package, this will hold the url under which the
referenced external document can be found.
That url is provided via `\externaldocument` at the time
of importing the referencing-data from the external
document's .aux-files.
This piece of data is retrieved by all cross-referencing-
commands that besides delivering a textual phrase also
deliver a hyperlink.>
}%
}%
When no additional package is loaded:
\newlabel{<Name of cross-referencing-label>}%
{%
{<The printing of the value which that counter had right
after having been "refstepped" which was incremented via
\refstepcounter as the last one before encountering the
\label-command.
[\refstepcounter in turn is called by macros like \chapter,
\section, \item (within an enumerate-like environment),
\caption (within environments for denoting floating objects
with numbered captions like the figure-environment or the
table-environment.)]
\refstepcounter provides this piece of data to the \label-
command by (re)defining the macro \@currentlabel to provide
the expansion of the sequence \p@<counter>\the<counter>
belonging to the <counter> that is "refstepped".
This piece of data is retrieved by the \ref-command.>%
}%
{<The printing of the number of the page which LaTeX was about
to build when encountering the \label-command.
This piece of data comes from expanding the macro \thepage
at the time of shipping out the page.
This piece of data is retrieved by the \pageref-command.>%
}%
}%
When, at the beginning of the current LaTeX-run, the auxiliary-files created during the previous LaTeX-run are read, and thus all the \newlabel-entries therein are carried out, processing a \newlabel-entry yields defining a macro \r@⟨name of cross-referencing-label⟩ which expands —in case of hyperref being loaded—to five respective—in case of hyperref not being loaded—to two undelimited/brace-nested items, each of them holding its piece of data. These undelimited/brace-nested items in turn can be used as arguments for macros that process undelimited arguments.
A cross-referencing-command like \ref{⟨name of cross-referencing-label⟩} or \pageref{⟨name of cross-referencing-label⟩} or \autoref{⟨name of cross-referencing-label⟩} or \nameref{⟨name of cross-referencing-label⟩} or \hyperref[⟨name of cross-referencing-label⟩]{⟨text⟩} will expand the corresponding \r@⟨name of cross-referencing-label⟩-macro and pick those data-piece-holding-arguments that are needed for creating the desired reference.
When, at the end of the current LaTeX-run, the auxiliary-files created during the current LaTeX-run are read, and thus all the \newlabel-entries therein are carried out, a few of the things that underlie the \newlabel-command are redefined so that this time processing a \newlabel-entry yields comparing its content to the expansion of the corresponding \r@...-macro and, in case of finding differences, causing LaTeX to inform the user at the end of the LaTeX-run about the need to re-run LaTeX: LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right. This way at the end of the current LaTeX run data that is held in the \r@-macros and that comes from the previous LaTeX run is compared to data that comes from the current LaTeX-run for detecting whether data for cross-references has changed and thus detecting whether LaTeX needs to be re-run for in the next LaTeX-run displaying the cross-referencing-data coming from this LaTeX-run.
Now let's look at the obscurity that causes the problems with cross-referencing experienced by you:
Above was said: Macros that produce items of numbered sectioning—e.g., \chapter, \section, \subsection, \subsubsection, (etc), \item (within an enumerate-like environment), \caption (within environments for denoting floating objects with numbered captions like the figure-environment or the table-environment)—internally use \refstepcounter both for incrementing counters and for placing anchors for hyperlinks and for redefining/updating some of the internal macros that hold the current cross-referencing-data, as there are: \@currentlabel and \@currentHref.
Macros that produce items of numbered sectioning often internally use \NR@gettitle for redefining \@currentlabelname.
Thus a \label-command will cause providing to referencing-commands in the next LaTeX-run the data provided by the last \refstepcounter-command and by the last \NR@gettitle-command that in this LaTeX-run occurred before the \label-command in question.
The situation about redefining/updating the internal macros that hold the current cross-referencing-data is funny:
\refstepcounter's redefining/updating of the macro \@currentlabel is implemented in the LaTeX2e-kernel already.
Redefining/updating this macro is restricted to the current scope.
\NR@gettitle's redefining/updating of the macro \@currentlabelname is implemented in the hyperref package/in the package nameref by means of macros from the package gettitlestring.
Redefining/updating this macro is restricted to the current scope.
\refstepcounter's redefining/updating of the macro \@currentHref is implemented in the hyperref package.
Redefining/updating this macro is not restricted to the current scope but is global.
A strange effect of this mixture of local updating and global updating is:
If a counter is "refstepped" inside a local scope, which happens, e.g., with an item within an enumerate-environment, and a \label gets placed right after the closing of that local scope, \@currentlabel will hold the value of the counter that was "refstepped" as the last one before that local scope was opened up, while \@currentHref will hold the name of the anchor that was placed as the last one via \refstepcounter before that local scope was closed.
In such situations, e.g, the textual phrase delivered by \ref will denote the number of that item of sectioning which occurred as the last one before opening up the local scope, while clicking the hyperlink created by \ref will not lead to that item of sectioning but will lead to the item of sectioning which occurred as the last one before closing the local scope in question.
As \autoref relies on deriving counter-names from anchor-names—it needs counter-names for calling the appropriate \⟨counter⟩autorefname-macros/\⟨counter⟩name-macros—, you might also get weird mixtures consisting of the name of the counter that was "refstepped" as the last one before closing the local scope and the value of the counter that was "refstepped" as the last one before opening the local scope in question.
E.g., with the example below,
\ref{ShouldReferToSectionThree} produces a textual reference to section 3 while the hyperlink leads to First Item.
\autoref{ShouldReferToSectionThree} produces a textual reference to "item 3" while there definitely is no item 3 and a hyperlink that leads to First Item.
\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{Section One}
\section{Section Two}
\section{Section Three}
\newpage
\begin{enumerate}
\item First Item.
\end{enumerate}
\label{ShouldReferToSectionThree}
section \ref{ShouldReferToSectionThree}
\autoref{ShouldReferToSectionThree}
\end{document}
As a rule of thumb place \labels as close as possible right behind those items of sectioning that you wish to refer to:
\documentclass{article}
\usepackage{hyperref}
\begin{document}
\section{Section One}
\section{Section Two}
\section{Section Three}
\label{ShouldReferToSectionThree}%
\newpage
\begin{enumerate}
\item\label{ShouldReferToFirstItem} First Item.
\end{enumerate}
section \ref{ShouldReferToSectionThree}
\autoref{ShouldReferToSectionThree}
item \ref{ShouldReferToFirstItem}
\autoref{ShouldReferToFirstItem}
\end{document}
Applying this rule of thumb to your code yields:
\documentclass{report}
\usepackage{caption}
\usepackage{longtable,ltcaption}
\usepackage{hyperref}
\usepackage{newfloat}
\usepackage{xcolor}
\usepackage{enumitem}
\usepackage{colortbl}
%% Formatting table colors
\definecolor{guidancebox}{gray}{0.95}
\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
%% New environment for guidance boxes
\DeclareFloatingEnvironment{guidancebox}[Guidance box][List of guidance boxes]
\newcommand*{\guidanceboxautorefname}{Guidance box}
\renewenvironment{guidancebox}{%%%%%
\renewcommand\LTcaptype{guidancebox}%%%%%
\longtable
}{\endlongtable}
\begin{document}
\begin{guidancebox}{C{0.5\textwidth}}
\hline
\rowcolor{guidancebox}%
\label{guide}%<--------------------
This guidance box provides guidance on the following items:
\begin{itemize}
\item first item
\item second item
\end{itemize}\\
\rowcolor{guidancebox}\\
\hline
\caption{caption of this guidance box.}%
\end{guidancebox}
Look at \autoref{guide} above. Now look at \autoref{guide2} below:
\begin{guidancebox}{C{0.5\textwidth}}
\hline
\rowcolor{guidancebox}%
\label{guide2}%<--------------------
This guidance box provides guidance on the following numbered items:
\begin{enumerate}
\item first item
\item second item
\end{enumerate}\\
\rowcolor{guidancebox}\\
\hline
\caption{caption of this guidance box.}%
\end{guidancebox}
\end{document}
