building respec snapshots via github actions

[davidcarlisle]

In an email on www-math [1] @bert-github suggests we move to publishing respec snapshots rather than the live respec source processing

This is an issue to track discussion and/or implementation of this.

The above has links to the basic instructions [2] and looking at recent W3C TR specs a simple live spec using this is minapp-widget [3] which has source html in main branch [main]req/index.html and a github action workflow to put the respec processed document at [gh-pages]/req/index.html with the latter being served by gh-pages.

I did some trials in my fork but (not toally surprisingly) hit errors

Default branch and "GH_PAGES_BRANCH": "gh-pages" cannot be same.

So.. I think if we are to do this we would need to switch to a new (say, main) branch and set that branch as the default for push, pull requests etc. then just use the gh-pages branch to serve the generated snapshots. (and people with forks would probably need to make similar adjustments to match)

If done as in the example above the generated index.html masks the edited version, so only the generated snapshot is visible. I (think?) If I understand the instructions correctly it would also be possible to generate the snapshot under a different name say spec.html or mathml.html so that both the live draft and snapshot are visible.

But I'm not sure what we want (or which is easiest to integrate with Echidna for automated publishing to W3C TR space.

Currently the inline mathml (in mathml4) and WPT results (in mathml core) are only visible in respec souce views not in snapshots.

[1] https://lists.w3.org/Archives/Public/www-math/2022Apr/0015.html

[2] https://w3c.github.io/spec-prod/#deploy-to-github-pages

[3] https://github.com/w3c/miniapp-widget/blob/main/.github/workflows/auto-publish.yml

[xfq]

(FWIW, I just came across this thread and since I configured the miniapp-widget-req example above, I'd be happy to help if anything is needed!)

[xfq]

Personally I think it should make the loading performance better for a long spec like MathML, but I haven't tested it.

[davidcarlisle]

@xfq thanks yes I noticed afterwards that it was your addition coincidentally just after you had made some comments on the spec here:-)

On a fork of mathml-core I got this working, but currently building off main then checking the built spec into gh-pages that works as designed, but I think I want to serve both the respec live version and the snapshot,

so

https://davidcarlisle.github.io/mathml-core/spec.html

is a snapshop of today's draft (built from main)

but that leaves a 5 year old relic as the view of the live document built from gh-pages

https://davidcarlisle.github.io/mathml-core/

The supplied respec workflow does not allow the GH_PAGES_BRANCH to be the source branch but (I assume) I can get the workflow to always re-sync gh-pages from main before doing anyhing else so I end up with spec.html being the snapshot and index.html being the live copy (or maybe re-arrange so that index.html is the snapshot and src/index.html the source)

# https://w3c.github.io/spec-prod/#examples
# Create a file called .github/workflows/auto-publish.yml
name: CI
on:
  push:
    branches: [main]
jobs:
  main:
    name: Deploy to GitHub pages
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: w3c/spec-prod@v2
        with:
          GH_PAGES_BRANCH: gh-pages
          TOOLCHAIN: respec
          SOURCE: index.html
          DESTINATION: spec.html
          VALIDATE_MARKUP: false

[davidcarlisle]

I think I have this working now in my mathml-core fork

live respec version

https://davidcarlisle.github.io/mathml-core/

updated respec snapshot

https://davidcarlisle.github.io/mathml-core/spec.html

@xfq Not sure if this git reset is too agressive? (the gh-pages branch is essentially only used as a device for gh-pages so resetting it to match main doesn't seem too bad?....)

# https://w3c.github.io/spec-prod/#examples
# Create a file called .github/workflows/auto-publish.yml
name: CI
on:
  push:
    branches: [main]
jobs:
  main:
    name: Deploy to GitHub pages
    runs-on: ubuntu-20.04
    steps:
     - uses: actions/checkout@v2
     - run: |
          git fetch
          git checkout gh-pages
          git reset main --hard
          git push -f
     - uses: w3c/spec-prod@v2
       with:
          GH_PAGES_BRANCH: gh-pages
          TOOLCHAIN: respec
          SOURCE: index.html
          DESTINATION: spec.html
          VALIDATE_MARKUP: false

@ljmaher is

https://davidcarlisle.github.io/mathml-core/spec.html

better for your screen reader than

https://davidcarlisle.github.io/mathml-core/

?

[ljmaher]

Hello David,

You asked:

is

https://davidcarlisle.github.io/mathml-core/spec.htmlhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2Fspec.html&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=klCYZEVa%2B1Log%2FPcFvZ%2BEif%2FISKikNkgFMliDYWVsp8%3D&reserved=0

better for your screen reader than https://davidcarlisle.github.io/mathml-core/https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2F&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=6Me9PyTZsxSF8udy2mx6ZquvPAnmGkFHRxJlG21Qqvc%3D&reserved=0

The answer is yes.

Generally, NVDA does a better job at accessing ReSpec then does JAWS. JAWS with Edge does the poorest job with ReSpec. NVDA with Firefox does the best job.

In your file

https://davidcarlisle.github.io/mathml-core/spec.htmlhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2Fspec.html&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=klCYZEVa%2B1Log%2FPcFvZ%2BEif%2FISKikNkgFMliDYWVsp8%3D&reserved=0

JAWS and Edge works perfectly. There is a table of contents, and the sections have numbers.

For https://davidcarlisle.github.io/mathml-core/https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2F&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=6Me9PyTZsxSF8udy2mx6ZquvPAnmGkFHRxJlG21Qqvc%3D&reserved=0

NVDA and Firefox provides all the text and a table of contents and section numbers.

Thanks for your help.

Regards Louis Maher Phone: 713-444-7838 E-mail: @.***

From: David Carlisle @.> Sent: Tuesday, April 26, 2022 6:22 AM To: w3c/mathml @.> Cc: ljmaher @.>; Mention @.> Subject: Re: [w3c/mathml] building respec snapshots via github actions (Issue #329)

I think I have this working now in my mathml-core fork

live respec version

https://davidcarlisle.github.io/mathml-core/https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2F&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=6Me9PyTZsxSF8udy2mx6ZquvPAnmGkFHRxJlG21Qqvc%3D&reserved=0

updated respec snapshot

https://davidcarlisle.github.io/mathml-core/spec.htmlhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2Fspec.html&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=klCYZEVa%2B1Log%2FPcFvZ%2BEif%2FISKikNkgFMliDYWVsp8%3D&reserved=0

@xfqhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fxfq&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=wqsxXRNawvoMFtlNn3FGtsJPFPtHWUmsNg3r3I2CoWU%3D&reserved=0 Not sure if his git reset is too agressive? (the gh-pages branch is essentially only used as a device for gh-pages so reseting it to match main doesn't seem too bad?....)

https://w3c.github.io/spec-prod/#examples

Create a file called .github/workflows/auto-publish.yml

name: CI

on:

push:

branches: [main]

jobs:

main:

name: Deploy to GitHub pages

runs-on: ubuntu-20.04

steps:

 - uses: ***@***.***

 - run: |

      git fetch

      git checkout gh-pages

      git reset main --hard

      git push -f

 - uses: ***@***.***

   with:

      GH_PAGES_BRANCH: gh-pages

      TOOLCHAIN: respec

      SOURCE: index.html

      DESTINATION: spec.html

      VALIDATE_MARKUP: false

@ljmaherhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fljmaher&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Yi3YDA2qitZXhupUeOUWfL2Eh%2BFgUsxIytjK2im4llo%3D&reserved=0 is

https://davidcarlisle.github.io/mathml-core/spec.htmlhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2Fspec.html&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=klCYZEVa%2B1Log%2FPcFvZ%2BEif%2FISKikNkgFMliDYWVsp8%3D&reserved=0

better for your screen reader than

https://davidcarlisle.github.io/mathml-core/https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdavidcarlisle.github.io%2Fmathml-core%2F&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=6Me9PyTZsxSF8udy2mx6ZquvPAnmGkFHRxJlG21Qqvc%3D&reserved=0

?

- Reply to this email directly, view it on GitHubhttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fw3c%2Fmathml%2Fissues%2F329%23issuecomment-1109674083&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=aOC1oMYvs321X%2FJPQzQTEclhIVFMtOuCVNM%2BaG6PYo0%3D&reserved=0, or unsubscribehttps://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAP4IYUKA3T3OJJ6H54E3DNDVG7GVFANCNFSM5UIFQICQ&data=05%7C01%7C%7C5a0605ebeb6e4996d96e08da2776f899%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C637865689173071116%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=FdXOac%2FCuvNYFNyJiomVb4wUU4%2FETay0Z6EVl0TnweY%3D&reserved=0. You are receiving this because you were mentioned.Message ID: @.**@.>>

[xfq]

@xfq Not sure if this git reset is too agressive? (the gh-pages branch is essentially only used as a device for gh-pages so resetting it to match main doesn't seem too bad?....)

I think it's fine as long as index.html and respec.html in gh-pages are up-to-date and not missing assets (images, scripts, etc.). Resetting it to match main looks good to me.

[davidcarlisle]

This has been done

https://w3c.github.io/mathml/spec.html