-
Notifications
You must be signed in to change notification settings - Fork 53
docs: format RFC 2119 keywords #872
New issue
Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? # to your account
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.