Add Symbol Clarification

[AFOliveira]

The comment and note symbol on both the Unprivileged and Privileged manual are not correctly addressed. Looking at the Unprivileged version, in this image the "commentary" is explained in the introduction like this:

Whilst this is informative, it lacks context and appears somehow randomly in the middle of the introduction. In my opinion, even worse is the “note” symbol, which appears without any context and immediately explaining something right after the last picture.

Furthermore, I propose an approach on which there is a “Typographic convention” or “Notation convention” section that exists in all the other main ISA Manuals like ARM and Intel. I believe this section should be placed right between the end of the preface and the beginning of the introduction to enhance clarity for readers.

[wmat]

I'll await feedback on this proposal from @aswaterman before proceeding, as the current formatting matches the original LaTeX spec.

[aswaterman]

IMO, the only thing that's immediately actionable is that we are inconsistent about using TIP versus NOTE. In the LaTeX spec, we only had one type of commentary section (as in, \begin{commentary}), but in the asciidoc spec, we use both, and the choice seems arbitrary. It looks like we use TIP about 60 times and NOTE about 800 times, so I guess we should replace all of the TIPs with NOTEs.

[gfavor]

Fwiw, I would agree with Andrew since there isn't a clear rhyme or reason to (or clear need for) this Tip vs. Note distinction. Whatever semantic difference for any given Tip/Note shoudl be clearly expressed in the note itself.

[kasanovic]

We could really use three different kinds of categorization of the non-normative content:
NOTE: for non-normative clarifications
TIP: to convey hints for implementers
RATIONALE: to convey design rationale and why other options were discounted
And, ideally, in web form, display of these could be made optional.

[aswaterman]

I like Krste's suggestion.

But, as a first step, I recommend we change all of the TIPs to NOTEs, since my unscientific sampling indicates we are generally using TIP where we mean NOTE. We can then recategorize NOTEs over time.

[wmat]

We'd have to add a custom admonition to get RATIONALE btw, AsciiDoc currently provides: NOTE, TIP, WARNING, IMPORTANT and CAUTION.

[gfavor]

I like Krste's suggestion. But, as a first step, I recommend we change all of the TIPs to NOTEs, since my unscientific sampling indicates we are generally using TIP where we mean NOTE. We can then recategorize NOTEs over time.

Sounds good all around. And if we are going to have people making use of more than just NOTES, then somewhere reasonably obvious there needs to be a definition or description of when each classification is appropriate to use (especially if we are also going to support and allow usage of WARNING, IMPORTANT and CAUTION). Otherwise we're bound to have very inconsistent choices being made by people between the available classifications. Also, given this, do we want to provide such a relative plethora of choices (i.e. NOTE, TIP, RATIONALE ,WARNING, IMPORTANT and CAUTION)? I'd be fine with just the first three. (WARNING sounds like a form of NOTE; CAUTION maybe sounds like a form of TIP, and IMPORTANT sounds like a form of NOTE.) Greg

[AFOliveira]

Thank you all so much for the feedback.

I definitely agree with @kasanovic that the terms "TIP" and "NOTE" can and should coexist, each with its distinct meaning. However, I believe @aswaterman's :

But, as a first step, I recommend we change all of the TIPs to NOTEs, since my unscientific sampling indicates we are generally using TIP where we mean NOTE. We can then recategorize NOTEs over time.

first approach gains even more traction when we also examine the privileged manual, Notably, the same "Introductory commentary" that appears as a "TIP" in the unprivileged manual is presented as a "NOTE" in the privileged version.

This observation further supports the idea of standardizing the terminology, at least initially, by converting all "TIP"s to "NOTE"s. This approach would bring consistency between the privileged and unprivileged manuals, while still allowing for future refinement and recategorization. Moreover, if it is decided to proceed with a review of all "TIP"s and "NOTE"s to ensure proper categorization, I would be more than happy to contribute to this effort.

Answering to @gfavor I totally agree with your opinion, I believe the description should be somewhere clear in the beggining of the manual, and I also tend to agree with the first three sounding better as you described them.

[kersten1]

Adding these details to the dev guide - https://github.com/riscv/docs-dev-guide

After we agree on typographical conventions, then we definitely need to add them to intros of main docs! I'll post in doc-sig mailing channel.