Re: Bikeshed

Hi all,

As we prepare to start the Process 2020 cycle, I have rolled out the bikeshed changes to the repo.

(Note: The vote for Process 2019 is closed, and conclusions should be out soon. If any change is needed for that, I'll handle it on a separate branch)

This means that from now on:

* The main branch is the master branch (not gh-pages anymore), and the file to edit is index.bs (not index.html anymore). Send Pull Requests for index.bs based on the master branch, not for index.html based on the gh-pages branch. I have rebased existing open pull requests.

* The index.html page does not exist in the main branch anymore, and it should not be added back. It is built automatically server side and pushed to the gh-pages branch, from which https://w3c.github.io/w3process/ is served. Also, for the same reason, do not manually commit to the gh-pages branch anymore.

* If you've never used bikeshed before, it is very similar to markdown, with a few extra niceties that makes spec writing easy. Reading the source should generally be straightforward. Documentation about the syntax is available here: https://tabatkins.github.io/bikeshed/#markup-shortcuts

* You can generate the index.html page locally to read the Process offline, or to check that your commits have the intended effect. If you have bikeshed installed already, just run type "bikeshed" in the command line from the repo's root directory. If you don't have bikeshed yet, instructions for how to install it on all major OSes are here: https://tabatkins.github.io/bikeshed/#installing

* If you have any issue, tell me, and I'll fix it / explain it / document it, as appropriate.

* For those who care about such minutiae, in addition to building and publishing master/index.bs to gh-pages/index.html, the server side integration will also build and publish Dispositions of Comments (master/issues-*.txt -> gh-pages/issues-*.html), and publish as is any snapshots (master/snapshots/* -> gh-pages/snapshots/*).

Happy bikeshedding,

—Florian

> On Dec 14, 2018, at 18:05, Florian Rivoal <florian@rivoal.net> 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 Monday, 4 February 2019 09:21:48 UTC