Re: Status of v1.12 privileged specification
toggle quoted message Show quoted text
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.
>>>>> 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.