[ReSpec]: New features and fixes! 🎁

• From: Sid Vishnoi <sidvishnoi8@gmail.com>
• Date: Tue, 21 Jul 2020 12:43:43 +0530
• To: spec-prod <spec-prod@w3.org>
• Message-ID: <CAKJqC-TVKdMK=SHrpdEJMKgyKEFbPPB5ABHgNTpu0ep6pnwL6g@mail.gmail.com>

Hello all,

As we mentioned in our previous email, I was granted a Mozilla Open
Source Support Award which funded some additional development of
ReSpec over the last 3 months. As the grant period comes to an end,
I’d like to share some of the developments.

tl;dr:

- Single-page documentation is back! Visit https://respec.org/docs/
- Added <section id="index"> — generates an index of definitions and
referenced terms!
- Support for “data-dfn-for=”  to define object-property conceptual
relationships (e.g., [=list/for each=])
- Dynamically getting W3C Group info from W3C API via the “group”
config option (e.g., "group": "webapps")
- Lots of bug fixes, enhancements, and features!

## Revamped Documentation

You can access the brand-new single-page documentation at
https://respec.org/docs/.

The single-page view means it’s easy to Ctrl+F to search for what you
are looking for, just like any spec. The table of contents provides a
quick overview of the configuration options, examples, and other
guides at a glance!

With the new single-page view, the documentation is now better
structured. It's been revamped and updated to remove deprecated
features, and we've documented new features and added
cross-references.

Best of all, the documentation is generated directly from ReSpec’s
wiki: https://github.com/w3c/respec/wiki

One can now edit the wiki and the changes automatically appear in the
docs. The documentation also contains links to edit specific wiki
pages.

## Index of Definitions

You can now do away with your spec’s “Dependencies” section! Adding a
`<section id="index"></section>` generates an in-place index of terms
defined by the current document, as well as an index of terms
referenced from other specifications.

Clicking on a term in “Terms defined by this specification” index
takes you to its definition, and clicking on a term in “Terms defined
by reference” index opens a panel showing the usage of definition in
the current document. It's handy to have all definitions in a single
place!

You can explore a live example in the Page Visibility API
Specification - https://w3c.github.io/page-visibility/#index.

## Contextual concept definitions

Respec now allows you to define that a particular concept is “for”, or
strongly related to, another concept - and also as a way of
disambiguating two terms. For example, we can define that a “document
is visible” and a “window is visible” like so:

    <dfn data-dfn-for="Document">visible</dfn>
    <dfn data-dfn-for="Window">visible</dfn>

And then we can talk about each uniquely like so: The [=document=] is
[=Document/visible=] and the [=window=] is also [=Window/visible=].

Read more at: https://respec.org/docs/#data-link-for

## `group` configuration option

With a new configuration option — “group”, you can specify a “short
name” for the WG/CG and let ReSpec figure out the details for you. The
wg, wgId, wgURI, and wgPatentURI options are deprecated in favour of
“group”.

Read more at https://respec.org/docs/#group.

## New features and enhancements

The following are some of the notable improvements in ReSpec:

- Definitions panels now also work in static exported documents.
- A new configuration option — “modificationDate”, adds an in-place
edit date of an already published document [1].
- Exported definitions have an "exported" label in the definition
panel, making them easier to spot and use!
- A new linter rule — “no-unused-vars”, warns you if you declare and
variable and not use it [2].
- A new attribute — “data-max-toc”, lets you control Table of Content
depth per section [3].
- Markdown code snippets can be treated as examples [4].
- Improved markdown `data-include=` support.
- Reduced payload size by 10KB to ~80KB with Brotli compression [5].

A more detailed changelog is also available:
https://github.com/w3c/respec/blob/9ea3388/CHANGELOG.md

[1]: https://respec.org/docs/#modificationDate
[2]: https://respec.org/docs/#no-unused-vars
[3]: https://respec.org/docs/#data-max-toc
[4]: https://respec.org/docs/#code-blocks
[5]: https://respec.org/dashboard/

## What's next?

Marcos and Saschanaz have been doing lots of code reviews, and they
surely missed writing code for ReSpec. So, both Marcos and Saschanaz
will make a comeback as core maintainers once the grant period ends on
July 24th. I will continue to contribute in my spare time again.

More concretely, we have some things planned in a Kanban board at
https://github.com/w3c/respec/projects/4.

## Support ReSpec

If you and member company would like to continue to support the
development of ReSpec, we'd like to encourage you to donate to our
open-source collective - any little bit helps:
https://opencollective.com/respec

We would like to express our gratitude to Xiaoqian Wu (siusin) and
Fuqiao Xue (xfq) for their contributions of $50 each. Special thanks
to Jory Burson for her continued monthly support! We would also like
to thank others who have contributed in the past 😇. You all rock!

You can also help ReSpec by filing issues for any bugs you come
across, and enhancements you would like to have. That’s more work for
us, but creating a good product is a life goal™️.

Kind Regards,
Sid Vishnoi
https://twitter.com/sid_vishnoi

Received on Tuesday, 21 July 2020 07:14:13 UTC