Subject: [Cellar] layout: default

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Jul 2017 09:58:03 +0200

All the Markdown files start with:
---
layout: default
---

What is the reason for that ? Given we have to remove it before
generating the IETF files. It seems GitHub doesn't need this header to
interpret our .md files. So can we remove it ?

-- 
Steve Lhomme
Matroska association Chairman

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 16 Jul 2017 08:09:03 -0400

If I recall correctly, this is used by Github not for the Markdown section
but for when generating a static Github-pages site. One of our goals at the
time was to have that site replicate, visually, the same styles as we see
on Matroska.org. You can see it generated here:
http://matroska-org.github.io/matroska-specification/. Github-pages uses
Jekyll <https://jekyllrb.com/docs/home/> to build these sites, and Jekyll
needed that front-loaded YAML to know which HTML framework to pull from.

If this is no longer necessary and we would prefer to narrow the scope of
the repository to not include this, it can be removed. A lot of other code
could be removed, too, to simplify the repo and maintain a specific
purpose, like the sister-repo, ebml-specification.

Ashley

On Sun, Jul 16, 2017 at 3:58 AM, Steve Lhomme <[email-masked]> wrote:

> _______________________________________________
> Cellar mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cellar
>

---

From: Luca Barbato <[email-masked]>
Date: Sun, 16 Jul 2017 14:25:18 +0200

> interpret our .md files. So can we remove it ?

that front-matter looks like some metadata for some specific processor
(pandoc?), probably it is safe to drop if the ietf processor does not
use it.

lu

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Jul 2017 16:13:32 +0200

2017-07-16 14:09 GMT+02:00 Ashley Blewer <[email-masked]>:
> time was to have that site replicate, visually, the same styles as we see on
> Matroska.org. You can see it generated here:
> Jekyll to build these sites, and Jekyll needed that front-loaded YAML to
> know which HTML framework to pull from.
>
> could be removed, too, to simplify the repo and maintain a specific purpose,
> like the sister-repo, ebml-specification.

Ah, that would explain the {{site.baseurl}} stuff in the code as well.
It may work with the website generator but it gives bogus links in
IETF for the HTML output. That's issue #145 that you saw.
https://github.com/Matroska-Org/matroska-specification/issues/145

I don't know yet how to do proper link inside the same documents on
the IETF doc. But depending on the working solution it may or may not
be compatible with the website generator.

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Jul 2017 16:26:15 +0200

> know which HTML framework to pull from.

It seems we could instead use an external file to achieve the same thing ?
https://jekyllrb.com/docs/configuration/#front-matter-defaults

This way we can just keep the Markdown cleaner. It seems some of the
{{}} will still need to be worked out though.

If we want to keep both compatibility we might pre-process the
Markdown files before so that links end up correct in both cases.

As we clean the Matroska specs there will probably parts that go away
or may be reordered. And I fear this is going to be a lot of extra
work to keep both sides happy. Or it would be easier if the
pre-process takes clean RFC-compatible Markdown and changes the things
that are necessary for Jekyll/YAML.

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 16 Jul 2017 10:27:00 -0400

Yep, it causes the {{site.baseurl}}, the _includes folder, the css and sass
folders, and probably some other stuff. I'm happy to volunteer to scrape
this stuff out responsibly if we find that it's no longer essential, or
that the documentation has grown to the point where we should only be
strictly considering the schema's path-to-IETF. We can always bring the
fancy-site-building back.

On Sun, Jul 16, 2017 at 10:13 AM, Steve Lhomme <[email-masked]> wrote:

> purpose,

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Jul 2017 16:29:06 +0200

Actually before getting rid of it, it might be interesting to be able
to generate these same pages locally (via the Makefile). This way we
can test solutions to keep both happy without breaking anything
online.

2017-07-16 16:27 GMT+02:00 Ashley Blewer <[email-masked]>:
> this stuff out responsibly if we find that it's no longer essential, or that
> the documentation has grown to the point where we should only be strictly
> considering the schema's path-to-IETF. We can always bring the

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 16 Jul 2017 10:33:12 -0400

Steve, could you assign me a ticket in Github in that repo? And I'll take a
look at cleaning this up (since I'm the one who put it there in the first
place).

I'm inclined to not do any of this work immediately before the IETF CELLAR
meeting (including a merge of your split-into-3 PR that I was looking at
this morning) but happy to tackle it.

Ashley

On Sun, Jul 16, 2017 at 10:29 AM, Steve Lhomme <[email-masked]> wrote:

> that
> >> > but for when generating a static Github-pages site. One of our goals
> at
> >> > the

---

From: Steve Lhomme <[email-masked]>
Date: Sun, 16 Jul 2017 16:36:25 +0200

Here it is:
https://github.com/Matroska-Org/matroska-specification/issues/146

2017-07-16 16:33 GMT+02:00 Ashley Blewer <[email-masked]>:
>> >> > If this is no longer necessary and we would prefer to narrow the
>> >> > scope
>> >> > of

---

From: Moritz Bunkus <[email-masked]>
Date: Sun, 16 Jul 2017 16:55:48 +0200

Hey,

> If I recall correctly, this is used by Github not for the Markdown
> section but for when generating a static Github-pages site. One of our
> goals at the time was to have that site replicate, visually, the same
> styles as we see on Matroska.org.

That is correct. Due to that initial goal I had thought about replacing
the real web pages on the matroska.org website with links to the
rendered GitHub pages. My motivation was that the spec is actively
worked on, but those improvements often didn't make it into the official
website promptly.

Since then I've reconsidered. Designing websites and writing specs are
two vastly different things with different requirements and different
audiences. I'd rather we keep the informal tone on the website, but be
very technically precise and formal in the specs. The specs should then
of course be linked to from the website, but they should intentionally
not replace all the existing pages. Informal descriptions of how things
work are very important for a user but have no place in a spec.

In short: I think we need to have both. Consequently we don't have to
and should indeed not hang on to the idea of rendering the website
directly from the specs. The specs will be one part of the websites, but
only a couple of pages.

> the repository to not include this, it can be removed.

For the reasons stated above I concur.

> A lot of other code could be removed, too, to simplify the repo and
> maintain a specific purpose, like the sister-repo, ebml-specification.

Exactly.

Kind regards,
mosu

---

From: Ashley Blewer <[email-masked]>
Date: Sun, 16 Jul 2017 11:01:05 -0400

I appreciate the swift progress Steve is making in this PR and am testing
it now:
https://github.com/Matroska-Org/matroska-specification/pull/147/files

Some of this legacy information is visible in the outdated tone of the
matroska-specification README. I can refine that information once this
issue is settled and resolved.

Ashley