Numbered anchors in doxygen

Question

I have quite a lot of anchors to picture in doxygen, e.g.

\anchor pic_foo
\image html foo.gif "My Caption"
\anchor pic_bar
\image html bar.gif "My Caption"

Everytime when I use \ref to link one of those, I have to make up some nice description so the raw name of the anchor doesn't appear in output.

Is it possible to have something like numbered anchors in doxygen where the link text will be the number of that anchor? Ideally something like:

\anchor pic_foo
\image html foo.gif "My Caption"
\anchor pic_bar
\image html bar.gif "My Caption"

As Figure \ref pic_foo shows... Figure \ref pic_bar is...

should ideally translate to:

As Figure 1 shows... Figure 2 is...

where the number is the link. I would be happy with every kind of counting scheme (documentation global or page local).

Answer 1

I don't think that automatic number of figures, either within a page or across the whole documentation, is possible with doxygen (I would be happy to be corrected here). However, an easy solution to your question is the replace your anchor text with spelt out numbers, i.e. "one", "two", "three"... etc. Alternatively, if you have lots of figures you could use Roman numerals. Plain numbers don't seem to work as anchor links.

Your example will then become, with additional text in the figure captions,

\anchor one
\image html foo.gif "Figure one: My Caption"
\anchor two
\image html bar.gif "Figure two: My Caption"

As Figure \ref one shows... Figure \ref two is...

resulting in

Here Figure one shows... Figure two is...

with one and two hyperlinks to your figures.

You can then define a alias in your configuration file, say \fref, defined to be Figure \ref which will automatically preceed the hyperlinked numbers with the text "Figure".

Is this solution acceptable? The only other alternative I can think of involves post processing the doxygen output, but the above solution is by far the simplest.

Update

The following Python code will transform anchor references to an incrementing counter:

# Test documentation.
s = r"""
\anchor pic_foo
\image html foo.gif "My Caption"
\anchor pic_bar
\image html bar.gif "My Caption"

As Figure \ref pic_foo shows... Figure \ref pic_bar is...
"""

# Split string into a list of lines.
s = s.split('\n')

# Dictionaries for mapping anchor names to an incrementing counter.
d = {}

numbers = {1: 'one',
    2 : 'two',
    3 : 'three'}

counter = 1

# Find all anchor links and map to the next counter value.
for line in s:
    if r'\anchor' in line:
        d[line.split(r'\anchor ')[1]] = numbers[counter]
        counter += 1

# Reform original string.
s = '\n'.join(s)

# Replace anchor links with appropriate counter value.
for key, value in d.items():
    s = s.replace(key, value)

print s

Running this script results in the output

\anchor one
\image html foo.gif "My Caption"
\anchor two
\image html bar.gif "My Caption"

As Figure \ref one shows... Figure \ref two is...

It is trivial to modify the above script to read from standard input and write to standard out, so this can easily be used in conjunction with the INPUT_FILTER configuration file option.

One thing to note is that the dictionary numbers has to be extended to allow for more than three figures to be included. This is again trivial, but probably not easily scalable. Solutions for mapping from arbitrary numbers to the appropriate word(s) are available (see other questions on this site) so I haven't bothered to implement this here.