Add "List of Requirements" to sidebar

[jccr]

Description/Context

This adds a "List of Requirements" as an additional navigation section, after the table of contents.

I'm intending for this to be a (hopefully) useful tool for reviewing the editor's draft as a part of the ReSpec workflow. I developed this in response to our TPAC F2F, when we talked about extracting the MUSTs/SHOULDs into a spreadsheet, for the creation of test cases.

Details

The added nav list is populated by scraping the specification document's HTML markup.

Each list item is an occurrence of a "MUST" or "SHOULD" RFC 2119 keyword, along with some context.

List item headers link back to the respective section containing the keyword.

The item elements themselves are clickable, and scroll to the reference location in the document.

A "shortcut" button appears next to the ReSpec UI button, to allow for jumping to the list.
This also has a secondary purpose, as it signals the existence of this feature.

I marked the created elements that are added to the nav with the removeOnSave class.
This class makes ReSpec remove the marked elements for when it gets saved.
Meaning that this list and its content won't show up in the resulting specification document.
The list only shows during the time the document is viewed with ReSpec, and before it's saved.

Demo

Here's a demo on how this PR looks like when it's running live, with ReSpec in runtime:
https://jccr.github.io/pub-manifest/
Try it out with the "ReqList" button, the one next to the "ReSpec" button on the top right.

Result

If this merges into master, I anticipate that it will be available for everyone to use, when browsing through this repo's GitHub pages site.
I'm referring to the version of the draft that's linked in the readme:

This is the repository of the W3C’s specification on Publication Manifests, developed by the Publishing Working Group.
The editors’ draft of the specification can also be read directly.

---

Preview | Diff

[iherman]

I do not understand. Neither the preview nor the diff view indicates any (visible) changes...

[jccr]

@iherman This is good. I intended for my modifications to not hit the "saved" version published by ReSpec. I'll update my opening post to clarify about what I'm showing here.

Edit: Added clarifications. Hopefully this starts to make some sense now :)

[iherman]

Edit: Added clarifications. Hopefully this starts to make some sense now :)

Thanks @jccr, it does.

I think this is something very useful in general. I wonder whether it is possible to have the necessary tools separated in a, say, repository so that it could be picked up by other groups and documents, too.

[mattgarrish]

Very much like what it does, but I wonder if it might be helpful to use a parameter in the URL to enable it? (Or to turn it off.) Having it always on in the editor's draft means browsers will search that text first (and then again through the body), it will collapse into the body when the sidebar is closed, etc.

[jccr]

I think this is something very useful in general. I wonder whether it is possible to have the necessary tools separated in a, say, repository so that it could be picked up by other groups and documents, too.

Looked into this. It looks like I could package it up as a respec plugin. Will give it a shot.

but I wonder if it might be helpful to use a parameter in the URL to enable it? (Or to turn it off.)

I agree. That button I have, it used to be more complicated. The list wouldn't exist until you clicked it first.

it will collapse into the body when the sidebar is closed, etc.

Just noticed this. I see how it could be a problem if it's collapsed into the body text.

[mattgarrish]

That button I have, it used to be more complicated. The list wouldn't exist until you clicked it first.

That actually sounds like an ideal solution.

[jccr]

@iherman

I think this is something very useful in general. I wonder whether it is possible to have the necessary tools separated in a, say, repository so that it could be picked up by other groups and documents, too.

Ideally, in the end, this is added as a core feature of ReSpec. ;)

Stepping back from that though, I looked into the plugin situation.
There are ReSpec profiles (we use the w3c-common profile), that runs everything to do with ReSpec on the spec doc. The profile is a script that waits for the doc to load, initializes the core runner, and loads all plugins. The profile also declares which plugins and other scripts to include. This is a problem. If I want to include this as a plugin, we need to extend the profile, fork it, reference that in our spec instead of the w3c profile.

What I want my solution to be is an external plugin, one that we include and declare outside of the profile, and can opt-in through the ReSpec config object.
ReSpec has an issue for this, but it hasn't been completed yet: https://github.com/w3c/respec/issues/1976

Here are my options:

1. Incubate and include it in our repo here for now. Host it in this repo and for this spec. This is the current state.
2. Make a repo for this, to host (and publish through github?) the JS scripts with ReSpec specific functions and other css files for the little bit of UI. Intended to be included with and added to another spec's ReSpec config. With the provided repo's functions in the preProcess and postProcess arrays.
3. Fork ReSpec with a new profile that extends the w3c profile. Include this feature as a plugin in the forked repo. Use the forked profile in our spec, instead of the w3c profile.
4. Implement something of the above into our spec. Wait and refactor when w3c/respec#1976 is fixed.

[iherman]

My favorite would be your option (2) while this document could play guinea pig:-)

[jccr]

@iherman @mattgarrish
I've addressed your feedback.

Ivan, I went with option 2.
Here's the repo with the scripts: https://github.com/jccr/reqlist/
This PR is now just links and integrates with it.

Matt, the button now does what we talked about. The list doesn't exist until you interact with it.

[iherman]

I am fine merging this; @mattgarrish ?