\cite rejects valid BibTeX keys (Origin: bugzilla #702584)

[doxygen]

status RESOLVED severity normal in component general for ---
Reported in version 1.8.4-GIT on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

• mwe.tar.gz (ID 247207)

On 2013-06-18 16:52:29 +0000, Alexandre Duret-Lutz wrote:

I'm using a 10-day old version compiled from git (SHA: 8cd4425).

My lab maintain several large BibTeX files in which each entry key has the form

name.year.conference

For instance

@InProceedings{ vardi.86.lics,
author = {Moshe Y. Vardi},
title = {An Automata-Theoretic Approach to Automatic Program
Verification},
booktitle = {Proceedings of the 1st IEEE Symposium on Logic in Computer
Science (LICS'86)},
pages = {332--344},
year = {1986},
publisher = {IEEE Computer Society Press}
}

Unfortunately, when I use

/// \brief First test
///
/// bar
/// \cite{vardi.86.lics}
/// baz
int test1(int f);

and run the Doxygen with default options (expect for the obvious CITE_BIB_FILES = myfile)

I get

[...]
/home/adl/doxygen-bug/test.hh:5: warning: Invalid or missing cite label
[...]
/home/adl/doxygen-bug/test.hh:5: warning: unable to resolve reference to `vardi' for \cite command
[...]

and the generated HTML documentation for test1()

First test.

bar [vardi].86.lics} baz

So apparently Doxygen considers only the first component of the citation key, but this contradicts its documentation that states that "The must be a valid BibTeX label".

I can't point to a definition of what characters are allowed as keys in a BibTeX entry. I've seen : and - used as separators as well.

Unfortunately, renaming these BibTeX entries to match what Doxygen expect is not a satisfying option for me, because the BibTeX files are used in too many places. Being able to refer to these from Doxygen would have been a bonus.

I nonetheless tried to play with this little example, and had other surprises:

@InProceedings{ vardi,
author = {Moshe Y. Vardi},
title = {An Automata-Theoretic Approach to Automatic Program
Verification},
booktitle = {Proceedings of the 1st IEEE Symposium on Logic in Computer
Science (LICS'86)},
pages = {332--344},
year = {1986},
publisher = {IEEE Computer Society Press}
}

/// \brief First test
///
/// bar
/// \cite{vardi}
/// baz
int test1(int f);

Gives the very same diagnostics (!) and produces:

First test.

bar [vardi]} baz

First test q barq vardi baz.

hinting that probably the use of braces is unwelcome (I believe people using BibTeX are used to call \cite with braces, so it would be very nice to support it).

My next try without braces was more successful, but not entirely.

/// \brief First test
///
/// bar
/// \cite vardi
/// baz.

int test1(int f);

This replaced all the warnings by

citelist:3: warning: expected

tag but found

instead!
citelist:4: warning: unexpected end of comment while looking for a html description title

and successfully output a link to the bibliography in the description of test1(). Unfortunately the bibliography page is empty :-(

I have found no file named citelist, so I find these warnings very unhelpful.

On 2013-06-18 19:36:10 +0000, Dimitri van Heesch wrote:

The \cite command does not support { .. } and no dots in the label at the moment.
With those limitation in mind you last example should work however.

Can you attach a minimal self-contained example (source + config file in a tar or zip) so I can reproduce the problem?

On 2013-06-18 20:02:47 +0000, Alexandre Duret-Lutz wrote:

Created attachment 247207
MWE

Here is a MWE containing Doxyfile, test.hh and my.bib for the last scenario. I've also included logs (separate for stdout and stderr) and the html output where the citelist.html page show no reference. (The generated LaTeX document is OK.)

On 2013-08-18 10:11:57 +0000, albert wrote:

Example has been provided.
With version 1.8.4 (and git version) the related page "Bibliographic References" is still empty.
During processing with 1.8.4 a file citelist.doc is generated, though the error message states citelist. In this, automatically generated, citelist.doc the code:

exists.
NOTE: in version 1.8.4-git the file citelist.doc does not exist anymore

On 2014-06-19 17:42:21 +0000, albert wrote:

For the problem regarding the problem as shown in the attached MWE file I've pushed a proposed solution to github (pull request 186)

On 2014-07-06 15:55:55 +0000, albert wrote:

I've just pushed a proposed patch for the original problem of this bug report (pull request 196)

Added possibility for . (dot) and + (bit analogous to file names. A . (dot) cannot be the last character)

On 2014-07-14 17:16:17 +0000, albert wrote:

Fix has been include July 13 2014 into master branch of git.

On 2014-08-21 17:15:28 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.8. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information
that you think can be relevant (preferrably in the form of a self-contained example).