# How does one set custom labels for description lists?

Every now and then I use the description list environment

\begin{description}
\item[foo]  foo is good
\end{description}


to create lists with non-numerical labels. Unfortunately the description list does not support the label-reference pair as normal latex: i.e. if I write

\begin{description}
\item[foo] \label{foo} foo is good
....
\end{description}
....
For good things (see, for example \ref{foo})...


the reference does not point to the item in the list. Instead it points to the closest environment that supports labeling (usually the subsection). So instead of showing the text foo (in boldface), it shows something like 2.2.1 (the subsection corresponding to where the description environment is sitting).

My question: is there a way or a package which allows references to description list items? My current work-around is to just type the text myself in the spot (since I named it myself, and it is not numbered, the formatting is unlikely to change the label =). But one of the good things about the label/reference pairs in latex is the implementation in pdflatex that allows in PDF hyperlinks between references and the objects referred to, this I cannot replicate myself.

Edit: let me rephrase my question. The primary goal is not to display \ref to something other than what LaTeX thinks the \label is. There are many ways to deal with it, some of which outlined in Michael Underwood's helpful answer below. What I am looking at is whether there exists an implementation of a list environment which is like the built-in description environment in that the displayed "title" for the list item is completely customized, while having support for \labels. (The built-in description environment does not support \labels, whereas the built-in enumerate environment does not support customized "title"s.) The enumitem package adds some customizability to the environments, but as far as I can tell it doesn't support exactly what I want.

-
@willie-wong If you think that his answer is "helpful," doesn't it deserve your upvote? –  vanden Jul 27 '10 at 3:02
Should an upvote be given to a generically helpful answer that does not address the question asked at all? He accurately described the work-around I alluded to in my question, but did not provide an answer to the specific question asked. So no, I don't think it deserve an upvote. –  Willie Wong Jul 27 '10 at 4:58
His second answer however, is wonderful. I'll vote for that once my vote limit cap is cleared in a few hours. –  Willie Wong Jul 27 '10 at 21:26

I don't know of a pre-built package that allows you to do this, but if I correctly understand what you're after then it is achievable by combining a counter with custom commands and the hyperref package. The first step is to create a new counter for the described items, and a pair of new commands to use in place of \item and \ref. In the preamble, put the following:

\newcounter{desccount}
\newcommand{\descitem}[1]{%
\item[#1] \refstepcounter{desccount}\label{#1}
}
\newcommand{\descref}[1]{\hyperref[#1]{#1}}


The new command \descitem is to be used in place of \item within a description environment. It takes a single argument and creates an item labeled with it. It also increments the new counter, sets it as the current value for the \ref command, and labels the location with the item's descriptor. The new command \descref takes the same argument and makes a hyperlink reference to the label, displaying the argument instead of the counter's value.

The commands work together like this:

\begin{description}
\descitem{foo} foo is good
\end{description}
...
For good things (see, for example \descref{foo})...

-
Sweet. Just tried it out and it works well. Ideally I would have liked to have the key and the displayed label possibly different, but I think I know roughly how to hack it to a way that works. (I'll up-vote this answer in a bit; I've hit my daily vote limit so cannot vote right now.) –  Willie Wong Jul 27 '10 at 21:25

Honestly, I would not recommend using a description/enumeration/itemization for your task, but from the answer I will provide now, you could derive how to overwrite the \item macros/commands if you really want to use a description environment.

Here is what I would do:

\newcounter{foocnt}   %% define a counter
\setcounter{foocnt}{0} %% set the counter to some initial value (not really important)
%%%% Parameters
% #1: Title
\newenvironment{fooEnvironment}[1]
{
\renewcommand{\thefoocnt}{\textbf{#1}}  %% this is where the display of the counter is overwritten/modified
\refstepcounter{foocnt} %% increment counter (in this case we write the custom label/title to a temp. file which is read when the document resolves a \ref)
\par  %% start new paragraph (this is just an example for format modifications)
\textbf{#1:}  %% display the title before the content of the environment is displayed
}{
\par  %% another paragraph after the environment
}

This solution can be used as follows to be equivalent to your example:


\begin{fooEnvironment}{foo}
foo is good
\label{fooLabel}
\end{fooEnvironment}
\begin{fooEnvironment}{bar}
\label{barLabel}
\end{fooEnvironment}
For good things (see, for example \ref{fooLabel})...


The lesson learned here is: At the definition of a counter with name blubb there is a macro defined called \theblubb which contains the string being printed in the document when the counter is referenced. Obviously, a solution where an additional parameter to the environment is provided to make the display of the reference different to the title is possible as well.

-

For those who are interested in links to arbitrary text, somewhere in the document, the following variations offers a solution, with custom text for the link, different than the label it point to:

\newcounter{desccount}
\newcommand{\descitem}[1]{%
\refstepcounter{desccount}\label{#1}%
}
\newcommand{\descref}[2][\undefined]{%
\ifx#1\undefined%
\hyperref[#2]{#2}%
\else%
\hyperref[#2]{#1}%
\fi%
}%


and in the text use:

\descitem{linklabel} text next to label, you will be directed here...

\newpage
\descref[after clicking on this optional text]{linklabel}

-
This seems to be answering my comments here. (For those who didn't read through the whole thread; incidentally this also means that the hyperref package is used for this answer.) –  Willie Wong Jul 22 '13 at 8:09

It's possible to change what \ref will display for equations if you include the amsmath package and use the \tag command, like so:

\usepackage{amsmath}
...
$$\label{eq:energy}\tag{Einstein} E=mc^2$$
...
Invoking the energy-mass equivalence of \ref{eq:energy}


I'm not aware of a straightforward method to accomplish it in general though, since if the tag you want is not going to be changed by edits or recompilations, there's no need to make TeX keep track of it.

I would accomplish what you are attempting by defining a new command to be the text of the description:

\newcommand{\foo}{foo}
....
\begin{description}
\item[\foo] foo is good
....
\end{description}
....
For good things (see, for example \foo)...


That way if you decide later that the description should instead be bar, you just have to change the one defining command to \newcommand{\foo}{bar} and all subsequent places that you use \foo will automatically get updated to display bar.

-
Your second idea is what I've been doing. I'd really prefer a solution that allows me to "link back" via the internal links in the PDF file. I've found out that the built-in "description" list environment is designed to be label-less. So I'd probably have to look at external packages for this. –  Willie Wong Jul 26 '10 at 22:31
Using the hyperref package it's possible to display something other than the label that's being referenced, for example \hyperref[eq:fib]{Fibonacci Sequence}. For more details, see en.wikibooks.org/wiki/LaTeX/Hyperlinks –  Michael Underwood Jul 26 '10 at 22:51
But if the <code>\label</code> object is referring to the wrong thing (the subsection, and not the list object), then hyperref will jump it to the wrong spot in the document. This would not be an acceptable work around. Again the problem seems to be that the built-in description list has no support for labels. –  Willie Wong Jul 27 '10 at 1:44

Okay, after Michael's second answer I had an idea which I want to just document here. Instead of using the description environment, it seems that another way is to abuse the list environment. The following snipplet is what can be done

\newcounter{foobarcounter}
\renewcommand{\thefoobarcounter}
{({\ifcase\value{foobarcounter}\or foo\or bar\else ehhh\fi\relax})}
\begin{list}{\thefoobarcounter}{\usecounter{foobarcounter}}
\item\label{foodesc} Foo is good