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

ocamldoc: improve printing of subscript/superscript in 'man' format #1710

Merged
merged 1 commit into from Apr 11, 2018

Conversation

Projects
None yet
2 participants
@gasche
Copy link
Member

gasche commented Apr 9, 2018

On a standard OCaml install, man Nativeint shows the following
sentence in its first paragraph:

All arithmetic operations over nativeint are taken
modulo 2^{32 or 2^{64 depending on the word size of the architecture.

The 2^{32 is a rendering bug. This PR removes the unbalanced curvy
bracket, so it prints 2^32 and 2^64 instead.

In theory just printing ^ and _ risks creating ambiguities for
multi-words superscripts or subscripts: "2^foo bar" could be either
"2^{foo bar}" or "2^{foo} bar". In practice, the ocamldoc text in the
standard library only uses the superscript for bit sizes.

Even for arbitrary user documentation comments, "^{" or "^" have the
same property of not being explicit about where the superscript ends,
so this would not be a regression even on multi-word superscripts.

ocamldoc: improve printing of subscript/superscript in 'man' format
On a standard OCaml install, `man Nativeint` shows the following
sentence in its first paragraph:

    All arithmetic operations over nativeint are taken
    modulo 2^{32 or 2^{64 depending on the word size of the architecture.

The `2^{32` is a rendering bug. This PR removes the unbalanced curvy
bracket, so it prints 2^32 and 2^64 instead.

In theory just printing ^ and _ risks creating ambiguities for
multi-words superscripts or subscripts: "2^foo bar" could be either
"2^{foo bar}" or "2^{foo} bar". In practice, the ocamldoc text in the
standard library only uses the superscript for bit sizes.

Even for arbitrary user documentation comments, "^{" or "^" have the
same property of not being explicit about where the superscript ends,
so this would not be a regression even on multi-word superscripts.
@Octachron
Copy link
Contributor

Octachron left a comment

I imagine that you deemed the alternative fix 2^{x} too ugly? Anyway, I agree that using just a^b is probably good enough for man pages, since it is generally more readable to use exp for multi-word exponents in inline equations.

@gasche gasche merged commit 57f086e into ocaml:trunk Apr 11, 2018

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.