Use BikeShed

[woutermont]

I wonder if anyone would object to using BikeShed instead of ReSpec to render the W3C layout around our spec.

I personally find it a lot more comfortable and maintainable. It is basically a Markdown variant that you run through a preprocessor to get the HTML. This makes it a lot more readable. It also allows for a clear separation between content, metadata and bibliography. All this additionally makes diffs in PRs much more easy to consume as a reviewer.

In any case, it's just a proposal. I know there are some people who prefer to dig the HTML tags of ReSpec 😉

[TallTed]

None of the groups I am or have been in use BikeShed, so far as I'm aware. I review a LOT of ReSpec markup, and it's quite readable. It even supports bits and pieces of Markdown (e.g., ` wrappers can be used instead of <code>), which are surprising when first encountered, but have not been hard to adapt to.

I will also note that in my experience, Markdown is FAR less powerful or flexible than HTML, and hence, less useful for complex layout, which is often desirable if not necessary in specification documents. Theoretically, HTML can always be included in a Markdown document; this is not always so, in practice. Having no evidence either way, I would not be surprised to find that BikeShed is similarly less powerful or flexible than ReSpec.

I would need to see an example set of documents that use both markup schemes, one per document, to produce (roughly) the same (hopefully complicated) HTML after ReSpec or BikeShed processing, to have an educated response to this. Lacking such, I'd prefer to stick with the ReSpec.

[woutermont]

@TallTed, I understand your conservative stance, but I can assure you that BikeShed is a lot more readable than ReSpec. Whether the later is more powerful than the former in absolute sense, I couldn't say, but I have used it in multiple projects without ever bumping into a limit. You can actually include any HTML in it whenever the Markdown is not enough.

For a relevant example, you can take a look at the Solid Application Interoperability specification.

[jacoscaz]

/chair hat off

IMHO, markdown would make for much, much more enjoyable diffing and comparing. +1!

[TallTed]

@woutermont — Could you link to the actual document in question, rather than the Solid Application Interoperability repository (which holds a great many documents)?

[TallTed]

I'm also wondering whether you mean to switch to BikeShed just going forward (for new documents), or to entirely revamp the existing document(s), which seems like a lot of extra work atop the content work that already needs doing.

[melvincarvalho]

Maybe give it a try, for new work, and see whether or not folks like it?

Markdown plays more nicely with LLMs, too.

I would be very interested in the workflow.

[webr3]

just going forward (for new documents)

+1 to this

[woutermont]

@TallTed, I believe all documents in the repo are BikeShed actually, but to make it concrete: this is the index of the spec itself. It mostly includes metadata and bibliography, and includes the other BikeShed files in the same folder, which contain mostly markdown text for each section.

The idea would indeed be to translate the latest draft to BikeShed (I can do that), and work on that for the foreseeable future. Let's perhaps put a time interval on it, and if it doesn't work out, revert and apply the passed changes to the original ReScript file.

[TallTed]

[@woutermont] all documents in the repo

Please be explicit when you say things like the above.

In context, "the repo" you most likely meant is "the repo" in which we're currently talking, i.e., w3c/WebID, but it appears from the index link you included that "the repo" you actually meant is solid/data-interoperability-panel.

The current editors draft of the WebID spec, which is what we've been discussing here, is in ReSpec, not BikeShed.

Having now taken a brief surf through the data-interoperability-panel spec to which you linked tells me, this will not be a quick-and-easy transition for me and perhaps not for others who are fairly familiar with Turtle, HTML, Markdown, and even ReSpec, but not so native in our reading of JSON-LD, and minimally if at all familiar with BikeShed notation.

I am not in favor of migrating existing (WebID or other) ReSpec docs at this time. A BikeShed experiment for new (especially WebID) docs might be worthwhile.

[melvincarvalho]

In context, "the repo" you most likely meant is "the repo" in which we're currently talking

I didnt read it that way. I read that wouter was doing you a favour by helping you click through a hyperlink, and then click on a bikeshed document. IMHO it was a fairly evident task, and wouter was generously helping to guide you. 1-2 minutes of exploring his original hyperlink would have enabled you to answer your question, rather than the whole group managing your navigation path. e.g. by clicking on the word "bikeshed". Personal navigation issues may be more easily handled out of band, than involving the whole group.

[melvincarvalho]

Having now taken a brief surf through the data-interoperability-panel spec to which you linked tells me, this will not be a quick-and-easy transition for me and perhaps not for others

IMHO seems fairly simple and straightforward.

[melvincarvalho]

@woutermont do you have any links that you'd recommend in addition to the living standard.

It seems to me that a sensible way to proceed would be to do the scaffolding as a first step, with some boiler plate. Then add sections one at a time, starting with the abstract.

How does that sound?

[melvincarvalho]

From what I can see the most sensible way to proceed is to use

https://github.com/solid/data-interoperability-panel/blob/main/build.sh

echo "Build: running bikeshed"
bikeshed spec proposals/specification/index.bs
bikeshed spec  proposals/primer/application.bs
bikeshed spec  proposals/primer/authorization-agent.bs

echo "Build: running mermaid for sequence diagrams"
for diagram in proposals/*/diagrams/*.seq.mmd
  do
    npx mmdc -i $diagram
done

echo "Build: running mermaid for flowchart diagrams"
for diagram in proposals/*/diagrams/*.flow.mmd
  do
    npx mmdc -i $diagram -o $diagram.png
done

echo "Build: done!"

Then a folder for the spec, specification, seems a good term

In our case we would not need either of the mermaid documents, initially

[melvincarvalho]

The final step that I can see is to replace this:

<pre class="metadata">
Title: Web Identity and Discovery [WebID]
Shortname: 
Level: 1
Max ToC Depth: 2
Status: 
Group: w3c
URL: 
Repository: 
Inline Github Issues: title
Editor: Jacopo Scazzosi
Markup Shorthands: markdown yes
Boilerplate: conformance no
Dark Mode: off
Abstract:
  This specification defines a standard means by which user agents 
  and servers interact to establish a user's identity, ensuring a structured, 
  decentralized approach for identity discovery on the web.  
</pre>

[woutermont]

Coincidentally I already translated the entire core spec to Bikeshed the past two days. The result is #45.

I indeed use part of the workflow of solid/data-interoperability-panel to allways keep a rendered version of the markdown in sync. Note that the W3C actually provides a GitHub Action (spec-prod) to validate and render Bikeshed, but it can only target GitHub Pages or the W3C Echidna system, not the branch itself.