[ReSpec] - Better documentation of shorthands

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.  

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. 
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: 

* WebIDL: {{WebIDLThing}} - The {{PaymentRequest/show()}} method.

* Concepts: [=normal link=] - [=queue a task=].

* 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. 

## 💰 Please support us 💰

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! :)). 

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. 

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. 

Kind regards,
Marcos

[1] More info about Outreachy at https://outreachy.org

Received on Monday, 10 February 2020 10:28:51 UTC