Re: ReSpec extensions

> On 8 Nov 2021, at 11:20 am, Manu Sporny <msporny@digitalbazaar.com> wrote:
> 
> On 11/4/21 7:09 PM, Marcos Caceres wrote:
>> We have a Developers Guide that describes plugins - apologies if it wasn't
>> easy to find: https://github.com/w3c/respec/wiki/Developers-Guide
> 
> *doh* -- I looked, I swear. It *is* right there in the ReSpec README.md... and
> on the ReSpec wiki home page.
> 
> That said, a link from here would probably help:
> 
> https://respec.org/docs/
> 
> Want me to raise a PR with a suggestion? I'm thinking an appendix called
> "Developer Guide" -- I read this, so I think I know what to do:
> 
> https://respec.org/docs/#editing-this-document

Filed: 
https://github.com/w3c/respec-web-services/issues/247

And yeah, would be good to add... 

> I'll also read the Developers Guide before doing any of this now that I know
> where it is. I have been looking for it for years, with a process that goes
> like: 1) I want to add new behaviour to ReSpec, 2) Unsure of how to "add a
> plugin", so I go looking for a developer guide, 3) something else blows up and
> I give up, thinking I'll come back to it in a week (and I don't).

Sad to hear that. In addition to this mailing list, you (or anyone) can also alway reach out for help on Github, and more recently, the W3C Community Slack (#respec channel).

There are a few of us there who can also provide general guidance on JS stuff. 

>> To include something in the "w3c-profile" itself, we generally evaluate if
>> multiple working groups would benefit from the edition. If you think many
>> groups would, then I'd be happy to discuss adding that to the w3c-profile.
>> 
> At present, I only expect WGs working on HTTP APIs *and* using OAS to find it
> useful... which is just one WG at present. So, happy to keep it of in a corner
> until there is greater demand (if ever).

Ok, yeah... so probably best as a "pre/postProcess" function.

> The stuff I was really looking for in a Developer Guide was something like:
> "Here is how you should structure your code so it's easy to use by itself, or
> if you want it pulled into a respec profile in the future."

Right... that's a tricky one, but we could probably clarify things... ReSpec is "just HTML". Once it runs, it gets out of the way and lets other scripts do whatever they want/need. 

In that sense, general JS/Web Development "best practices" are the only things that apply. But yes, we should state that as, at the same time, I can understand that that is not obvious to everyone. 

> I'll try to go look at some code after reading the Developers Guide.
> 
> Thank you! I've got somewhere to start.

No problem. If you want me to look at any JS specifically, please feel free to ping me privately or cc me on GitHub.

Received on Monday, 8 November 2021 00:50:40 UTC