-
Notifications
You must be signed in to change notification settings - Fork 50
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
docs: format RFC 2119 keywords #872
base: main
Are you sure you want to change the base?
Conversation
4b7a88c
to
93bf898
Compare
I noticed that gh-801 tries doing the same thing. Could you compare and recommend which approach to use? |
Ah, indeed. gh-801 looks more polished of course. Can't see what the rendered docs look like since the link has expired and CircleCI needs a kick from somebody with the right permissions (does not seem to react to my prods). Assuming the rendered docs in gh-801 are what we want them to be, the choice boils down to whether we prefer to maintain a dedicated Sphinx extension (gh-801) or run My personal preference would be for the latter, but I'm not the main writer here. |
IMO, the approach in this PR is preferred when compared to #801. The main issue which I raised there is that changes should actually be constrained to normative content. At least to start, I recommend only modifying the use of |
OK, reverted all changes to |
$ sed -E -i "/not/! s/must/\*must\*/g" ./*.rst $ sed -E -i "s/must not/\*must not\*/g" ./*.rst $ sed -E -i "/not/! s/should/\*should\*/g" ./*.rst etc
9c95dfb
to
699a1d6
Compare
aims to address #397, #796
typeset RFC 2119 magic keywords (should/must/must not) in lowercase italics; the preference in gh-397 seems to avoid ALLCAPS.
No specific preference for italics either, can change to boldface---did not do it just yet because boldface is already in use in phrases like
The full **singular value decomposition** of an :math:
m \times nmatrix ...
Either way, if there's a strong preference for boldface or other, it's easy to change, just slightly tweak the
sed
stanzas under the fold.Note that I only spot-checked the diff, so it's possible that the search-and-replace changed too much.