All Guidelines Pages should have dropdown menu in footer to go to other versions in the Vault.

[jamescummings]

In thinking about the TEI Guidelines web pages footer for https://github.com/TEIC/Stylesheets/issues/125 it occurs to me that all Guidelines web pages should have a dropdown menu in the footer allowing a user to jump to a previous version of that page in any of the previous versions. (I would just make this an addition taken from a list of releases rather than testing that this element in particular existed in that previous version.) i.e. a dropdown might list 3.3.0, 3.2.0, 3.1.0, 3.0.0 and if an element was introduced in 3.2.0 then anything I select before that just results in a 404. (That would be fine, it shows quickly what release the element was introduced in.)

[raffazizzi]

F2F subgroup likes this idea a lot. We discussed a couple strategies for implementation, which is not as straight forward as one might think.

• Create a persistent structured file that maps past versions and file names of TEI Specs and Guidelines
• ~~New build will add a new entry to this file using the file on master branch (or Vault?) as the source in order to avoid pollution from dev version numbers.~~ We need a way to update the file with only release numbers, while making available dev version for testing (think of changelog script)
• Add a dropdown menu in the build that uses this structured file to figure out what to show for each spec or guidelines page.

[jamescummings]

@jamescummings assigned to look at this when he gets enough round tuits. Low priority. Another option is as an XSLT hackathon or stylesheets group activity.

[jamescummings]

If we do create this persistent list of versions it might help @raffazizzi in being able to automatically produce a list of versions of the TEI to base your TEI P5 ODD starting point in https://github.com/TEIC/romajs

[martindholmes]

I'm going to remove myself from this ticket for the moment because I'm not sure what's required; if it depends on the maintenance of a canonical list of versions which RomaJS can use, then that would seem to be the first thing to do; but there's also the obvious problem that some pages will not have equivalent versions in other released of the Guidelines, and I don't know how this could be known or deduced without a lot of processing.

[ebeshero]

I'm adding @hcayless and @joeytakeda to this ticket as we're working on Guidelines HTML for integration in the new website, and might try working this in to a new footer...

[joeytakeda]

I've had a go at this ticket to test out some options. In the TEI repository in branch https://github.com/TEIC/TEI/tree/Stylesheets_iss_321, I've written an XSLT that:

1. Produces a list of versions via the ReleaseNotes/READMEs in the TEI repository (that would at least give us the canonical list in P5, I'd hope)
2. Uses that list of versions to then retrieve the P5 subset where we can (it looks like only versions before 1.2.0 either did not include the P5 subset or the P5 subset wasn't a thing yet)
3. Processes each P5 subset to list the idents defined for that version (as a map()) [version-to-ident.json]
4. Then inverts that map to list each ident and the versions in which they are defined [ident-to-version.json]

I'm not sure if this is completely the right approach (perhaps there are better ways to retrieve this information), but wanted to propose this as a start for thinking about this again. I'm also not sure if the idea would be to run this, say, per release (and then just use that information when building the pages) or with every GLs build (which would be painful, given how long it takes to retrieve from the vault).

version-to-ident.json ident-to-version.json

[peterstadler]

Just my 2c: That sounds like a very reasonable approach and to speed things up one could execute that script (e.g. in a Github action or Jenkins job) with an update switch to only (re)build the information for the current version, not the whole vault. Another comment: I would refrain from adding those files (version-to-ident.json and ident-to-version.json) to the repo and rather add them to the release artifacts. If the mappings were created before the HTML pages in the GL build process one could even write those mappings directly to the HTML pages and avoid AJAX/Javascript completely.

[jamescummings]

If it is possible to have it in the page footer without JS that reduces maintenance issues. As long as there is an artifact created which other systems (like Roma) could use, that sounds good.

[joeytakeda]

Returning to this (see https://github.com/TEIC/TEI/commit/a6d35ff8747bcdc68ce51eb3faff00af95297756): The processing of the JSON is quite simple, but the challenging part is figuring out where it should go, how it should work, and what it should look like. If we do want this in the footer, I can think of a few options:

1. I was initially thinking that it could be a dropdown menu with a button, but that would require (a teeny bit of) JS to make the select menu jump to the appropriate version.
2. This could just be a list of links (maybe hidden in a details or something) -- that's not as elegant, but it work without any additional JS
3. We could do a hybrid approach: create the details with the list of links, and then, on page load, convert the details into a <select> with options and a button.

In all cases, if we want this in the footer, then we should decide where it should go in the footer (and then figuring out where in the Stylesheets or in guidelines.xsl.model this should go).

In the above commit, I've implemented a quick version of option 2 via guidelines.xsl.model (screenshots below) -- however, it did require making some local changes to the Stylesheets (namely, adding a hook to inject content between the two parts of the footer). We could decide to just do this in the Stylesheets, but that would depend on having the produced release maps.

Screenshots

Closed (default)

Open

[jamescummings]

I somehow missed @joeytakeda's comment above and think that works well as a solution. (Though one could argue about where the expanding [Previous Versions] should be. In my head it was in the footer proper, but I don't really feel strongly about it.) I like the idea of it working without JS turned on (for legacy devices).

Of course, there is an issue where if I navigate to version 4.4.0 of this, the same list of versions won't be there... but I think control-Clicking to maintain the current version and any version before we add it is reasonable. (Make the links open in a new tab by default?)

[martindholmes]

If the dropdown were created from a centralized listing at runtime, all future versions would include their successors. But we couldn't make this work for old versions without editing all their pages, which wouldn't be right, really.

[jamescummings]

Yes, agree @martindholmes we can't change previous versions. (And only should of something like their overall page infrastructure fails.)

[martindholmes]

I've created a proof-of-concept here:

https://hcmc.uvic.ca/people/martin/vault-poc/index.html

It retrieves the Vault page from the TEI site and constructs the selector on the fly by parsing it; then it lets you select a different version and would then navigate there automatically (in the proof-of-concept it just pops up an alert to tell you where it would go).

This should work both on Jenkins and on the TEI site, I think. It doesn't need any JSON; just put the JS into the page. It doesn't solve the problem of previous-page-doesn't-exist, of course.

[martindholmes]

I don't believe we can do this without JS, because wherever the list of releases is retrieved from, either the Vault page itself or some JSON that replicates the Vault page listing, it will have to be retrieved on the fly to populate the selector; if it's hard-coded into each release, then it won't be possible to move forward from an old release to a new one.

So, since JS is required, and since it can be done purely with JS (no need to generate JSON as part of the build, because we have the Vault page already), we might as well do it as pure JS.

[joeytakeda]

Per Krakow F2F: We are going to take up the approach of creating JSON files (as above) with a new dropdown menu at the footer of the page as proposed. We like the idea of lists (with a new list for each major version). This should also be available on Guidelines pages.

In terms of processing, the JSON documents listing all available versions should be created at build time as part of a release artifact. However, it should not be re-created for each new version, but should use a previous version (once that is available).