search

w3c / did-core

W3C Decentralized Identifier Specification v1.0
https://www.w3.org/TR/did-core/
Other
404 stars 94 forks source link

(editorial) replace some markdown with html tags #660

Closed TallTed closed 3 years ago

TallTed commented 3 years ago

backticks -> <code /> and associated line lengths

Preview | Diff

msporny commented 3 years ago

Hrm, this is a good catch, but we should be doing the /opposite/ thing with the spec. I'm going to merge this in to make things consistent... but ReSpec uses the backtick mechanism to specifically avoid the proliferation of <code></code> markup. Inline tags make things harder to read from an Editorial perspective and the difference between the two has no effect from reader's perspective.

We should replace all <code></code> with backtick markup. We'll do this in another PR.

msporny commented 3 years ago

Editorial, multiple reviews, alternate path proposed for a future PR, no objections, merging.

TallTed commented 3 years ago

Hrm, this is a good catch, but we should be doing the /opposite/ thing with the spec. I'm going to merge this in to make things consistent... but ReSpec uses the backtick mechanism to specifically avoid the proliferation of <code></code> markup. Inline tags make things harder to read from an Editorial perspective and the difference between the two has no effect from reader's perspective.

We should replace all <code></code> with backtick markup. We'll do this in another PR.

Ayie... So raw ReSpec docs look like HTML, but aren't really, and make the Editor's job more arcane (because an Editor [and any attentive authors/contributors] must understand HTML and Markdown and ReSpec markup). I do not like this.