Autonumbered and referenceable requirements

[hylkevds]

Currently the references in the template are not auto-numbered, and can not be auto-referenced. This makes the editing process very tedious and error prone.

A referenceable number can be generated with: [[reqnr-thing-properties,{counter:req}]] A referenceable name can be generated with: [[reqname-thing-properties,http://www.opengis.net/spec/iot_tasking/1.0/req/thing/properties]]

Then you can reference the number by using: <<reqnr-thing-properties>> And the complete requirement id using: <<reqname-thing-properties>>

This way you can use an understandable requirement name in the text (thing-properties in this example) instead of a number that might change. It's also easy to spot incorrect references, since they will not resolve. And you can click the references to jump to the requirement.

Moreover, once the requirements are defined with references, it's trivial to generate a table-of-requirements.

The only limitation of asciidoctor is that only once anchor can be defined at a time, so I tend to anchor the number to the word "Requirement" in the table, and the name to the requirement itself.

i.e.:

[cols="25a,75a"]
|===
|Requirement[[reqnr-thing-relations,{counter:req}]]
|
[[reqname-thing-relations,http://www.opengis.net/spec/iot_tasking/1.0/req/thing/relations]]
<<reqname-thing-relations>>

__Each `Thing` entity SHALL have ...__
|===

As an example I've used it in: https://github.com/hylkevds/sensorthings/tree/17-079/src/17-079

Generated pdf, with table of requirements: https://hylkevds.github.io/sensorthings/17-079/17-079.pdf

Script that generated the Table of Figures and Table of Requirements: https://github.com/hylkevds/sensorthings/blob/17-079/src/generate_tof.rb

[ogcscotts]

@hylkevds Thanks for the effort on this. The reason we did not autonumber requirements in the template is because we have an OGC Policy Directive that requires sequentially numbered requirements, but that those numbers be fixed to the requirement and if a requirement is deleted, the numbers do not reset, rather they are retained. If we could have an autonumber that allows for deletion of an entry (or insertion of a number out of sequence if a requirement is added), then that would be great. Please see Directive 43: https://portal.opengeospatial.org/public_ogc/directives/directives.php

[hylkevds]

That could be done by either

• removing the requirement, but leaving the counter-incrementing command
• removing the requirement, and hard-setting the counter index on the next requirement

Inserting a new requirement in between old requirements, resulting in a requirement sequence of something like 1, 2, 53, 3, 4, would be achieved by using a new counter for the new requirements, that is initialised on the number of the last old-requirements.

To start a new sequence, called req2, starting at 53, use {counter:req2:53}

The good thing is, that when referencing requirements, you don't need to know if it's in the old sequence, or the new sequence. You always reference by name.

edit: Since the counters and the references are separate concepts in asciidoc, it is even possible to, in the final release stage, replace the auto-counters with fixed numbers. i.e. change

|Requirement[[reqnr-thing-relations,{counter:req}]]
...
|Requirement[[reqnr-thing-relations,{counter:req}]]
...
|Requirement[[reqnr-thing-relations,{counter:req}]]

to

|Requirement[[reqnr-thing-relations,1]]
...
|Requirement[[reqnr-thing-relations,2]]
...
|Requirement[[reqnr-thing-relations,3]]

Preferably using a script of course. This will leave the referencing in tact, and fixate the requirements' numbers. That would give the advantage of automatic numbering when moving requirements around during the edit process, but still give fixed numbers in the final document.

[ogcscotts]

Makes sense. Also makes me think that it would be good to leave the old counter incrementing in the document and have some very short comment in the text where a requirement was removed to state so. For instance: "Requirement 2 removed in version 1.1." I'll look at updating the template and template instructions.