Please add instructions on how to build spec

[jogu]

This WG seems to use a different toolchain to other OIDF WGs - can you add instructions on how to build the spec to README.md please?

Doesn't need to go into too much in detail, e.g. an example from DCP WG: https://github.com/openid/OpenID4VP

[ogazitt]

The referenced README (for DCP) doesn't contain instructions for building the spec. The github workflow that builds the AuthZEN spec was created by @tulshi before the repo was transferred to the openid GH org.

It's true that the toolchain is pretty convoluted and it's hard to replicate locally. It requires two tools - kramdown (with a Ruby toolchain dependency) to convert the markdown files to XML, and xml2rfc (with a python toolchain dependency) to convert the resulting XML to HTML.

It's possible (but not trivial) to reproduce that environment on a local workstation. We can add some instructions for how to do that on a Mac. A better solution, of course, would be to create a docker image that included the entire environment. This is more work than the co-chairs can currently undertake, so any cycles you (or other volunteers) can dedicate to this would be greatly appreciated!

[jogu]

The referenced README (for DCP) doesn't contain instructions for building the spec.

It's here: https://github.com/openid/OpenID4VP/blob/a42365f882a5ab18e1c449259fa7f3e78d9fe256/README.md?plain=1#L31

Namely: docker run -v pwd:/data danielfett/markdown2rfc openid-4-verifiable-presentations-1_0.md

If we can improve the wording to make it more obvious please let me know how!

[ogazitt]

The referenced README (for DCP) doesn't contain instructions for building the spec.

It's here: https://github.com/openid/OpenID4VP/blob/a42365f882a5ab18e1c449259fa7f3e78d9fe256/README.md?plain=1#L31

Namely: docker run -v pwd:/data danielfett/markdown2rfc openid-4-verifiable-presentations-1_0.md

If we can improve the wording to make it more obvious please let me know how!

Sorry, not sure how I missed it! I only saw the first section on building and running the tests.

At any rate, we have a PR to add instructions to the README of the repo.

#188

[julioauto]

I made a short Dockerfile:

FROM python:3.10-alpine as python

RUN pip install xml2rfc

FROM ruby:3.1-alpine

RUN gem install kramdown-rfc

COPY --from=python /usr/local/bin/* /usr/local/bin
COPY --from=python /usr/local/lib/libpython* /usr/local/lib
COPY --from=python /usr/local/lib/pkgconfig /usr/local/lib/pkgconfig
COPY --from=python /usr/local/lib/python3.10 /usr/local/lib/python3.10

COPY make.sh /usr/local/bin

RUN apk update && apk add bash

ENTRYPOINT ["/bin/bash", "/usr/local/bin/make.sh"]

And an accompanying make.sh:

base="${1##*/}"
kramdown-rfc2629 /data/$1 > /data/${base%.*}.xml
xml2rfc /data/${base%.*}.xml --html -o /data/${base%.*}.html

Assuming you have both on your current directory, you can build an image with something like docker buildx build --tag authzen_builder:latest .

And then you can run the container from the base of the authzen repo, like:

~$ git clone https://github.com/openid/authzen
Cloning into 'authzen'...
remote: Enumerating objects: 1881, done.
remote: Counting objects: 100% (570/570), done.
remote: Compressing objects: 100% (210/210), done.
remote: Total 1881 (delta 450), reused 379 (delta 357), pack-reused 1311 (from 2)
Receiving objects: 100% (1881/1881), 2.18 MiB | 12.15 MiB/s, done.
Resolving deltas: 100% (1129/1129), done.

~$ cd authzen/

~/authzen$ ls
 CONTRIBUTING.md   README.md   api   interop  'meeting notes'   patterns

~/authzen$ docker run -v `pwd`:/data authzen_builder:latest api/authorization-api-1_0_00.md
*** attributes left {"isbn"=>9781630811341}!
---
- No link definition for link ID '[ to be removed from the final specification ]'
  found on line 693
- No link definition for link ID ' to be removed from the final specification ' found
  on line 693
.refcache/reference.RFC.4001.xml: fetching from https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4001.xml
.refcache/reference.RFC.6749.xml: fetching from https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml
.refcache/reference.RFC.8259.xml: fetching from https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8259.xml
.refcache/reference.RFC.9110.xml: fetching from https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9110.xml
.refcache/reference.RFC.9493.xml: fetching from https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9493.xml
 Created file /data/authorization-api-1_0_00.html

~/authzen$ ls
 CONTRIBUTING.md   README.md   api   authorization-api-1_0_00.html   authorization-api-1_0_00.xml   interop  'meeting notes'   patterns

If you find it OK, feel free to push the image do Docker hub under whatever name and account suits you. I do recommend adding the Dockerfile and make.sh to this repo or somewhere else for transparency. I find it annoying that I can't find the sources for markdown2rfc (the image used for the other OID WGs) anywhere.