Re: Proposed Correction extension for ReSpec?

Hi Manu, 

> On 22 Nov 2021, at 6:45 am, Manu Sporny <msporny@digitalbazaar.com> wrote:
> 
> You can read more about the tool here:
> 
> https://github.com/digitalbazaar/respec-vc#readme
> 
> Or if you want to just play around with an example, you can do that here:
> 
> https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/pull/834.html#example-usage-of-the-id-property

Neat. 

> The structure of what's going on here is very similar to what I think we want
> for the Proposed Correction stuff... multiple tabs showing "before", "after",
> and "diff view".  What I need to know is:
> 
> 1. Do others think that's the sort of thing we are looking
>   for?

This is good, but I'm still extremely concerned about the amount of manual labour being dumped on spec Editors. 

<rant>
In particular, I feel pretty strongly that Editors shouldn't be put in a position where they have to manually include before/after changes. I'm hearing _a lot_ of negative feedback from folks in multiple working groups about how annoying/frustrating this process is going to be, which is really concerning to me as and editor, tool maintainer, staff, and as a chair.  

If it proves too much, most Editors will opt to just stay in CR or just opt to publish as REC and then go straight back to FPWD (or, I'll be recommending they do this instead to save them the trouble). That seems counter productive and defeats the purpose of what we were trying to achieve with the Process changes. 
</rant>

> 2. Is this an addition to ReSpec's code base, or a
>   separate extension, and if so, is this[1] the right
>   model to follow?

If it's something that's generally useful, then it could be specified as a plugin: 
https://respec.org/docs/#developers-guide

> 3. I expect there are accessibility/print issues with
>   actively hiding/showing tabs... any pointers there?

We would need to work with the right community... coincidently, the "Aria in HTML" folks are also about to update their REC, so they could probably provide the best guidance.
 
> 4. Is this how a ReSpec extension should inject styles
>   into the document?
>   https://github.com/digitalbazaar/respec-vc/blob/main/index.js#L73-L104

These are injected via JS. See: 
https://github.com/w3c/respec/tree/develop/src/styles

And, as an example, import:
https://github.com/w3c/respec/blob/develop/src/core/webidl.js#L18

And insert:
https://github.com/w3c/respec/blob/develop/src/core/webidl.js#L400-L402

> 5. Is this how a ReSpec extension should inject
>   code into the document?
>   https://github.com/digitalbazaar/respec-vc/blob/main/index.js#L106-L138

Yes, something like seems fine. However, if we can make it make is an external script, all the better. 

> 6. Is there a better way to get "default CSS colors for
>   things" than this?
>   https://github.com/digitalbazaar/respec-vc/blob/main/index.js#L94

See all the CSS variables at:
https://github.com/w3c/tr-design/blob/gh-pages/src/base.css#L79


> 7. Should this be a global? How should people export
>   things we want postProcess to call?
>   https://github.com/digitalbazaar/respec-vc/blob/main/index.js#L254-L257

Ideally, one would make everything static and driven by CSS. Certainly wouldn't want to run "createExmples()" on every page load.   

> 8. Do we have a favoured Javascript-based diff'ing
>   library we want to use?

We don't. No. But if there is one, that be great.... 

> If folks feel like this is a useful path, I'm happy to take a cut at an
> extension that makes candidate/proposed corrections easier for spec editors.
> I'm also happy to stand aside and let the experts address the issue. :)

Personally, I think we should explore what the Process requirements are, and look at what the minimal amount of work is to get what we need. 

If we want to do the diff'ing thing, I think we should be doing that with git (maybe via the GitHub API) or some other custom API that pulls down diffs. 

IMO, the right place to view the diffs is on Github and/or via .pr-preview. 

Kind regards,
Marcos

Received on Monday, 22 November 2021 00:18:08 UTC