Skip to content
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 big O notation to the style guide #1261

Merged
merged 3 commits into from
Jan 14, 2024

Conversation

hugovk
Copy link
Member

@hugovk hugovk commented Jan 10, 2024

Following python/cpython#113695, document how to add big O notation.

image


📚 Documentation preview 📚: https://cpython-devguide--1261.org.readthedocs.build/documentation/style-guide/#big-o-notation

Copy link
Member

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case a regular reST table (compact form) would probably be more readable then a list table (and save a few lines).

Somewhat unrelated, but I was wondering whether using (and recommending) ² instead of :sup:`2` would be better, especially since the latter tends to become a regular 2 once copy-pasted.

@hugovk
Copy link
Member Author

hugovk commented Jan 10, 2024

Somewhat unrelated, but I was wondering whether using (and recommending) ² instead of :sup:`2` would be better, especially since the latter tends to become a regular 2 once copy-pasted.

Hmm, could be. We'd need to check epub/PDF/accessibility etc.

@doerwalter
Copy link
Contributor

This feels wrong to me: The "O" isn't an emphasized "O". This is a mathematical formula, so IMHO the :math: role should be used:

:math:`O(1)`
:math:`O(\log n)`
:math:`O(n)`
:math:`O(n \log n)`
:math:`O(n^2)`

This should work in both the PDF/TeX and the HTML output.

@hugovk
Copy link
Member Author

hugovk commented Jan 11, 2024

:math: renders as O(n\log{n}) in plain text and \(O\log{n}\) in EPUB:

python/cpython#113724 (comment)

@ezio-melotti
Copy link
Member

Hmm, could be. We'd need to check epub/PDF/accessibility etc.

I did some research but I didn't find anything too conclusive.

MDN says:

Appropriate use cases for <sup> include (but aren't necessarily limited to):

  • Displaying exponents, such as "x3". It may be worth considering the use of MathML for these, especially in more complex cases. See Exponents under Examples below.

Wikipedia says:

The intended use when these characters were added to Unicode was to produce true superscripts and subscripts so that chemical and algebraic formulas could be written without markup.

and links to a Unicode document.

Some screen readers seem to have options to handle <sup>. Both <sup> and Unicode superscript chars seem valid choices, so unless someone finds something more conclusive, I'd say to just stick with :sup:/<sup>.

@hugovk
Copy link
Member Author

hugovk commented Jan 12, 2024

https://stackoverflow.com/a/12224471/724176 says to use the Unicode version where available instead of <sup>.

Similarly https://stackoverflow.com/a/76931597/724176 says ² is better for accessibility and mentions some screen readers that have problems with <sup>.

It also links to https://adrianroselli.com/2022/09/brief-note-on-super-and-subscript-text.html by an a11y expert, showing problems some screen readers have with <sup>.

@hugovk
Copy link
Member Author

hugovk commented Jan 14, 2024

Let's merge this, it reflects what we're using now.

If we update the docs to Unicode ² instead of sup (and I'm not opposed, seem like an improvement), then we can update the devguide to match too.

@hugovk hugovk merged commit d4552d0 into python:main Jan 14, 2024
4 checks passed
@hugovk hugovk deleted the add-big-O-to-style-guide branch January 14, 2024 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants