Hi David, On Sat, Nov 13, 2021 at 2:41 PM David Jencks <david.a.jen...@gmail.com> wrote: > >> I think we can use it sort of in reverse to publish a site manifest for > >> each obsolete component version and use it to add to the component > >> explorer. It will take some thinking and a bit of work but should not be > >> too hard. > > > > Hmm I need to wrap my head around this, sounds like we would build the > > version against the site manifest and never build it again? How's that > > different from building it, keeping the HTML files around and then > > removing that version from the playbook? > > With this plan we’d keep the HTML files around: the difference is that Antora > would know about the old pages, so links to them would work and the versions > would show up in the component explorer.
Oh, that's really neat I like that > > > > We use hash of the CSS files for cache busting, so we'd need to keep > > the older version of CSS files as well. Not really an issue, just > > something we need to accomodate for. > > I don’t understand how this works. I would expect that everything Antora > related would use the same UI and if we changed the html generation enough > (maybe Antora 4 or if we added a custom template) we’d do a one-time > regeneration of all the old docs. In the Gulp build of the UI we use gulp-rev so file gulp-rev so that CSS and JavaScript files have a hash in them, e.g. site.css becomes site-9775b2354a.css, this in turn allows us to set caching (for 1 year IIRC), but still push out new versions and get the browsers to update and use the latest version as the hash part changes. This gives us better performance and saves some bandwidth for ASF and end users. When we publish we delete everything and copy over the latest version, so if a CSS file is updated and it now has a different filename, the old CSS file will be removed and a new one published. So if we're to keep old versions of HTML files there is a good chance that they'll point to an older CSS file, so if we remove it we'll break the formatting. We'll just need to take that into consideration if we're going to keep old versions around to keep the old resources that they use around as well. > > What would happen when an older version of the docs points to a page > > in the user manual that we removed/renamed? > > Well, we shouldn’t be doing that now without leaving behind a redirect, > hopefully soon via a page-aliases attribute :-) Yeah, or we put a placeholder page if there is no new content to point to, that explains that the content was removed as it's no longer relevant. > > > >> I’d suggest that we do something to make it plain on each such page that > >> the page is obsolete, and in the component explorer that the version is > >> obsolete. This might involve a “final build” of the component version > >> after a “retirement update”. Maybe we could have an “obsolete” watermark > >> in the layout and set the “obsolete” layout in the antora.yml component > >> descriptor. > > > > Yeah, I've seen banners displayed on older documentation pages > > prompting users to use the latest documentation/version, that would be > > helpful. > > > > I was also thinking about having a documentation ZIP distributed with > > the release downloads. Probably using a different Antora UI, perhaps a > > bit lighter and without the same menus as the published website. > > That could be interesting too. The site-manifest idea could be used to > create working links to the actual user manual. How would you deal with > links to the relevant obsolete versions of other subprojects? I was thinking either have them point to the website, with some magic needed here to publish with absolute links to other subprojects; or expect that the subproject's documentation is extracted in the same directory so the links are still valid. I feel like we need to decide if we're going to take on all this work, i.e. do we care about making older versions of the documentation available? Seems like quite a lot of work, so if we're not certain that there is a need for this, perhaps we should not be doing it... zoran -- Zoran Regvart
