How to manage & publish GEMINI pages

[PeterParslow]

GEMINI consists of (about) 15 web pages. Twelve are "normal" web pages; three are generated from common content, but are currently sent to AGI as HTML web pages. The "XML Element Order" page would also benefited from being generated from that common content - it has fallen behind.

The current issues may impact perhaps 12 of those 15 pages.

BlueStar, who host AGI's website, expect to be paid for each set of changes. This is an issue across the website that will be discussed at AGI Council. @archaeogeek to keep us informed.

Some or all the GEMINI pages could be published separately (e.g. on GitHub), styled (to some extent) like the AGI site, and linked from there. We would want the permanent links to remain, so there would be quite a lot of redirects.

As a separate question, we could use GitHub to generate the web pages, allowing us to maintain them "natively" within GitHub in Markdown.

[PeterParslow]

At meeting on https://github.com/agiorguk/gemini/wiki#2021-07-29 we agreed to move the "element" pages to GitHub, which I take to mean pages 1062, 1063 and 1250.

I have spent a merry few hours tracing all the links & updating the old "Readme" file that documented the old site at go live (2018). We seem to have added a lot more links (or I missed some back then).

Anyway, you can see the current picture (in words & image) at https://github.com/agiorguk/gemini/blob/main/resources/Readme.md

I reckon there are four pages that should have been deleted earlier; another two that are not really any use:

• 1047 Bibliography - why not just have the links to the targets?
• 1040 Conformity - always been a rather short list!

I would favour moving all the pages on to GitHub.

We have pending versions of 1037 & 1048 already, leaving seven "text" pages most of which could do with updates.

[archaeogeek]

Skeleton page for outlining the update process: https://github.com/agiorguk/gemini/blob/main/governance/website_update_process.md

[PeterParslow]

I've had some success just putting 'plain HTML' in a repository and using GitHub Pages: https://github.com/PeterParslow/GEMINI2-3

Like most Content Management Systems, the CSS approach taken on the AGI website is pretty opaque, so I haven't managed to reproduce the 'look & feel', but that aside, do have a look.

[archaeogeek]

For information, the gh-pages version is at https://peterparslow.github.io/GEMINI2-3/

[PeterParslow]

I've just added a sample with dynamic (dataset / service) content - one element (Title). There may be more elegant ways to do it!

Still can't get the CSS to work :(

[archaeogeek]

@PeterParslow do you have a simple css that you're trying to include? I'm certain you should be able to reference one. That might be simpler than trying to link to the ones actually used on the AGI website. I think as long as we hit the basic look and feel stuff it should be OK, particularly for now. I love the dynamic page though- it's great!

[PeterParslow]

The files that use the Gemini.css (e.g. 1-Title.html) work fine*

My offline experiments to reproduce the style of the "static pages" have so far failed. Sometimes I am having trouble picking out which bits of the current site's style are actually being used. Each page has a mix of several imported CSS files & a couple of inline CSS blocks that are generated per page, with seemingly identical content but using different class names. I've been trying to extract the useful subset to a common CSS that we can then import to all the pages. But I parked that a few days ago. Occasionally I also hit an odder problem, where the browser couldn't read the CSS file at all (some kind of misinterpretation of the character encoding).

*I'm not sure why you need to click twice on each "expander" to get it to expand, but that's a separate problem!

[PeterParslow]

I've fixed the 'click expander' before it can be activated bug. I've also switched to what I reckon is a neater way of doing dataset/service, as a URL parameter. Of course this would change all the incoming links (at least, those who want a 'service' view, I defaulted to 'dataset'). Initially, I envisage this being a set of redirects from the AGI site/domain, so less of a problem.

That would also give us a chance to migrate to nicer URLs: the AGI site has the old ones redirecting to GitHub, and as they would have to create a set of redirects, they could also create the newer URLs as redirects too.

I'm thinking of things like:

https://www.agi.org.uk/gemini/2.3/1-title.html?view=service

and https://www.agi.org.uk/gemini/2.3/xml-encoding-introduction (or similar)

[PeterParslow]

Something for later: https://openwork-nz.github.io/mdwg/defs/TableOfContents

That is, I think there are nice ideas in this New Zealand / Australia guidance, not that we should try to achieve that structure/output for GEMINI at this point!

[PeterParslow]

Looking down the ASCII Doc / Metanorma route:

• Metanorma does seem to support the ASCII Doc "include" directive (an extension defined by ASCIIDoctor). I can't see anything about it in the Metanorma authoring guide (https://www.metanorma.org/author/topics/document-format/), but this blog implies support: https://www.metanorma.org/blog/2020-12-08-asciidoc-include/

However, to use "include",

• we’d have to manage two files (datasets, services) with the common stuff in a whole lot of includes

• I can't imaging anyway to generate the Summary page

• I can't see how we can support our common case, where text in one cell in a table differs between dataset & service - so we would have to completely re-think our layout.

• I can't see any way to provide the expand/collapse functionality that we use to make the same page useful to those who want to see the XML & those who don't (or other sections).

• There might be a way to pass through CSS display block/none instructions, with a java script function to toggle them (the approach I've taken at https://github.com/PeterParslow/GEMINI2-3/blob/main/1-title.html). See https://www.metanorma.org/builder/topics/styling-output-html/

But to use CSS this way seems far more complex than just managing / editing native HTML!

[archaeogeek]

If asciidoc is going to make things more complicated then I don't see the point of going down that route or the metanorma approach. There are other options, such as sphinx (https://www.sphinx-doc.org/en/master/). Yes we'd need to use something like https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets to do show/hide but it's clearly possible.

FWIW I didn't get very far with the ruby issue I hit in metanorma, so would not be unhappy to change approaches at this stage :-)

[PeterParslow]

Hold that thought - I will dig a bit more into ASCII doc "semantic tags" and "custom inline styles" - although I don't know how those will pass through Metanorma.

I know Ronald Tse quite well; once I've formed a question, I'll ask him.

[archaeogeek]

I've also got a potential solution to the ruby bug I was seeing, so I'll see if I can make some progress with that as well

[PeterParslow]

@archaeogeek I've done a bit more looking on embedding 'active content' (restyled by parameter) into the ASCIIdoc files. This seems to be possible, using a combination of docinfo.html and ASCII doc 'role' variables. However, I can't check that in GitPages without adding something extra to the Jekyll configuration which GitPages is using. And even if I did that, it wouldn't show whether the same approach will work through Metanorma.

That lead me to realise that we may be able to publish ASCIIdoc on GitHub without using Metanorma - but I suspect you looked into this. GitHub uses "safe mode" ASCIIdoctor, but seems quite configurable; GitPages then adds a bit to that.

Anyway, could you try my sample with Metanorma? It's two files at https://github.com/PeterParslow/GEMINI2-3: 1-titlePP.asciidoc and docinfo.html

https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/ implies that to get ASCIIdoctor to load the docinfo requires a command line parameter.

Meanwhile, I've come to like maintaining the GEMINI element page-fragments in ASCIIdoc, if only because I no longer have to escape almost everything in each XML example!

[PeterParslow]

Over the past few months, Jo has made a lot of progress. Basically, what's left is that we need to style the pages to "pass muster" for AGI Council, and decide how to manage 'pending' and published things. I know that GitHub is designed for that, so the difficult bit seems to be styling.

Over the past couple of weeks, I've spent an hour attempting to fathom out the style sheets on the live AGI site, but they have a the typical "system generated" complexity. I've then spent another hour trying to recreate the style from scratch, but my HTML/CSS is too rusty. Me doing it is way to inefficient.

Could all GEMINI Working Group people see if they have any HTML styling expertise available in their organisation? For someone who knows what he or she is doing, it can't be that hard! Then of course, we need to make sure we can recreate that from ASCIIDoc.

@nmtoken @6footdestiny @archaeogeek @coalsh

[archaeogeek]

My 2p worth is that it doesn't necessarily be a complex job. I think if we focus on getting the basic text styles correct (headers, paragraphs, text, links etc) then I can go to council and see if that's enough. If it's not, then they can tell me what else they need and we can work on that.

[nmtoken]

Basic computed style for page (using https://www.agi.org.uk/uk-gemini/) is I think:

@charset "utf-8";
*{
    background-color: rgb(255, 255, 255);
    box-sizing: border-box;
    color: rgb(103, 97, 97);
    display: block;
    margin: 0px;
    font-family: Arial, "Helvetica Neue", Helvetica, sans-serif;
    font-size: 20px;
    font-style: normal;
    font-weight: 400;
    line-height: 36px;
    overflow-x: hidden;
    text-size-adjust: 100%;}

Page doesn't have any traditional headers.

Uses global variables for colours like:

:root {
    --tpg-primary-color: #0d6efd;
    --tpg-secondary-color: #0654c4;
    --tpg-primary-light: #c4d0ff;}

[archaeogeek]

I've made a start on the css (see https://agiorguk.github.io/gemini/datasets.html). I'm going for the low-tech approach of building up a new stylesheet (https://github.com/agiorguk/gemini/blob/main/docs/assets/gemini.css) by scratch, just overriding the elements from the original asciidoctor.css as required. I'll keep tinkering, but feel free to join in :-)

[nmtoken]

Is importing Google fonts going to be an issue for GDPR?

i.e. The @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; in asciidoctor.css

[PeterParslow]

James, could you explain? Are the Google fonts somehow likely to take away personal data? If so, I'd be curious as to how!

[nmtoken]

https://blog.runcloud.io/google-fonts-gdpr/

[PeterParslow]

Thanks. So OK if hosted locally, but not if we route each user via the Google site to get the fonts. May be easier to use a different font family.

[archaeogeek]

Updated pages now include AGI header, head and footer files using the docinfo directive. Still a WIP- can't get the footer to show on the datasets and services page at present though it does on the general pages (though missing the twitter and other icons)