SFML community forums
General => SFML website => Topic started by: Hapax on January 16, 2016, 12:57:34 am
-
At the moment, the website has the documentation for each different version that are contained within their own folder. As new versions become released, any linking to the documentation automatically becomes linked to what is then and old version.
Would it be possible to include a way to link to specific articles in the documentation while being able to specify a more generic version?
For example,
http://www.sfml-dev.org/documentation/2.3.2/classsf_1_1RenderWindow.php
links to the (currently) latest version of the documentation for sf::RenderWindow.
As soon as 2.3.3 - or, indeed, 2.4 - is released, this link would be out of date.
Since patch updates - and also minor updates - shouldn't be changing the documentation in a "breaking" way, it would be convenient to be able to link to these articles using a form of "wild-card" version.
A suggestion would be able to specify wild card at minor or patch level like so:
http://www.sfml-dev.org/documentation/2.3.x/classsf_1_1RenderWindow.php
which would link to sf::RenderWindow in the latest version of 2.3
http://www.sfml-dev.org/documentation/2.x/classsf_1_1RenderWindow.php
which would link to sf::RenderWindow in the latest version of SFML 2.
The website already has the feature to some extent for its documentation's "main page" where, if you leave off the version, it'll choose the latest. Adding the suggested ability above to the articles directly would help increase permanence of documentation links.
I found that, as I was linking to the documentation a lot, I have started to drop using the patch level version from the links thus:
http://www.sfml-dev.org/documentation/2.3/classsf_1_1RenderWindow.php
as replacing all links every time a new patch version is released just to make sure you're on the latest version feels like overkill and these are "pretty much" the same. Pretty much, as much as linking to the wrong patch version would be, anyway.
Suggestion summary:
documentation/2.3.2/article
2.3.2 article
documentation/2.3.x/article
latest 2.3 article (currently 2.3.2)
documentation/2.x/article
latest 2 article (currently 2.3.2)
-
I had the feeling it was discussed at some point but maybe I'm wrong.. Anyway, I guess this would be nice but let's face it: who would implement it? A few month ago we were talking about a showcase page but nothing happened... So, were there a consensus on this, does anyone want to implement such system? (To be honest I've no idea how complex this is.)
-
Shouldn't be too hard to setup with a small script and URL rewrites. I can have a look, but don't know yet when I'll have some time for that.
-
Should be fairly easy with RedirectMatch in the .htaccess file.
Something else that was already discussed too are "banners" at the top that appear for outdated versions and direct the user to the latest version. Like Boost (http://www.boost.org/doc/libs/1_59_0/libs/phoenix/doc/html/index.html) does it, for example.
-
Shouldn't be too hard to setup with a small script and URL rewrites.
No script needed.
Should be fairly easy with RedirectMatch in the .htaccess file.
Except we don't use Apache.
It can be done in the nginx config, but only Tank can change that.
Personally I think it can still lead to issues where people discuss a specific kind of behavior that might have slightly changed, but the link simply points to the latest documentation and thus the information what SFML version that is talked about, gets kind of lost.
-
As far as I can see there are more problems with people using old documentations and not the other way around.
This might be mostly because of the static linking and dependency changes.
-
Adding this feature won't guarantee that people suddenly use the generic link as well. Some do, many might be too lazy to do so.
-
I would suggest to show a "warning" that the current shown version is not the newest one.
Not sure if people would read it though :-\
-
That's why I mentioned the hint, which appears at the top of the page and can't be overlooked. There will always be links to outdated documentation, which is why I consider this a more important improvement than a 2.3.x or 2.x redirect.
Because of the nature of redirects, people will never actually see that URL in their address bar. Furthermore, they won't even notice when they click on such a link, unless the URL appears in plain text and people pay close attention (unlikely at long convoluted link names). Therefore, that feature would be limited to a small circle of insiders who are aware of its existence.
-
I think both are important - the ability to link to latest versions and information showing that the current documentation is not the latest.
The "bar" would, of course, only show when people linked directly to a specific version that is out of date so this bar could possibly also inform people of the ability to "latest link".
Implementation-wise, this should even be possible using only PHP but it might not be the best solution.
-
I have noticed that this also affects the official tutorials as the tutorial versions only progress per minor version so don't link to the latest patch version.
e.g.
http://www.sfml-dev.org/tutorials/2.3/graphics-draw.php
All links to documentation are 2.3, not 2.3.2 (the current latest) as it should be, especially as the tutorials are up-to-date to match the latest patch.
Wouldn't it be "nice" to have the 2.3 tutorials to link to 2.3.x versions of the documentation, for simplicity in maintenance of those tutorials as well as them linking to the correct version.
-
I just updated the website to include this fabulous button:
(http://i.imgur.com/XYMvjOY.png)
-
That's great and just exactly what was needed on the actual out-of-date pages.
Still, as mentioned above, the website looks kind of unmaintained when you click on a link to documentation from a tutorial and it tells you it's out-of-date.
-
Now we need the second part: a "latest" alias to improve referenced links on search engines.
-
I still see an issue with the alias, i.e. where people talk about a specific version and link the latest doc. After a year when the discussion gets picked up, it's not obvious anymore which version was referenced.
Additionally if something gets removed all links still pointing to it break.
-
Thank you for the update eXpl0it3r. Could you consider adding this feature to the tutorials pages too?
Today I first learned about SFML from this page http://www.cplusplus.com/forum/windows/57237/ (http://www.cplusplus.com/forum/windows/57237/), but it made me stuck on version 1.6 for an hour ;D (BTW, people on this page also love SFML)