asfimport
commented
6 years ago Chris M. Hostetter (@hossman) (migrated from JIRA)
Rough (untested) sketch of how this might work...
- Generated HTML documents can be tweaked to start including something like
<!--#include virtual="../../../latest-warning.html" -->in all pages – where the relative path../../../is based on how deep the generated HTML doc is in it's "set" of docs (ie: relative to the 'root' of the javadocs for this version, or the 'root' of this version of the ref-guide)- the generated docs can/should include an empty
latest-warning.htmlfile at that path, so external users who host their own copy don't get mod_include errors for a missing file
- the generated docs can/should include an empty
- the .htaccess file(s) used on lucene.apache.org can use mod_rewrite rules to route any request for
latest-warning.htmlto a new CGI, preserving the (resolved) path from the mod_include request as a "request param" for the CGI to use - the CGI can look at the version# in the path and compare it to the "latest" version (which we can start setting in an .htaccess SetEnv variable), outputing HTML as needed if they don't match
- the generate HTML can use the original (resolved) path from the request for
latest-warning.htmlto know where to link people to.
- the generate HTML can use the original (resolved) path from the request for
- once this is setup and working, it could be backported as far back as we want to go, and the hosted javadocs/ref-guides could be regenerated & re-published.
So for example:
- https://lucene.apache.org/core/5_2_0/queries/org/apache/lucene/queries/TermsQuery.html
<!--#include virtual="../../../../../latest-warning.html" -->
- .htaccess rewrites https://lucene.apache.org/core/5_2_0/latest-warning.html to something like https://lucene.apache.org/latest-warning.cgi?path=core/5_2_0/
- latest-warning.cgi extracts "5_2_0" from
$pathand compares it to some env variable (currently) set to "6_6_0" and decides to output a warning- in that generated warning HTML, the URL to link to is built by replacing "5_2_0" with "6_6_0" – ie: https://lucene.apache.org/core/6_6_0/
- if the
$pathalready matches the latest version, then the CGI generates blank output
Spinning this idea out of some comments/concerns in SOLR-10595...
It would be nice if all the various "version specific" pages we have (ie: javadocs, tutorials, solr ref-guide) could include some standard snippet of text drawing users attention to the fact that they are looking at docs for an "older" version of lucene/solr – ideally with a link to the current version. ala...
The details of how this could work aren't clear cut – particularly since for any arbitrary URL the "latest" version of those docs may not contain the exact same path/file (ie: deprecated/moved classes in future releases, etc...) but ideally it would be some very generic mod_include / javascript directive that could be included in all generated HTML, that would only "activate" when the page was loaded from lucene.apache.org and would only inject the "warning" into the page based on the version number in the URL compared to some server side configured version number (ex: the way we already have the "latest" version# hardcoded in our .htaccess file for redirects)
Migrated from LUCENE-7924 by Chris M. Hostetter (@hossman) Linked issues: