tag file entry without filename

ChristianTackeGSI commented 2 years ago

Describe the bug

external tag files with entries that do not have a <filename> element give links to non-existant files.

Expected behavior

If there is no filename in the tag file, maybe set the generated entry to artificial = true, so that it is visible in diagrams/etc, but not clickable? Like the BUILTIN_STL_SUPPORT things?

To Reproduce

This is a very minimal example. Not being really useful, but shows the problem.

foo.h:

#include <TObject.h>

class MyClass : TObject {};

ext.tag:

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<tagfile>
  <compound kind="class">
    <name>TObject</name>
  </compound>
</tagfile>

Doxyfile:

TAGFILES = ext.tag

This draws an inheritance / collaboration diagram for MyClass with TObject in it. And TObject is clickable, but sends you to a non-existant page.

Version Debian-11, amd64, 1.9.1-1

albert-github commented 2 years ago

There are 2 forms of TAGFILES references:

TAGFILES = ext.tag=<reference to html documentation> Here an explicit position of the relevant HTML documentation to be linked to is given.
TAGFILES = ext.tag This requires that the relevant HTML documentation to be linked to is in a directory that is a direct sub-directory of the place where the ext.tag file can be found.

Personally I would always use the explicit version 1 for the references to the tag files

Some questions:

how is the ext.tag generated?
where can the documentation be found. In the resulting error message we see a reference to .../html/classTObject.html so it cannot find the relevant descriptions.

Small side note: the current doxygen version is 1.9.3 (most likely won't influence your problems).

As far as I can see the problem is usage.

ferdymercury commented 2 years ago

If I guess correctly, the external tag file refers to the one from ROOT, that can be downloaded from https://root.cern/reference/

It was generated using this Doxyfile: https://github.com/root-project/root/blob/master/documentation/doxygen/Doxyfile#L2311

albert-github commented 2 years ago

That might indeed be the case, but in the mentioned tag file I do see:

....
<compound kind="class">
    <name>TObject</name>
    <filename>classTObject.html</filename>
    <member kind="enumvalue">
      <name>kIsOnHeap</name>
      <anchorfile>classTObject.html</anchorfile>
      <anchor>a4dbe3207b9cea1c3467c08494babb646a86a2f10e2ccacd503e6f3211db434de9</anchor>
      <arglist></arglist>
    </member>
...

so with filename. so I guess @ChristianTackeGSI might have stripped the file or .... Still a reference to the HTML output directory (by downloading and unpacking the the relevant file from the mentioned reference page) or referencing https://root.cern/doc/v624/in the TAGFILES is necessary .

@ferdymercury Few remarks:

I would not place the MathJax directory in the same directory as where are all the html files are and also try to minimize it at bit by removing unnecessary files (In the past I did this once for the MathJax version and from the original 100Mb / 34K files it was just 12Mb and 657 files), though this was tailored for the specific application output).
did you look at MathJax version 3 to integrate it?
I would split the html directory with CREATE_SUBDIRS
the tag file file is hard to download maybe an idea to also provide it as compressed tar file (same accounts for the qch file).

ferdymercury commented 2 years ago

Thanks for the hints.

Concerning the Mathjax directory, I had already changed that in this rehaul (still in a draft status), putting it in a separate folder: https://github.com/root-project/root/pull/9966
Concerning v3, I will ping @couet
Good idea about create_subdirs, I will test it to see if it improves performance --> EDIT: No, actually this is problematic, as it would break all 'unofficial links' in our forum (root-forum.cern.ch) to the documentation website https://root.cern/doc/master.
Concerning compression, that seems a good idea, too, pinging also @couet

ChristianTackeGSI commented 2 years ago

Hi!

Yes, this is ROOT. And yes, I stripped it down a lot. I don't want the full blown ROOT documentation. (In reality, I wrote it from scratch to include only the things that I want in there.) What I would like is something ike what BUILTIN_STL_SUPPORT is giving me for say std::unique_ptr<Foo> ref; in a class. It gives some nice intermediate box with ref and ptr on the arrows and the std::unique_ptr in it. But that box is not clickable. There is no extra documentation for it. That's basically what I want to get.

I had hoped that stripping the <filename> element will tell doxygen "there's no linkable documentation".

albert-github commented 2 years ago

Did you try to run without the tag file as in that case I see the box (using HAVE_DOT is NO and also with YES) but without a link in it at least in the inheritance diagram.

Why would you use the tag file in your use case?

Did I overlook something?

ChristianTackeGSI commented 2 years ago

Okay, let's make the example a bit more realistic:

ext.tag:

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<tagfile>
  <compound kind="class">
    <name>TObject</name>
  </compound>
  <compound kind="class">
    <name>TNamed</name>
    <base>TObject</base>
  </compound>
</tagfile>

foo.h:

#include <TNamed.h>

class MyClass : TNamed {};

(which is actually one of my first uses. I always forget, wether TNamed is standalone or a child of TObject. But I don't need the full blown docs for it.)

albert-github commented 2 years ago

The more realistic example gives a bit a better insight in what you want, interesting idea.

albert-github commented 2 years ago

I've just pushed a proposed patch, pull request #9247

ChristianTackeGSI commented 2 years ago

Wow, very nice!

I have to admit, that I wont get to test this anytime soon.

From reading the diff this looks more complex than I had expected / hoped. So hopefully this doesn't make things too complex? That mentioned I see a lot of [external]. On the one side, I think, it's a good thing to mark those properly. On the other hand I think, it might bloat (especially diagrams?) some places?

BTW: In the long run, it would be interesting to replace BUILTIN_STL_SUPPORT by shipping a (hand crafted) simplyfied-stl.tag file?

albert-github commented 2 years ago

I have to admit, that I wont get to test this anytime soon.

Pity as you requested it so you probably would have a start "ROOT.tag" without the <filename> tags or could easily create from the default "ROOT.tag" a version without the <filename> (e.g. by means of grep -v "<filename>" Root.tag and run it with your code base to see the initial results.

From reading the diff this looks more complex than I had expected / hoped. So hopefully this doesn't make things too complex? That mentioned I see a lot of [external]. On the one side, I think, it's a good thing to mark those properly. On the other hand I think, it might bloat (especially diagrams?) some places?

It was a bit of work to get the, for me, right idea. The number of extra external is not that much, it just is added at the places where it was before in the output but was omitted now due to the change. I don't think it will bloat the output (I didn't see any bloating), but this we can only be certain with the user's experience.

BTW: In the long run, it would be interesting to replace BUILTIN_STL_SUPPORT by shipping a (hand crafted) simplyfied-stl.tag file?

Interesting idea. I know that there is an older tag file at https://en.cppreference.com/w/File:cppreference-doxygen-web.tag.xml

ferdymercury commented 2 years ago

Interesting idea. I know that there is an older tag file at https://en.cppreference.com/w/File:cppreference-doxygen-web.tag.xml

There a bit newer ones (at least the file date is 2019, not sure if much is changed) at https://en.cppreference.com/w/Cppreference:Archives

albert-github commented 2 years ago

@ferdymercury Thanks actually that was the version I was looking for but couldn't, quickly, find it. The new version looks quite a bit bigger, so probably more complete.

ChristianTackeGSI commented 2 years ago

I have to admit, that I wont get to test this anytime soon.

Pity as you requested it so you probably would have a start "ROOT.tag" without the <filename> tags or could easily create from the default "ROOT.tag" a version without the <filename> (e.g. by means of grep -v "<filename>" Root.tag and run it with your code base to see the initial results.

Yes! I would like to try this!

Just I am currently busy with lots of other things. I'll try setting up doxygen source with the patch in about two or three weeks.

If you need to merge the PR and/or close this issue anytime soon, don't get obstructed by me!

doxygen / doxygen

tag file entry without filename #9185