Added Tagfile generation and search

[PapyChacal]

Working on Ubuntu 16.04, I don't know if this can directly work on macOS/Windows.

[LaurentGomila]

Thanks for your contribution.

So now the end user has a new CMake variable, SFML_DOC_DIR, that points to this new file, SFML.tag. And then what? Can you explain what this stuff does?

[MarioLiebisch]

Never used it before, but it's obviously a feature by DoxyGen to include library documentation without reparsing the source.

[PapyChacal]

Yes, using this tagfile, a project documentation generated by Doxygen can link to the sfml documentation. I think it could help to easily make user-friendly documentations for those projects, which is always good for new users ! And it is a really small change anyway

[mantognini]

I think this is a nice little addition at no real cost. Just one little change.

(forum thread)

[mantognini]

I wouldn't put this file in the html sub-directory as it's unrelated to the HTML generated files. One could build the doc using other output format instead. Of course, the other change should be adapted.

[PapyChacal]

Well, I think the tagfile mechanism is only used to link against HTML documentations, but I might have misunderstood that ? Doxygen's page :
https://www.stack.nl/~dimitri/doxygen/manual/external.html

If that is the case I personnaly think it's natural to have it in the HTML sub-dir.

[eXpl0it3r]

The example on the site you linked, doesn't add it inside the html directory. As such I wouldn't place it there either.

[PapyChacal]

Okay, I get it.
It can be installed in the doc directory (parent of html), would this make more sense ? This way it wouldn't be inside the html directory but is still installed in an already standard place.

[PapyChacal]

Oh, and as I am not used to work with pull requests, reviews and everything : should I commit the changes corresponding to this request or what ?

[eXpl0it3r]

It's your PR, so yes, you should provide the change. Additionally, if you could squash your commits, that would be great as well, otherwise I'll just do it when merging. 😉

[mantognini]

It can be installed in the doc directory (parent of html), would this make more sense ?

Yes. :)

[PapyChacal]

@LaurentGomila
With this new variable, one can use this mechanism to link his project's documentation against SFML doc, by adding a TAGFILE line to his Doxyfile.in :
TAGFILES = @SFML_DOC_DIR@/SFML.tag=@SFML_DOC_DIR@
(Doxygen need a path to the tagfile, and a path to the corresponding doc)

Then the generated documentation will link to this SFML generated documentation (To those given local files) : If a SFML type is mentionned in the other project, it will be a link to this type's SFML documentation page.

I just think this could make those projects easier to discover for future new clients ?
I don't know if there is an easy way to link to the online SFML documenation, but I think it would be great too, for those projects online documentaions.

[PapyChacal]

Okay now I made changes to generate (and find) the tagfile in the doc folder directly, but I don't understand why there are so many changes indicated on other files ? What did I do wrong ? :s

With those settings, it would need to be used this way in external projects :
TAGFILES = @SFML_DOC_DIR@/SFML.tag=@SFML_DOC_DIR@/html

[eXpl0it3r]

You merged master into your branch at one point. Would be better to rebase your branch onto the current master instead. 😉

[mantognini]

In this specific case, you want to run something like this:

git rebase upstream/master
git push --force-with-lease

[PapyChacal]

Done ! Is it okay now ?

[mantognini]

Looks good :)

[eXpl0it3r]

Merged in 341bc2a