1. Tech-Privileged
  2. Messages

Re: Status of v1.12 privileged specification

Greg Chadwick
 

> Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Depending on how much we rely on the git repository being the source of truth you could reference the git commit SHA-1 that was used to generate the PDF along with the more human readable document version (e.g. only include the SHA1 in a footnote or a references section).

So for say the 'misa' section of the current latest ratified privileged spec (this one https://github.com/riscv/riscv-isa-manual/releases/download/Priv-v1.12/riscv-privileged-20211203.pdf)  you would say something like

Section 3.1.1 'Machine ISA Register misa' of The RISC-V Instruction Set Manual Volume II: Privileged Architecture version 20211203 SHA 9896426

Obviously you would need a shorthand for that lot.


On Wed, Jul 27, 2022 at 5:47 PM Allen Baum <allen.baum@...> wrote:
Just to point out that I was pointing out only one specific example of a document (where I recently encountered this) that used section numbering references.
It's not the only one, it's all over.   This isn't just "if it hurts when you do that, don't do that" after the fact kind of advice that is required; we need a stronger statement somewhere that clearly says that external references to the spec must not use just section numbers because they will change.

Andrew's suggestion is a good one - but it needs to be communicated.

A slightly different issue is that these documents that this may not take into account references to extensions that have been ratified but have not been updated in the most up-to-date ratified spec yet but are in the draft). 
Maybe that problem will go away when it's all in asciidoc and updates can be made more timely.





On Tue, Jul 26, 2022 at 11:46 PM <krste@...> wrote:

There will be an annual release of all the specs, which can be
reference as Andrew says.

But, use the extension name as a key.  If the extension doesn't have a
name, we'll give it a name.

Krste

>>>>> On Tue, 26 Jul 2022 23:14:42 -0700, "Greg Favor" <gfavor@...> said:

| On Tue, Jul 26, 2022 at 10:50 PM Allen Baum <allen.baum@...> wrote:
|     So " In general every new extension will be a separate new chapter."
|     But of course, but.... will they always be added to the end of the spec, or could they be inserted into the middle?
|     The latter will, cause renumbering of chapters, and many, many references to those sections to become obsolete
|     in docs all over the ecosystem. 

|     I'm reviewing the RISC-V certification test questions, and authors must point to references for their answers.
|     If sections change numbers, then a lot of those test questions will need to be rewritten. 
|      I'm sure that won't be the only place, and tracking them all down will be a pain.

| Using chapter numbers instead of chapter titles for cross-reference purposes seems quite brittle (as you're pointing out) and undesirable.  And that constancy of all chapter (and
| section numbers) going from the 2019 Unpriv and Priv specs to the 2021 specs has already been broken.

| If it was me, I would say that the certification test questions should use chapter (and section) titles (and avoid chapter/section numbers).  Otherwise one way or another I would
| bet that their spec cross-references aren't going to survive 100% over the next 5-10 years.

| Greg
Join tech-privileged@lists.riscv.org to automatically receive all group messages.