Subject: Re: [Cellar] Proposal to work on Github Pages site

From: Ashley Blewer <[email-masked]>
Date: Wed, 20 Apr 2016 21:14:43 -0400

Apologies for not being more specific about this usage... I updated the
repository with information about how to view changes, view the webpage,
and view local changes. The changes are in the new README:
https://github.com/ablwr/mkv_jekyll_poc

Pull requests can't be readily made visible live, but you can pull down
someone's pull request and view it locally on your own machine. Also, if a
user forks the repo and merges their changes to their own gh-pages branch,
they should be able to see and share the differences. For example, if and
when this repo moves to MatroskaOrg, I can still fork it, commit a change
to my fork in the gh-pages branch, and see it by going to
ablwr.github.io/mkv_jekyll_poc/. Likewise, Dave could do the same and his
changes could be seen on dericed.github.io/mkv_jekyll_poc/. I hope that
makes sense.

Ashley

On Mon, Mar 28, 2016 at 8:19 AM, Steve Lhomme <[email-masked]> wrote:

> 2016-03-26 23:42 GMT+01:00 Dave Rice <[email-masked]>:
> > Hi all,
> >
> > On Mar 24, 2016, at 9:38 PM, Ashley Blewer <[email-masked]>
> wrote:
> >
> > Hi all,
> >
> > I intentionally haven't merged this PR since it's being used as an
> example.
> > I am happy to merge it in, but I myself am not representative of
> MatroskaOrg
> > so it doesn't feel right for me to approve of Dave's work on this.
>
> LGTM
>
> > Would it be better if this demo was brushed up (that's on me) and moved
> to
> > MatroskaOrg Github account and work can be commented on via the listserv
> and
> > approved there?
>
> Not sure, how can we preview the content of this repository as a
> webpage ? Can pull requests be visible as web pages too ? That would
> make it easier to validate changes.
>
> > I’ll leave this to WG Chairs, Steve, and Moritz and whomever contributes
> to
> > clarifying a contribution and approval process for the Matroska spec, now
> > that the one for EBML is getting very close to completed (I hope).
>
> IMO yes, EBML is in a good shape now.
>
> > The current Matroska spec is on a website, in Drupal posts, which is not
> so
> > RFC-like and doesn’t offer the same list of features for collaboration as
> > github. I suggest we work Matroska specification website in a GitHub repo
> > (wherever that may be located).
>
> Yes. Also the old specs will likely remain as they are, at least a
> legacy reference. We'll probably have a different URL for the official
> RFC for EBML and Matroska (in addition to being published wherever
> RFCs are).
>
> > Ashley’s draft repo at
> > https://github.com/ablwr/mkv_jekyll_poc/blob/gh-pages/index.md
> represents
> > only https://matroska.org/technical/specs/index.html. My initial PR at
> > https://github.com/ablwr/mkv_jekyll_poc/pull/1/files mostly focuses on
> > removing the redundancy with the EBML specification and instead
> deferring to
> > that as a dependency.
> >
> > For next steps I propose moving the Element Table from
> > https://matroska.org/technical/specs/chapters/index.html. I think
> eventually
> > we could have a build process that combining information from
> specdata.xml
> > with the rest of the specification to make nice human-readable versions
> and
> > interactive tables of the Matroska spec, but for specification work I
> think
> > it may help to separate the EBML Schema data of the table and the rules
> and
> > specification of Matroska into separate documents (one in xml and one in
> > markdown).
>
> Sounds good.
>
> > Also I propose moving copies of other Matroska specification pages to the
> > GitHub repo for refinement. I suggest starting with these:
> > https://matroska.org/technical/diagram/index.html
> > https://matroska.org/technical/specs/notes.html
> > https://matroska.org/technical/order/index.html
> >
> > And then moving on the the pages to focus on the Top Level Elements, such
> > as:
> > https://matroska.org/technical/specs/chapters/index.html
> > https://matroska.org/technical/cover_art/index.html (expanding this to
> cover
> > other types of Attachments)
> >
> > I think through this work we could separate the current content of
> > matroska.org in information that should become part of a Matroska RFC
> spec
> > and other data that is intended to support that (such as the info on user
> > guides, faq, downloads, logos, etc).
>
> We could use /technical/drafts/
>
> > I’m a bit inspired by the IETF work on Opus where there is now the Opus
> RFC
> > https://tools.ietf.org/html/rfc6716 and a supplementary
> > https://www.opus-codec.org website that contextualizes the RFC and
> > integrations non-spec documentation, samples, and community information.
> I
> > think a similar approach may work with Matroska.
>
> http://specs.matroska.org/ ?
>
> > Comments welcome.
> >
> > Best Regards,
> > Dave
> >
> > Let me know your thoughts!
> >
> > Ashley
> >
> > On Thu, Mar 17, 2016 at 10:45 PM, Dave Rice <[email-masked]> wrote:
> >>
> >> Hi all,
> >>
> >> To test this out, I submitted a Pull Request to Ashley’s mkv_jekyll_poc
> >> repository. I am open to either matroska-spec-repo approach as Ashley
> >> demonstrated in GitHub; however I have a preference for the jekyll
> version
> >> as we could work on the specifications in Markdown rather than directly
> in
> >> HTML. I find Markdown patches a lot easier to read than HTML patches.
> >>
> >> The pull request is here:
> https://github.com/ablwr/mkv_jekyll_poc/pull/1.
> >>
> >> The PR mainly has two changes:
> >>
> >> - The introduction is rephrased to say that the specification is WIP and
> >> associate it to CELLAR WG.
> >>
> >> > This document is a work-in-progress specification defining the
> Matroska
> >> > file format as part of the [IETF Cellar working
> >> > group](https://datatracker.ietf.org/wg/cellar/charter/). But since
> it's
> >> > quite complete it is used as a reference for the development of
> libmatroska.
> >> > Legacy versions of the specification can be found
> >> > [here](/files/matroska.pdf) (PDF doc by Alexander Noé -- outdated).
> >> >
> >> >  For a simplified diagram of the layout of a Matroska file, see the
> >> > [Diagram page](../diagram/index.html).
> >>
> >> I could also move the reference to Alexander Noé’s document into a new
> >> `Legacy Matroska` section to reference historical Matroska documents
> while
> >> contextualizing them as superseded by CELLAR’s work.
> >>
> >> - I also removed the section of the Matroska specification that is
> >> redundant to the EBML specification. Instead I added a section that
> states
> >> that Matroska is dependent on EBML like this:
> >>
> >> > ### Basis in EBML
> >> >
> >> > Matroska is a Document Type of EBML (Extensible Binary Meta Language).
> >> > This specification is dependent on the [EBML
> >> > Specification](
> https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown
> ).
> >> > For an understanding of Matroska's EBML Schema, see in particular the
> >> > sections of the EBML Specification covering [EBML Element
> >> > Types](
> https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#ebml-element-types
> ),
> >> > [EBML
> >> > Schema](
> https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#ebml-schema
> ),
> >> > and [EBML
> >> > Structure](
> https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#structure
> ).
> >>
> >> One disadvantage of the mkv_jekyll_poc repo over the mkv_pages_poc repo
> is
> >> the presentation of the Matroska Element table,
> >> http://ablwr.github.io/mkv_jekyll_poc/#elements-semantic, but I am
> >> interested in the idea of re-designing the presentation of the table.
> >>
> >> Thanks,
> >> Dave Rice
> >>
> >>
> >> > On Mar 14, 2016, at 4:29 AM, Steve Lhomme <[email-masked]>
> wrote:
> >> >
> >> > 2016-03-13 15:24 GMT+01:00 Ashley Blewer <[email-masked]>:
> >> >> We can always dedicate the table of elements to its own page -- the
> >> >> current
> >> >> page is pretty lengthy. Unless there are others who strongly favor
> the
> >> >> other
> >> >> approach, I can continue working on the Jekyll-based site and it will
> >> >> be
> >> >> ready for future collaboration with version-control built in.
> >> >>
> >> >> Steve, do you think the Jekyll site should mimic/replicate exactly
> the
> >> >> current site design or is some change in aesthetics fine? Don't know
> if
> >> >> we're tied to having the Github Page site look like Matroska.org or
> if,
> >> >> since it's for spec viewing and work in particular, it's fine to
> appear
> >> >> differently.
> >> >
> >> > The design doesn't matter too much. As long as it's easy to read and
> >> > navigate.
> >> >
> >> >> Thanks much!
> >> >>
> >> >> Ashley
> >> >>
> >> >> On Sun, Mar 13, 2016 at 6:24 AM, Steve Lhomme <[email-masked]>
> >> >> wrote:
> >> >>>
> >> >>> 2016-03-06 22:39 GMT+01:00 Ashley Blewer <[email-masked]>:
> >> >>>> Hey all!
> >> >>>>
> >> >>>> There's been some discussion about a collaborative framework with
> >> >>>> which
> >> >>>> to
> >> >>>> continue work on the Matroska specification in a code-development
> >> >>>> context
> >> >>>> after we've had conversations on this list.
> >> >>>>
> >> >>>> I'd like to propose we migrate the Matroska specification to
> Github.
> >> >>>> As
> >> >>>> I
> >> >>>> mentioned before, I'm happy to carry this transition to completion
> on
> >> >>>> a
> >> >>>> MatroskaOrg-hosted or CELLAR-hosted Github organizational account,
> >> >>>> but
> >> >>>> would
> >> >>>> like to hear from everyone on which site is the best for a
> >> >>>> collaborative
> >> >>>> environment.
> >> >>>>
> >> >>>> Option 1: Jekyll-based website that automatically translates
> Markdown
> >> >>>> to
> >> >>>> HTML.
> >> >>>> Option 1 repo: https://github.com/ablwr/mkv_jekyll_poc
> >> >>>> Please note this currently follows a Jekyll theme standard but can
> be
> >> >>>> made
> >> >>>> to look like the Matroska site.
> >> >>>>
> >> >>>> The pros and cons are both in terms of ease of use. The benefits
> are
> >> >>>> working
> >> >>>> in the more human-readable Markdown instead of HTML. The negative
> is
> >> >>>> that
> >> >>>> running a local Jekyll server to preview work before submitting a
> >> >>>> request is
> >> >>>> harder than opening up a static site.
> >> >>>>
> >> >>>> Also, tables can be difficult to read and create in Markdown.
> >> >>>> However,
> >> >>>> the
> >> >>>> primary table located on the specification page is rendered via XML
> >> >>>> and
> >> >>>> would not have to be rewritten in Markdown (although this example
> >> >>>> does
> >> >>>> have
> >> >>>> it written in Markdown).
> >> >>>>
> >> >>>> Option 2: Standard HTML website.
> >> >>>> Option 2 repo: https://github.com/ablwr/mkv_pages_poc
> >> >>>> This has been translated to replicate the Matroska site.
> >> >>>>
> >> >>>> Like I said above, previewing work doesn't require running a local
> >> >>>> server.
> >> >>>> But work is harder to read because it's in HTML and most changes
> will
> >> >>>> be
> >> >>>> very text-based anyway.
> >> >>>>
> >> >>>> After we come to a decision, I can move relevant specification
> >> >>>> details
> >> >>>> to
> >> >>>> this site and it can be used to make changes to the standard after
> >> >>>> decisions
> >> >>>> are made here on CELLAR.
> >> >>>
> >> >>> I never heard of Jekyll before but it seems interesting. That would
> be
> >> >>> for the RFC based specs, so maybe the table of elements will go in
> the
> >> >>> end or be presented differently. Until the RFC work is done we
> should
> >> >>> keep the current specs as they are, just fixing things when we find
> >> >>> issues.
> >> >>> So as a starting project I think the Markdown approach is good. We
> can
> >> >>> always go back to pure HTML and continue from there later. While the
> >> >>> opposite is more work and not trivial.
> >> >>>
> >> >>>> My best,
> >> >>>>
> >> >>>> Ashley Blewer
> >> >>>>
> >> >>>> _______________________________________________
> >> >>>> Cellar mailing list
> >> >>>> [email-masked]
> >> >>>> https://www.ietf.org/mailman/listinfo/cellar
> >> >>>>
> >> >>>
> >> >>>
> >> >>>
> >> >>> --
> >> >>> Steve Lhomme
> >> >>> Matroska association Chairman
> >> >>
> >> >>
> >> >
> >> >
> >> >
> >> > --
> >> > Steve Lhomme
> >> > Matroska association Chairman
> >> >
> >> > _______________________________________________
> >> > Cellar mailing list
> >> > [email-masked]
> >> > https://www.ietf.org/mailman/listinfo/cellar
> >>
> >
> > _______________________________________________
> > Cellar mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/cellar
> >
> >
>
>
>
> --
> Steve Lhomme
> Matroska association Chairman
>

---

From: Moritz Bunkus <[email-masked]>
Date: Sun, 24 Apr 2016 17:08:17 +0200

Hey,

thanks again for working on this, Ashley.

As there haven't been any votes against Jekyll and no specific
complaints with your work I've just copied your repository over to the
Matroska-Org organization:

https://github.com/Matroska-Org/matroska-specification

I've decided not to use Github's cloning functionality in order not to
confuse users by the "cloned from…" message – the official repo should
look official, too ;)

The history's been preserved, of course. I've also adjusted the URL to
the pages site.

Kind regards,
mosu

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 24 Apr 2016 11:11:22 -0400

On Sun, Apr 24, 2016 at 11:08 AM, Moritz Bunkus <[email-masked]> wrote:

> I'll continue to work on it with gusto!

> Emphatically agree!

---

From: Dave Rice <[email-masked]>
Date: Sun, 24 Apr 2016 20:30:09 -0400

Hi Timothy,

> On Mar 29, 2016, at 1:59 PM, Timothy B. Terriberry <[email-masked]> wrote:
> 
> Dave Rice wrote:
>> 
>>> On Mar 29, 2016, at 1:26 PM, Timothy B. Terriberry <[email-masked]> wrote:
>>> 
>>> Dave Rice wrote:
>>>> Tim, how 'done' should we be before submitting as a draft?
>>> 
>>> The normal bar for an individual draft is, "There are some words on a page."
>> 
>> In that case, here's https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown.
> 
> It still has to be submitted through the normal datatracker:
> https://datatracker.ietf.org/submit/
> 
> Submissions are currently closed in preparation for next week's meeting in Buenos Aires (as they are two weeks before every meeting, to give people time to read the drafts before the meeting). They will re-open on Monday.

I'm taking a look at the submission process in consideration of https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown. Beyond "words on a page" the upload page seems to require "Either a plain-text document or a valid .xml file which can be processed by the xml2rfc processor must be provided".

I haven't done this before but since we're working almost exclusively in markdown (in the FFV1, EBML, and MKV repos) I'd like to find an efficient way to create a Makefile or process to convert markdown to an upload-friendly document. I see some discussion in IETF lists about consideration of supporting markdown as a submission format. I've been looking at the approach used here https://github.com/miekg/mmark/wiki/Syntax, but wanted to ask for advice before proceeding too far.
Thanks,
Dave Rice

---

From: Thomas Daede <[email-masked]>
Date: Mon, 25 Apr 2016 16:51:22 -0700

Martin Thompson has a template on Github that includes makefiles to
generate a draft from Markdown.

https://github.com/martinthomson/i-d-template

It is based on a tool called kramdown-rfc2629 that will generate xml2rfc
compatible output from Markdown. It has worked well for me for a couple
of drafts in the netvc github, as well as some really big drafts, like
TLS 1.3: https://github.com/tlswg/tls13-spec

---

From: "Timothy B. Terriberry" <[email-masked]>
Date: Mon, 25 Apr 2016 17:08:24 -0700

> TLS 1.3: https://github.com/tlswg/tls13-spec

I have never used the tools in question, but Thomas's advice seems 
cogent to me (at the very least a lot better than converting by hand).

---

From: Ashley Blewer <[email-masked]>
Date: Mon, 25 Apr 2016 20:38:40 -0400

Thomas, thanks for posting this!

On Mon, Apr 25, 2016 at 8:08 PM, Timothy B. Terriberry <[email-masked]>
wrote:

> I have never used the tools in question, but Thomas's advice seems cogent
> to me (at the very least a lot better than converting by hand).
>
>

---

From: Ashley Blewer <[email-masked]>
Date: Mon, 25 Apr 2016 22:58:07 -0400

I demo'ed the above template and it seems promising, but the Markdown would
need a lot of work to get it integrated -- the current MD document includes
some unconventional HTML tags (abbr, pre) and the template also doesn't
like the way the document can link to itself using syntax like
this: [SimpleBlock structure](#simpleblock_structure). Not sure how well
this will play with Github-pages.

I'll keep investigating. Also using the core component of this (xml2rfc),
we might be able to build our own Makefile that auto-generates an RFC.

Ashley