External documentation links that shouldn't have a file extension have HTML_FILE_EXTENSION added to them.

[daliborfox]

Describe the bug Hello! I'm writing a win32 application that I'm documenting with Doxygen, and I'd like to add links to the MSDN API documentation, I think it would improve the user experience of working with the documentation.

The problem is that MSDN links don't include a file extension, here is an example for the ScriptShape function: https://learn.microsoft.com/en-us/windows/win32/api/usp10/nf-usp10-scriptshape

So when I've defined a tag file like this:

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<tagfile>
  <compound kind="file">
    <name>usp10.h</name>
    <path></path>
    <filename>api/usp10</filename>
    <member kind="function">
      <type>HRESULT</type>
      <name>ScriptShape</name>
      <anchorfile>api/usp10/nf-usp10-scriptshape</anchorfile>
      <anchor></anchor>
      <arglist>(HDC hdc, SCRIPT_CACHE *psc, const WCHAR *pwcChars, int cChars, int cMaxGlyphs, SCRIPT_ANALYSIS *psa, WORD *pwOutGlyphs, WORD *pwLogClust, SCRIPT_VISATTR *psva, int *pcGlyphs)</arglist>
    </member>
  </compound>
</tagfile>

And I've added it to my Doxyfile: TAGFILES = ./win32-msdn.tag=https://learn.microsoft.com/en-us/windows/win32

It's correctly generating links to the appropriate MSDN pages, the usp10.h header file and the ScriptShape() function... though it's appending an extra .html to the links, and that's causing a 404 error. It's appending the extension defined as HTML_FILE_EXTENSION in the Doxyfile, so when I change the extension to .php or .asp, it adds those instead of .html. I tried setting HTML_FILE_EXTENSION to an empty string, but it defaults to .html in that case.

Would it somehow be possible to set the file extension for externally linked documentation separately, with a possibility of having no extension? I can work around this issue by writing a script that post-processes the generated html pages and removes the .html file extensions from the MSDN links, but it would be much nicer for it to work natively.

Screenshots Link in generated Doxygen documentation:

Results of clicking on the link:

Same link, with extension removed:

To Reproduce Here's a simple testcase with a single function which contains a link to the ScriptShape() function above: msdn_test.zip

Expected behavior Having an option to specify the default file extension for a tagfile, perhaps as an XML tag within the file, or as an option in the Doxyfile, with an empty file extension being allowed.

Version Doxygen 1.9.8 on Debian Stable (Trixie) 13.1

[albert-github]

In the past (1.8.16 and before) when the anchorfile in the tag file had an extension the extension was stripped and replaced by the currently used extension. This lead to problems when the currently used extension was different from the extension used for the files mentioned in the tag file. When I remember correctly in the far past even tag files were written so that no extension at all was written to the anchorfile in the tag file. For compatibility the current extension is still added, though this is counter productive in this case ("nice" of Microsoft to use this type of links ...).

I think that an extension to the tag file is necessary that signals whether or not the anchorfile should be extended or not by means of a tag attribute. I'm not sure whether this attribute should be added with the tagfile tag, or with the individual compound tags or with the individual anchorfile tags. (the default should, of course, be so that the extension is added). Another possibility would be that when the anchorfile ends with a . this . is stripped and no extension is added (in addHtmlExtensionIfMissing) @doxygen what is your opinion?

@daliborfox Important to know is here:

• is the tag file generated by you by hand or is it generated by an external party (where did you retrieve the file from?)? When it is an "external" file the "strip" possibility is not feasible. ((of course the file in the example that you gave is tailored by you specifically for the example)

I don't think the suggested solution:

Having an option to specify the default file extension for a tagfile, perhaps as an XML tag within the file, or as an option in the Doxyfile, with an empty file extension being allowed.

is a good solution as it is not really flexible and doesn't take old tag files without extension into consideration in case of mixing files.

[daliborfox]

Thanks for the quick reply!

I agree that the information should most likely be embedded in the tag file, and I agree with the concerns about inflexibility in case it were added to the Doxyfile.

As for the example tag file, I wrote it by hand after comparing it with some generated data. I only use a dozen or so functions and data types that I want to link to, so it shouldn't be much of a hassle to compose the file by hand. If someone were to write a tag file generator for this particular documentation site (MSDN), I'm sure they'll find the feature useful, but I wasn't able to find such a generator or such a pre-generated tag file with a web search.