[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=