I was going to suggest to use uppercase only for header-like directives, excluding thereby ".. math::" in particular.
but as Travis expressed, it would be confusing to change a long-held tradition, unless there is unanimous agreement. So I will stop here. Thanks for the info and opinions. On Sunday, February 4, 2024 at 1:24:17 PM UTC+9 Travis Scrimshaw wrote: > I think it is more confusing to mix the two. I vote for keeping everything > all uppercase since everything else that is analogous uses all uppercase > letters. > > Best, > Travis > > On Wednesday, January 31, 2024 at 9:20:58 PM UTC+9 TB wrote: > >> On 25/01/2024 7:06, Kwankyu Lee wrote: >> >> Hi, >> >> Our developer guide dictates to write Sphinx directives in upper case. So >> for example, ".. MATH::" instead of ".. math::". By the way, it seems that >> Sphinx community seems to regard lower case as norm. So my question is: why >> do we insist upper case? Could anyone point to a discussion thread that >> decided on this? >> >> More than 13 years ago we have >> https://github.com/sagemath/sage/issues/10077 and >> https://github.com/sagemath/sage/issues/10078 that have comments about >> the case. Some further history might stem from stropping >> <https://en.wikipedia.org/wiki/Stropping_(syntax)>... For those looking >> in the docs, one place is here >> <https://doc.sagemath.org/html/en/developer/coding_basics.html#sage-documentation-style> >> . >> >> >> On 25/01/2024 10:18, Kwankyu Lee wrote: >> >> In my humble opinion, except >> >> ".. SEEALSO::", "..WARNING::", ".. TODO::", ".. NOTE::", ".. RUBRIC::", ".. >> PLOT::", "..TOPIC::", which seek for reader's attention, >> >> we should use lower case (by default) for all other directives, following >> Sphinx community's trend. In particular, ".. MATH::" is only distracting. >> >> No strong opinion from me, except maybe for having consistency within a >> given file. The INPUT and OUTPUT blocks are related, but they are not >> directives. Do you think they should be? >> >> >> Regards, >> >> TB >> >> -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/3cbb6eb4-df23-4a2f-b690-63cde8f54d0en%40googlegroups.com.
