HTML display of spec files: add an xml view link to the footer, pointing at the ODD source

[peterstadler]

There is an "XML view link" on every page served from the CMS, but not for the Guidelines spec pages. I propose to add this feature which would make the ODD definition of the spec files easily accessible on the web.

[lb42]

No particular objection to this, but don't forget that the ODD specs contain an awful lot of stuff most users don't want to see (e.g. descs and examples in other languages, rude comments by editors, etc.)

[peterstadler]

True, but there's so much beauty in it, as well :)

[ebeshero]

The ticket is only asking for the XML view, but would we want to duplicate the whole footer on most pages of the TEI site, e.g. http://www.tei-c.org/About/Logos/ ? Can we clarify whether we want stylistic consistency between the Guidelines pages and the website, or whether we want only the XML specs link for the distinct purposes of improving available documentation on the specs?

[ebeshero]

Okay...I'm pretty sure we want this just for improving documentation on the specs, but figure we might want to clarify why this would be helpful for reference. I'm thinking it's specifically useful for writers of ODD customizations.

[ebeshero]

Am I right in thinking we'd need to edit https://github.com/TEIC/Stylesheets/blob/dev/common/common_tagdocs.xsl to implement? Seems like we'd need to define a param to help construct a link back to the source XML spec.

[hcayless]

The base problem here is that, while the CMS pages are dynamic transforms from their XML sources, and therefore know where those sources live, the spec pages are static HTML and don’t. We can establish a convention for the website that builds in a standard location for the source on tei-c.org, but that will only work there, so I think we’ll have to either make the site build slightly different from the standard build (and there might be some advantages to this), or maybe point to the source on GitHub instead. We might have enough information to do that, since we already grab the current commit hash.

[jamescummings]

1. I think pointing to the source on github is the right solution. That way people can comment, submit issues, etc. directly relating to the source.
2. This can only be about the Guidelines section of the website, not something like /About/Logos because remember we're doing away with an XML-based website by moving to WordPress. i.e. the About/Logos page will be as at http://www-dev.tei-c.org/about/logos/ so there won't be an XML view.

Is it not in the stylesheets repo at all but in the guidelines.xsl.model https://github.com/TEIC/TEI/blob/dev/P5/Utilities/guidelines.xsl.model that we should be making the change?

[jamescummings]

Thinking about what @hcayless is saying there, does that mean we are expecting to point to the revision of that particular release for any spec page? (i.e. need the current commit hash) Or is it sufficient just to point to the current dev branch version of the spec file. The dev branch might have been modified since release but surely, if someone is going to complain about something, seeing the current state of it is better than seeing the version at release time, no? I'd much rather encourage ongoing engagement with the state of the TEI Guidelines as they are than information archaeology back to previous releases. I note that these also will end up in the vault and from there would be pointing to the 'current' dev branch on github rather than the dev branch as of the release for that historical page. I understand that is misrepresenting 'XML Source' somewhat, but I think it is a more helpful link in the long run. Are people looking at the XML Source because they want to see what the HTML page was generated from, or because they think the TEI Source as reflected in that page should change? If the latter it should always go to the current dev branch, if the former then the spec file for that particular commit.

[ebeshero]

@jamescummings Indeed, I'd been thinking we'd just link to the XML directly if it's not too impenetrable, or do some old-fashioned rendering of the XML spec in the browser (e.g., embedded XSLT transformation).

[jamescummings]

@ebeshero Sure. I don't think we should process the XML. browsers do that if you display it without a stylesheet. But really I think pointing to GitHub is a more sophisticated solution. Commenting, syntax highlighting order, etc.

[hcayless]

Stylesheets group suggests pointing into the current release in the Vault from the footer.

[sydb]

Using the tei: prefix, which should be defined in the source to P5 via a <prefixDef>, no?

[hcayless]

I'm unclear as to the utility of the prefix here, but maybe it will make sense when I look at it...

[joeytakeda]

+1 for this. I was this close to almost opening a (near) duplicate ticket in the TEI repo, but realized that this is in fact a Stylesheets thing :-)

Here's what I was going to say, had I posted it in the other ticket:

While the spec pages show the ODD content model, I think it would quite helpful for those page to include either the full specification (in an <egXML> akin to what's already there for the <content>) or, at the very least, a link to the source in GitHub (probably pinned to the latest revision). I often find myself going to the Source/Spec/$thing.xml page when I'm trying to modify an element in ODD, especially if there some reason where one needs to use @mode='replace' for an entire element.

Putting a link would work nicely when building the TEI website, but it wouldn't be all that useful for ODD users generally, which is one of the reasons why it makes sense for this to be a Stylesheets issue: wanting to see the source specification of an element isn't a unique Guidelines thing, since anyone creating an ODD may very well want to see what they've done at a glance. A block with the spec in it would be no less ugly, imo, than the schematron blocks or the content models on the page, and would be really useful for those actively developing a schema in ODD (especially for new elements or schemas that aren't based on the TEI at all)

So, thinking aloud, what about something like:

• If the specification is derived from the TEI schema, the documentation for that spec points to its original TEI source (maybe in GitHub, but that'd be harder since Stylesheets would have to work out how to find the page for the P5 version from which the thing is sourced, which is slightly tricky due to inconsistent names for tags in the releases [sometimes P5_Release, sometimes P5_release] )
• If the specification is declared in the producing ODD, the documentation would contain an XML block that shows how it was configured in the customizing ODD—i.e. specifications added, changed, and replaced are shown as they appear in the ODD that produced that customization