In the “old” ROOT documentation, internal web links to class members were preserved across releases.
So, (almost always) any link given to some method was valid even years after the post was written.
TGraph::Integral from ROOT 5.34
TGraph::Integral from ROOT 5.30
Unfortunately, the “new” way of the documentation generator creates new distinct links (almost?) each time it is executed.
As a result, links in forum posts become quickly invalid.
TGraph::Integral from ROOT master as of 2018.05.23
TGraph::Integral from ROOT master as of 2017.05.05
Please, fix this problem.
Posts in this forum are very often “reused” (and read by people even years after they were created) and the links given inside should be kept “valid”.
Part of the problem here is that the links point to the master documentation and the links there get “randomly” assigned by doxygen every time the documentation is compiled. If instead links to particular versions were posted then the links would hopefully not be regenerated as that version has been finalized and released. Somehow the master version needs to be harder to find and instead the latest recommended version should be the go to for documentation, this also avoids issues where new features are added to the master documentation which users expect to be in the recommended release.
Note that in the “old” ROOT 5 documentation, all links were preserved in the ROOT 5 master, too (the only change in links was “/html/” for the master versus “/html534/” for 5.34 versus “/html530/” for 5.30).
We need this same approach now.
Olivier strongly encourages people to give links (in posts) to the current master, but this quickly creates broken posts.
So, we need a way to convince doxygen to generate “stable” / “predictable” links (instead of “random” strings).
Seems to me only the links to the methods are not preserved, Right ? For instance the link to the TGraph class is always
root.cern/doc/master/classTGraph.html. I agree with you that it is really annoying to have the links to the methods changing. I will check if some solution exists .
We also regenerate (every night) older versions of the documentation, for instance to fix mistakes or typos. So even the “non master” version are changing.
I investigated a bit more and found some information here and there. According to what I saw, the naming of the “funstions’ URL” is done according to the functions’ prototypes, Therefore if the function signature does not change it should be the same among various documentation (re)generation. And indeed it seems to be the case. I just take here as example a function I know for sure it has not changed between 6.10 and the current master:
TGaxis::ChangeLabel . Here are the URL for 6.10 and master:
As you can see they are exactly the same.
And even if I generate a short version of the doc locally on my machine I get the same URL:
Ah … yes this can be … I will ask on the doxygen forum.
Maybe you could ask them if instead of these random “#a8ef5...” strings we could again get “#TGraph:Integral” or something like this.
Done… waiting the answer.
It does not seems to be that simple. I took an other example of a very old method which for sure has not changed.
THistPainter::PaintArrows . I looked at the oldest version of the reference guide we have generated with doxygen: 6.06 … versus the master version. I get:
… the same URL …
the doxygen versions are 1.8.9 and 1.8.13 …
So may be there is some other hidden rules triggering the name change … I leave my question on the doxygen forum. They may tell me if there is something hidden we have not seen.
Looking at the links in your last post, I noticed that you used “/root/html606/” while I used “/doc/v606/”.
It seems that, for “TGraph::Integral”, they produce different links starting with ROOT 6.08:
Note: starting from ROOT 6.10, “/doc/v610/” exists and “/root/html610/” does NOT.
Just an idea … can one somehow convince doxygen to emulate c++ compiler’s name mangling (“man c++filt”)?
This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.