Fwd: facilitating requirement cross references in the ucr document

Simon, all,

this is the mail I sent to the editors of the other UCR document. I hope it is understandable and can be helpful…

Ivan

> Begin forwarded message:
> 
> From: Ivan Herman <ivan@w3.org>
> Subject: facilitating requirement cross references in the ucr document
> Date: 3 June 2016 at 13:21:16 GMT+2
> To: Romain Deltour <rdeltour@gmail.com>, Heather Flanagan <rse@rfc-editor.org>, Dave Cramer <dave.cramer@hbgusa.com>
> Cc: Tzviya Siegman <tsiegman@wiley.com>
> Message-Id: <59A3ECBC-C5AE-4675-993B-ACE5ACDA8BD5@w3.org>
> 
> Heather, Romain, Dave
> 
> I have experimented with a script to generate cross references to use cases easily. I have put the results into the repo under a separate branch: 'req-test', and the result is at:
> 
>  https://rawgit.com/w3c/dpub-pwp-ucr/req-test/index.html <https://rawgit.com/w3c/dpub-pwp-ucr/req-test/index.html>
> 
> Be careful if you merge this with the main branch, I have added some tests into the text itself which has to be edited/changed (search for 'Ivan's experimentation!!!'). The idea is as follows:
> 
> 1. For each use case, there should be a separate list of requirements, each with a short mnemonic. The format should be something like:
> 
>  <p>Requirement (Ivan's experimentation!!!): <a data-set-anchor>Many Resources</a></p>
> 
> The only thing that counts is the <a> element. Note that the <a>XYZ</a> idiom is a respec facility[1], the only thing I added is the extra attribute. Note, however, that it does not really work with the "data-lt" attribute (see [1]); I am happy to look into it if you need it.
> 
> 2. There is a separate section on listing and detailing the requirements. In the experimentation it looks like:
> 
>  <dt><dfn>Many Resources</dfn></dt>
>  <dd>Some bla bla on the requirement
>  <p>Referenced in: <span data-ref-anchor>Many Resources</span></p>
> 
> The 'dfn' is the counterpart of the link, as in[1]; the effect is that the <a> above will link to that one. That is a respec feature. The extra is the <span data-ref-anchor>...</span> (whether it is a span or something else is not important). The script will exchange the content of the span for a list of references to the immediate section element(s) where the corresponding <a data-set-anchor> are. The references will include the section numbers and the section titles. (I make use of another respec feature[2] that generates those automatically)
> 
> 3. I have also added an extra facility that lists all the requirements in one table: each row is a reference to the requirement definition and a list of the corresponding use cases; you can look at the code at the very end to see the pattern.
> 
> Beyond the editing, the things that have to be added to the file is:
> 
>  <script src='reverse-index.js' class='remove'></script>
> 
> with an extra
> 
>  preProcess: [rev_index],
> 
> into the respec configuration
> 
> Please, tell me if this works for you, and if you want me to change something.
> 
> Note that (2) above is not really DRY; you have to set the requirement mnemonic twice. If you have a fixed, regular structure that you want to use, I can probably generate that automatically, but I tried to stay reasonably general, because this tool may be reusable elsewhere. (And it can probably be generalized, but I wanted to get something out quickly.)
> 
> Does this help?
> 
> Ivan
> 
> 
> [1] https://www.w3.org/respec/guide.html#definitions-and-linking <https://www.w3.org/respec/guide.html#definitions-and-linking>
> [2] https://www.w3.org/respec/guide.html#sections-1 <https://www.w3.org/respec/guide.html#sections-1>
> 
> ----
> Ivan Herman, W3C
> Digital Publishing Lead
> Home: http://www.w3.org/People/Ivan/ <http://www.w3.org/People/Ivan/>
> mobile: +31-641044153
> ORCID ID: http://orcid.org/0000-0003-0782-2704 <http://orcid.org/0000-0003-0782-2704>
> 
> 
> 
> 


----
Ivan Herman, W3C
Digital Publishing Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
ORCID ID: http://orcid.org/0000-0003-0782-2704