-
Notifications
You must be signed in to change notification settings - Fork 639
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Symbol Clarification #1547
Comments
I'll await feedback on this proposal from @aswaterman before proceeding, as the current formatting matches the original LaTeX spec. |
IMO, the only thing that's immediately actionable is that we are inconsistent about using |
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. |
We could really use three different kinds of categorization of the non-normative content: |
I like Krste's suggestion. But, as a first step, I recommend we change all of the |
We'd have to add a custom admonition to get RATIONALE btw, AsciiDoc currently provides: NOTE, TIP, WARNING, IMPORTANT and CAUTION. |
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
|
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 :
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. |
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. |
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.
The text was updated successfully, but these errors were encountered: