search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
139 stars 25 forks source link

Proof of concept for authoring spec in markdown #110

Closed tpluscode closed 7 years ago

tpluscode commented 7 years ago

In the previously used version of ReSpec only inline markdown was supported. With great help from @marcoscaceres, now it's possible to create specification sections in imported markdown files (see w3c/respec#993)

Please let me know if you'd like to explore splitting the spec in smaller chunks.

Also, I refactored the respec-w3c-extensions.js file to be independent of jQuery (see this comment)

RubenVerborgh commented 7 years ago

While this is great, we should probably differentiate between two goals:

So I see this work in the second context; is this what you have in mind?

tpluscode commented 7 years ago

Yes, I had the actual spec in mind. "Bothering about language" doesn't interfere with ease of authoring. Markdown and/or splitting the HTML in smaller chunks could make it easier to author the specs.

lanthaler commented 7 years ago

Iā€™m not sure what the desired goal of this proof of concept is. Do you want to convert the entire spec to Markdown? Do you want to split it into multiple files? Both?

tpluscode commented 7 years ago

Probably both with the preference of splitting if first into multiple files. Smaller files could be easier to manage than one large HTML document, with all that indentation and pointy markup. And markdown is just easier to edit.

And contribute. That is the real goal. Lower the barrier.

asbjornu commented 7 years ago

I approve of this pull request, or at least of the direction it is moving. šŸ˜„ šŸ‘ I too would like the spec to be entirely written in Markdown and while the spec currently is less than 1000 LOC, it needs to grow to incorporate informative examples and such. In that future scenario, managing a larger set of smaller, feature-focused files, is easier than one gigantic one.