search

w3c / rdf-star

RDF-star specification
https://w3c.github.io/rdf-star/
Other
118 stars 23 forks source link

EBNF files and references #218

Closed gkellogg closed 2 years ago

gkellogg commented 2 years ago

This adds EBNF for the -star versions of the following:

Preview | Diff

gkellogg commented 2 years ago

One problem will be publishing multiple linked files. Maybe they should be absolute URLs so taking a copy of the spec doc still links to the EBNF files. The links can be into the GH repository for now.

@dontcallmedom Is there some established practice for where to put related documents for specs (CG Final Report, in this case). We have 5 EBNF files form grammars updated in the spec, which are currently located relative to the GitHub Editor's Draft. If this were published at w3.org/TR/rdf-star, then they might be at w3.org/TR/rdf-star/ebnf/n-triples.ebnf and so forth, if the publication process can handle that. Otherwise, at w3c.github.io/rdf-star/ebnf/n-triples.ebnf, but they are not versioned along with a published report.

dontcallmedom commented 2 years ago

@gkellogg assuming you'll request to publish the final report on the W3C Web site, you can include additional files to be published along with the main HTML, and thus use relative links from the HTML. /cc @ianbjacobs to make sure this indeed matches our practices.

gkellogg commented 2 years ago

As a CG Final Report, it would more likely go in time-stamped space (https://w3.org/2021/rdf-dev/... rather than /TR. This might require some help to get related files moved up, given the interface for publishing CG reports.

dontcallmedom commented 2 years ago

yes, we regularly help uploading dated cg reports on w3.org - see for instance https://www.w3.org/2021/06/musicxml40/

gkellogg commented 2 years ago

I could render HTML versions of the grammars instead; there does not seem to be any appropriate media type for for any sort of BNF. Alternatively, we can add an Apache config to set it to text. I’m not a fan of simply adding .txt. Of course, this won’t help with GHpages.

The sentences can be made notes to make non-normative.

pchampin commented 2 years ago

I could render HTML versions of the grammars instead; there does not seem to be any appropriate media type for for any sort of BNF.

I'm happy with rendering the grammars as plain text.

Alternatively, we can add an Apache config to set it to text.

Yes of course, but as you point out, we can't do this on GH pages. And it might be cumbersome on w3.org as well.

I’m not a fan of simply adding .txt.

If .ebnf was referring to a dedicated media-type, I would agree... Anyway, this is not blocking for me...

The sentences can be made notes to make non-normative.

+1

gkellogg commented 2 years ago

(Thought I had already left this comment, but in any case, here it is again).

I think using HTML versions of the grammars might really be the best thing. I have software to render them, for example as is done for the N3 Grammar. We could also put some boilerplate around it, a s we do in our Implementation Report. This is consistent with how grammars are presented in other serializations, and for those who really want them, we can keep the EBNF source documents in the repo. For most users, being able to link between the different productions is probably easiest.

pchampin commented 2 years ago

The HTML rendering are indeed really nice. But at this point, we might as well include them as appendices in the report, WDYT? Respec can do that: https://respec.org/docs/#external-includes

gkellogg commented 2 years ago

Yeah, I think appendices make sense, I’ll update, and possibly relocate the files.

gkellogg commented 2 years ago

There are some markup errors from the EBNF, and may be some overlapping anchors, which I'll address this weekend.

pchampin commented 2 years ago

This was discussed during today's call: https://w3c.github.io/rdf-star/Minutes/2021-10-29.html#x135