search

agiorguk / gemini

Resources relating to the UK Gemini metadata profile
5 stars 3 forks source link

How to manage & publish GEMINI pages #64

Closed PeterParslow closed 2 months ago

PeterParslow commented 3 years ago

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 commented 3 years ago

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:

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 commented 3 years ago

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

PeterParslow commented 3 years ago

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 commented 3 years ago

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

PeterParslow commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

Looking down the ASCII Doc / Metanorma route:

However, to use "include",

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

archaeogeek commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

PeterParslow commented 2 years ago

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 commented 2 years ago

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)