Representation of bibliographic reference in output

[albert-github]

With doxygen version 1.14.0 it is possible not just refer to a bibliography reference by means of a number like it is shown in HTML as:

The primary design goals of CGAL are described in [6]

but also by means of a author "abbreviation" with result:

The primary design goals of CGAL are described in [Fabri et al.]

just by means of defining the reference not by \cite but by means of \cite{shortauthor}

(see e.g. https://cgal.geometryfactory.com/CGAL/Manual_doxygen_test/CGAL-6.1-Ic-161/master/Manual/devman_intro.html)

[lrineau]

/build:test

[lrineau]

/build:test

Stupid me... our build bot does not use Doxygen 1.14.0, for now.

[albert-github]

@sloriot @lrineau

Any chance that this will be integrated in CGAL or is there something further to be done here

[sloriot]

The output looks good in the text but the fact that the bibliography page is still using the numbers makes it hard to do the matching IMO. I don't have a strong opinion so we can merge it if people are happy with the change.

[albert-github]

@sloriot

Interesting observation.
I made a small example with a potential solution.
Bib file

@book{ cgal:eb-19a
, title        = "{CGAL} User and Reference Manual 4.14"
, author      = "{The CGAL Project}"
, publisher     = "{CGAL Editorial Board}"
, edition     = "{4.14}"
, year         = 2019
, url =    "https://doc.cgal.org/4.14/Manual/packages.html"
}
@book{ cgal:eb-26a
, title        = "{CGAL} User and Reference Manual 6.2"
, author      = "{The CGAL Project}"
, publisher     = "{CGAL Editorial Board}"
, edition     = "{6.2}"
, year         = 2026
, url =    "https://doc.cgal.org/6.2/Manual/packages.html"
}

source file

/** \file
  * The old manual: \cite cgal:eb-19a, \cite{shortauthor} cgal:eb-19a
  *
  * The new manual: [\cite{nopar} cgal:eb-26a, \cite{shortauthor,nopar} cgal:eb-26a ]
  *
  */

resulting in:

maybe the "26" version is more what you like / would be better.

Example: example.tar.gz

[albert-github]

Or maybe even nicer:

The new manual: [\cite{nopar} cgal:eb-26a‌: \cite{shortauthor,nopar} cgal:eb-26a]

(Need ‌ as otherwise we cannot have the : and the command \: does not exits)

[sloriot]

We can try updating the macro and see what it does in a testsuite run. But I remember @lrineau did not like ‌ the last time you proposed something using it.

[albert-github]

@sloriot The ‌ version is not part of the PR but only a suggestion for an even nicer version. Also the , version is not part but the both solutions were just suggestions based on the comment #8905 (comment), so it is up to the CGAL project which one would you like to have?

[sloriot]

I've done an update that looks good to me:

but it means that we have to review all usage of the macro:

[sloriot]

But that's 247 files to look at...

[albert-github]

That is quite a few to look at, but I think the update is worthwhile and probably not all have to be checked as the update is done by an ALIASES so automated.