Point in-app help links to /development/ docs unconditionally#21418
Point in-app help links to /development/ docs unconditionally#21418andriiryzhkov wants to merge 1 commit into
Conversation
| // <lang> = en / fr ... (default = en) | ||
|
|
||
| // in case of a standard release, append the dt version to the url | ||
| if(dt_is_dev_version()) |
There was a problem hiding this comment.
As we may fix that at some point I would advise to have:
if(TRUE && dt_is_dev_version())
And add a comment:
TODO: revert when documentation redirection is back....
There was a problem hiding this comment.
But what is the point of redirection when we not planning per version documentation?
There was a problem hiding this comment.
Not sure to understand why you say that we are not planning per version documentation. This was the case and we are trying again to recover this. It will take time but hopefully this will be back at some point in the future. But maybe I miss some information about this?
There was a problem hiding this comment.
Oh, I came to this conclusion from
As of darktable 5.2 we no longer maintain separate versions of the user manual for each release of darktable, since we don’t have the resources to support this.
If there is a goal to return to versioned dtdocs, that's awesome. And in this case this fix does not make sense, and all we need now is to fix redirects on the site.
There was a problem hiding this comment.
Meanwhile, updated per your comment to keep it as temporary solution.
There was a problem hiding this comment.
I see, I was not aware of this end of versioning support :( So you may be right and so the code should be adjusted accordingly. Let me first discuss with the documentation team to take a final decision.
There was a problem hiding this comment.
@andriiryzhkov : I have just discussed this with the documentation team and we will stop the versioned release after all. So let's go back to your first proposal and move forward.
I'm sorry for the confusion.
andriiryzhkov
force-pushed
the
usernamual_url_fix
branch
from
57d901e to
0f7a25e
Compare
The problem with unconditionally pointing help links in the app to "/development/" documentation is that after a certain time, the current state of the documentation will describe all those new changes that did not yet exist at the time of the release of previous versions. This can be confusing for users who are still using somewhat outdated versions of darktable. Unfortunately, there are some users who do, as not everyone likes new and shiny versions when the version they are already used to is completely fine with them. |
|
@victoryforce : I understand your point. But versioned doc is too much work for a little gain and a small team so we'll have to live this this for now. Also note that at the moment we have no way to access the server to add nginx redirection anyway. |
To quote the wording from the resources page: "we no longer maintain separate versions of the user manual for each release of darktable". This was written at a time when the documentation was in a much worse state and had been seriously behind for several versions. In such a situation, there is no point in continuing to branch heavily incomplete documentation for each release of darktable. We would end up with several equally incomplete documentations instead of one and that's it. Now the situation is different, as @Phemisters writes in darktable-org/dtdocs#909 (comment):
Now supporting multiple versions of the user manual is just a matter of branching and publishing. The versioned documentations are already complete and do not need any further work.
I suggest that we once again ask those who control the server configuration to resolve this issue for now and we'll continue to think about how to resolve it better. Perhaps the easiest way would be to move to hosting the documentation on github pages. |
This is being done (read I have done so), but for 5.6.1 we are not even sure that we will be able to get an answer. So for now it is better to remove the versioned support than having a 404 page. |
|
Oh... I see that the issue has been reopened with a new proposal. Still we need at least to have a new nginx redirection. |
I thought so too, but I just realized that it seems like it's not necessary. We only needed the redirect because the documentation wasn't deployed to the "/usermanual/version.number" subdirectory. So we needed to add a redirect to the nginx configuration to forward such requests to /usermanual/development. If we now deploy the documentation release for 5.6 to docs.darktable.org, the files will be in the right place and the redirect won't be needed. |
Indeed, probably right. I don't know how the deployment and the server is configured. To be tested I would say. |
|
I have converted to Draft for now. We will discuss the different options just before the 5.6.1 release. The goal is to have a functional (even if not perfect) online-help system for 5.6.1. |
3 participants
Long-term half of #21417. This PR does not fix the 5.6 release – users on already-shipped 5.6 binaries will keep getting 404s until a server-side redirect for
/usermanual/5.6/*is added separately. This change only ensures the bug stops recurring from 5.8 onward.Why
dtdocs stopped publishing per-release snapshots after 5.2, so the URLs we've been constructing for stable builds – e.g.
/usermanual/5.6/en/...– just 404. The server has manual per-version redirects for 5.0 / 5.2 / 5.4, but 5.6 was missed when it shipped, and the same will recur with every future release as long as we keep encoding the build version in the URL.What it does
dt_get_manual_base_url()now always emits/usermanual/development/, the only modern path dtdocs actually publishes. Dev builds were already emitting that; stable builds now do the same. No per-version redirect rule will be needed for 5.8 or anything after.