Re: Bikeshed

Thanks.  LGTM.

On 12/14/2018 4:05 AM, Florian Rivoal wrote:
> Hi all,
>
> As the review period for the 2019 Process is so far going quietly, before we get to the 2020 cycle, I took the opportunity to prepare a large editorial/markup change we had been talking about for a while.
>
> On an experimental branch, I have converted the process to use the bikeshed spec preprocessor. I have not merged it yet, nor am I sending it as a pull request yet, but I wanted to give a little preview.
>
> TL;DR: preview is here: https://frivoal.github.io/w3process/
>
> This conversion has the following benefits:
>
> 1. Section numbering and ToC
>    * The table of content is auto-generated
>    * The section numbers in each section title are auto-generated
>    * The section numbers in each cross-reference are auto-generated (i.e. in links like this: See <a href="#Consensus">section 3.3</a>)
>    * cross-references to non existing anchors cause a build-time error
>    * section titles without a manually defined id cause a build-time error
>
>    => All this eliminates the risk of inconsistencies and broken links or mistaken references, even when adding, removing, renaming, or reordering sections
>
> 2. definitions
>    * Any term marked up with a <dfn> element is added to an auto-generated index at the end of the document
>    * Thanks to easy syntax (like <a>this</a> or like [=that=]), terms with special meaning can be automatically linked to the corresponding <dfn>, and I have done so fairly extensively.
>
>    => This solves https://github.com/w3c/w3process/issues/198 and makes reading section of the Process out of context (which is generally the case, as it is rarely read top to bottom) much easier since the reader can easily find definitions for key terms.
>
> 3. Bibliography
>    * Bikeshed has facilities for automatically managing the bibliography. We can just cite known documents like [[RFC2119]] and they get automatically added to the reference section.
>    * Bikeshed will warn if the documents we try to reference are obsolete. This has uncovered  https://github.com/w3c/w3process/issues/233 for instance
>    * This avoids the reference section and the body of the document getting out of sync
>
> 4. Cross-document linking
>    * automatic links to [=known terms=] can work across documents. Terms defined in other documents can be referred to in the Process just as easily as terms defined inside it, and when we do that, these other documents automatically get added to the reference section, and these externally defined terms also get an entry in the index.
>    * The meta-data included in the output enables the Process to be indexed so that other documents can start referring to terms defined in the Process with the same ease.
>    * When linking to a section of another document known to bikshed, the title and number of that section can be automatically computed, avoiding things getting out of sync
>
>    => I am not taking advantage of this yet in this conversion, but going forward, enabling the bikeshed ecosystem to more easily link to terms and sections in the process will be nice.
>
>    => Also, hypothetically, if we later did the same to the Patent policy, we could change markup like this:
>> as per <a href="https://www.w3.org/Consortium/Patent-Policy/#sec-exclusion-with">section 4.1</a>
>> of the <a href="https://www.w3.org/Consortium/Patent-Policy" data-ref="PUB33">W3C Patent Policy</a>
> to
>> as per [[PATENT-POLICY#sec-exclusion-with]].
> which is not only easier to write, but also makes sure there's no mistake in the section number, even if the target document were to get reorganized.
>
> 5. Easier source code
>    Between the various simplification above, and the fact that bikeshed can consume markdown rather than HTML, the source code becomes more readable, more maintainable, and smaller by 15%. Thanks to a lighter syntax and the fact that the build step can point errors, it should prevent problems like https://github.com/w3c/w3process/pull/205 or https://github.com/w3c/w3process/pull/126 or https://github.com/w3c/w3process/pull/78 or https://github.com/w3c/w3process/pull/200/commits/1faa69d367159c59c2275fa3a8351165339a3cd0
>
>    While I was at it, as I was touching most of the file anyway, I've taken the opportunity to make coding style and indentation consistent throughout the document.
>
> 6. Better styling
>    This could have been achieved without bikeshed, but this was also an opportunity to update the process to the latest stylesheet, make it responsive thanks to a viewport metatag
>
> The experimental result is available here:
> https://frivoal.github.io/w3process/
>
> The old one for comparison:
> https://w3c.github.io/w3process/
>
> Here's an HTML diff:
> https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fw3c.github.io%2Fw3process%2F&doc2=https%3A%2F%2Ffrivoal.github.io%2Fw3process%2F
>
> You'll see that the body of the text is unchanged, except for:
> * A slightly different structure for the document header
> * Some fixes in the autogenerated ToC
> * Some bikeshed-driven typographical improvements such as using curly quotes instead of straight ones, or an em-dash instead of hyphen-minus where appropriate
> * Some differences about the formatting of section references and cross document references
> * A lot more cross references between terms and their definitions (not visible in the HTML diff, as the text is unchanged and these are merely new links)
> * A differently structured References section
> * The new Index section https://frivoal.github.io/w3process/#index
>
> I may tweak this a little bit more over the next few days. I'll also need to add some documentation about bikeshed for those who're not familiar with it, and I'll also set up automatic server side builds.
>
> If all goes well, I would like to make this the first thing we land for for Process 2020, so that we can start on a clean basis. (I'll also rebase any pre-existing open PR on top of this so that there's no merge conflict).
>
> Feedback welcome.
>
> —Florian
>
> PS: As I've re-read the whole document in detail from top to bottom, I've found a number of editorial or not-so-editorial issues along the way. To keep the change easy to review, I have refrained from fixing them, and will later report separately.

Received on Friday, 14 December 2018 13:19:34 UTC