bug_705285 Allow non-globally unique page/section labels when using tagfiles

[albert-github]

The basic idea is that occurrences in the "normal" files are preferred above occurrences in a tag file

To be able to do this there should also be a mechanism to refer (by means of \ref) to a page section in the project that is "linked" by means of a tag file.

• define a tag and store this in the tag file (doxygen.cpp extend GENERATE_TAGFILE with the possibility to specify a tag), read the tag back when reading the tag file (tagreader.cpp) and adjust the checking of the GENERATE_TAGFILE (configimpl.l)
• extend the reading of the \ref command to support a tag, this is done by means of having {<tag>}<ref_word> (doctokenizer.l)
• adjusting page names (to be used in \ref) when read pages from a tag file, in this way the page could be accessed by means of the original name or the adjusted name with the tag, also the section names should be adjusted (otherwise there could be double section names) (tagreader.cpp).
  • when there is a page in the main part of the documentation (so not linked through a tag file) and the page name is defined here it should not be in present from the tag file (these tagged pages are still accessible through the version with the tag name though), (doxygen.cpp with getPageDoc and checkRemovePageDoc).
  • when a page is present in multiple tag files this is not unique and should be removed (these tagged pages are still accessible through the version with the tag name though) (doxygen.cpp getPageDocTag, countPageDocTag and checkRemovePageDoc).
• when there are section names that occur in multiple tag files the names of the second and subsequent occurrences are not recorded, so always the first one is used. To prevent this these names are stored and after the tag file reading and reading of the "normal" files these section names are removed (Note 1) that a maximum of 1 occurrence can remain as read from tag files, 2) in case the name also occurs in the "normal" files this occurrence overwrites the possible present version from the tag files, commentscan.l. 3) in case of the an occurrence in multiple tag files a warning could be given, now suppressed, but I think in that case it should be suppressed by means of a Doxyfile setting). (tagreader.cpp and section.h)

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
19 Code Smells

No Coverage information
0.0% Duplication

[doxygen]

@albert-github I was looking at this change, and I'm trying to understand the requirements behind it.

Let me summarize it to see if I got it correctly:

Given some input files and a set of tag files.

• When label x is present in the input and also imported via a tag file, \ref x shall point to the input (a local label has preference over an imported label).
• To explicitly link to a label imported from a tag file \ref {tag}x shall be used (where tag uniquely identifies the tag file).
• When a label y is unique (when combining input and tag files) and defined in a tag file tag, the explicit tag can be omitted, i.e. both \ref y and \ref {tag}y are equally valid and point to the tag file (needed for ease of use and backward compatibility).
• When a label x is defined in multiple tag files, but not in the input, it shall have an explicit reference, i.e. \ref {tag1}x or \ref {tag2}x are valid and \ref x shall produce an ambiguity warning (we could still link to one of tag files for backward compatibility).

[albert-github]

@doxygen that is indeed the intention.