0

I defined a guidancebox envirenment, which is similar to the longtable environment, only with a different counter/ caption tag and reference label. This works fine, except if I use enumerate inside this environment, while itemize does not give any trouble, see example below:

\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} 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.}
    \label{guide}
\end{guidancebox}

Look at \autoref{guide} above. Now look at \autoref{guide2} below:

\begin{guidancebox}{C{0.5\textwidth}}
    \hline
    \rowcolor{guidancebox} 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.}
    \label{guide2}
\end{guidancebox}

\end{document}

This gives the following output:

enter image description here

Obviously, I want the reference to be 'Guidance box 2' instead of 'item 2'. Does anyone have any thoughs on how to solve this?

Thanks in advance!

Tim

2

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, e.g., 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).

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 for placing anchors for hyperlinks
- and for redefining/updating the internal 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 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.
             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. 
             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: Items of numbered sectioning—e.g., 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)—internally use \refstepcounter both for incrementing counters and for placing anchors for hyperlinks and for redefining/updating the internal macros that hold the current cross-referencing-data, as there are: \@currentlabel, \@currentlabelname and \@currentHref.

Thus a \label-command will cause providing to referencing-commands in the next LaTeX-run the data provided by the last \refstepcounter-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.

\refstepcounter's redefining/updating of the macros \@currentlabelname and \@currentHref is implemented in the hyperref package.
Redefining/updating these macros 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 \@currentlabelname will hold the name of the item of sectioning that was created as the last one before that local scope was closed, and \@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—, 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}

enter image description here enter image description here

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}

enter image description here enter image description here

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}

enter image description here

0

Using cleveref is safer.

\documentclass{report}

\usepackage{caption}
\usepackage{longtable,ltcaption}
\usepackage{newfloat}
\usepackage[table]{xcolor}
\usepackage{enumitem}
\usepackage{hyperref}
\usepackage{cleveref}

%% 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]
\crefformat{guidancebox}{#2Guidance Box #1#3}
\renewenvironment{guidancebox}
  {\renewcommand\LTcaptype{guidancebox}\longtable}
  {\endlongtable}

\begin{document}

\begin{guidancebox}{C{0.5\textwidth}}
    \hline
    \rowcolor{guidancebox} 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.}\label{guide}
\end{guidancebox}

Look at \cref{guide} above. Now look at \cref{guide2} below:

\begin{guidancebox}{C{0.5\textwidth}}
    \hline
    \rowcolor{guidancebox} 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.}
    \label{guide2}
\end{guidancebox}

\end{document}

enter image description here

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.