# How to create my own ref label system?

I want to add a hyperlink to sections where a file is discussed. Additionally the usage should be added to the index. In principle this is very close to the label ref system.

A simple approach would be this

\newcommand{\labelfile}[1]{%
\hypertarget{file:#1}{}%
\index{file!#1}%
\csname doc@file@#1\endcsname%
}

\newcommand{\file}[1]{%
\ifcsdef{doc@file@#1}{%
}{%
\texttt{#1}%
}%
}


which would be used as

\section{about links in pdf}
The code is in \file{preamble/hyperref.tex}
...
\section{preamble/hyperref.tex}
\labelfile{preamble/hyperref.tex}


It however does not work, because the label is created after the ref command. So I need to add everything to the aux file and read it again. However how do I implement that?

Additionally I would like to have everything in the index as

files
preamble
hyperref.tex


That however requires to pass it to the index as

\index{files!preamble!hyperref.tex}


I however have it as

\index{files!preamble/hyperref.tex}


how can I replace the char / with ! ?

-

You can use the normal \label/\ref system for this. The link is then done with

\hyperref[label]{text}


Discussion \label setting and destination name

A \label uses the currently active anchor (usually, the last anchor set) when it writes the reference data into the .aux file. The example does not show whether the target for preamble/hyperref.tex should be the section with the same title or it should moved below to the position of \labelfile. In the first case, the part in the solution example file between the %%% markers should be:

%%%
\newcommand*{\labelfile}[1]{%
\label{file:#1}%
\index{file!#1@\string\FileName{#1}}%
}
%%%


If \labelfile should set its own anchor, but the destination name does not matter, then the part between the %%% markers should be:

%%%
\newcommand*{\labelfile}[1]{%
\phantomsection
\label{file:#1}%
\index{file!#1@\string\FileName{#1}}%
}
%%%


The anchor setting is done by \phantomsection.

The full variant below also controls the destination name. It uses the fact that hyperref's redefinition of \refstepcounter sets an anchor. (With default options) the destination name is constructed from the counter name and the counter value. Different destinations must not share the same destination name. A problem is that \the<counter> is not always unique. Therefore hyperref uses \theH<counter> for destination names. The file names here are unique because they are also used for \label. \thefile shows the "file number" that is not needed here (at end of document it could be used to get the maximum number of files). \theHfile is completely different, it shows the file name and the destination name would be file.example.tex for file example.tex, the first part file is the counter name, the following dot is hardwired, and the remaining part is the file name.

File name formatting

File names can be formatted in many ways. There are packages that deal with hyphenation, font settings, … As an example, I have used package url to define a formatting command \FileName and also added this to the index entry to show the special syntax of the index entries. I assume that the file names does not contain too fancy characters. Otherwise some extra work would be needed to deal with the problematic characters.

\documentclass{article}

\usepackage{hyperref}

\usepackage{url}
\DeclareUrlCommand{\FileName}{\urlstyle{tt}}

\usepackage{makeidx}
\makeindex

%%%
\newcounter{file}
\providecommand*{\theHfile}{\thefile}

\newcommand*{\labelfile}[1]{%
\renewcommand*{\theHfile}{#1}%
\refstepcounter{file}%
\label{file:#1}%
\index{file!#1@\string\FileName{#1}}%
}
%%%

\newcommand*{\file}[1]{%
\hyperref[file:#1]{\FileName{#1}}%
}

\begin{document}


Nice documentation of the answer! However I do not understand why the new \theHFile counter is required, since it is not used in \file. –  Matthias Pospiech Aug 3 '12 at 7:30