[ReSpec] - Better documentation of shorthands
Marcos Caceres <[email protected]> Mon, 10 Feb 2020 21:28:40 +1100
| Newsgroups | gmane.org.w3c.specifications |
|---|---|
| Message-ID | <[email protected]> |
Hi All,
Janice Shiu, one of Mozilla's Outreachy [1] Interns for 2020, has kindly =
help us put together some great documentation for ReSpec's shorthands. =20=
tl;dr: ReSpec supports many of the same shorthands that BikeShed =
supports (but not all!), making it easier for everyone to edit both =
ReSpec and BikeShed specifications at the same time.=20
Quick examples below of What ReSpec can do.
Full docs of the shorthands:
https://github.com/w3c/respec/wiki/Shorthands-Guide
## Long version
Similar to markdown, shorthands are custom ways of writing things that =
trigger special behavior in ReSpec. The most common one you've used is =
[[Reference]]. Shorthands save you time and work: you write a lot less =
HTML, and ReSpec does all the linking and error checking for you.
Each of these special character combinations, as well as what behavior =
they trigger, are detailed below.
Note that WebIDL identifiers are case sensitive.
## Examples
Below is the syntax and real example of usage:=20
* WebIDL: {{WebIDLThing}} - The {{PaymentRequest/show()}} method.
* Concepts: [=3Dnormal link=3D] - [=3Dqueue a task=3D].
* Variables: |variable:Type| - Let |p:Promise| be a new {{Promise}}.
* HTML elements (different to BikeShed): [^element^] - The [^iframe^] =
element has an [^iframe/allowed^] attribute.
* Expansions: [[[#some-id]]] - [[[#example-2]]] expands and links to =
"Example 2"
* References: [[shortName]] - As stated in [[RFC2119]]...
Any questions, please refer to the guide linked to above... or please =
feel free to reach out to us.=20
## =F0=9F=92=B0 Please support us =F0=9F=92=B0
If you like using ReSpec, please consider sponsoring our project. The =
money will go towards providing opportunities for emerging developers =
and designers from under represented groups, and for improving the =
overall quality of the software (Marcos doesn't make any money from it, =
promise! :)).=20
We've raised around US$250 so far, but we'd like to raise a few thousand =
to maybe fly out an maintainer to the next TPAC and to give ReSpec a new =
coat of paint.=20
If you or your organization depends on it, please consider sponsoring =
us:
https://opencollective.com/respec
We are happy to also work out sponsorship arrangements to add something =
that's currently missing.=20
Kind regards,
Marcos
[1] More info about Outreachy at https://outreachy.org=