Rephrase displayMode description to be clearer

[tabatkins]

Previously was of the form "whether should be A or B (default C)", which didn't make sense. Rewritten to properly refer to the bool and map it's effects clearly.

[khanbot]

CLA signature looks good 👍

[gagern]

👎

I find the original formulation clearer. The option configures the default for a formula. You can set displayMode to false but use \displaystyle in part of your formula, and conversely with \textstyle. So the setting controls the default, as indicated. And the (default false) tells me that the default for this boolean value is false: not specifying the option is the same as specifying it with the value false. That information is absent from your reformulation. Furthermore, your formulation introduces “the typesetter” as a concept which might take some readers a bit till they identify what you are talking about. It doesn't matter who is doing what; what matters is the style of the result.

[tabatkins]

Yes, I get what it does. The point of my rephrasing is that "true" or "false" is neither "display" nor "text", and there's no natural mapping between the two. The current wording assumes you can intuit that displayMode = False means "default to textstyle", which I don't think is a reasonable assumption.

I'm not attached to the exact wording at all, I just wanted to make it clear what True and False each do. Suggested alternative text is welcome.

[kevinbarabash]

Isn't displayMode: true equivalent to prepending the input with \displaystyle?

[gagern]

Isn't displayMode: true equivalent to prepending the input with \displaystyle?

No, it also adds some outer styling.

[edemaine]

I find it odd that the documentation doesn't mention the outer styling. How about rephrasing as follows?

Whether the expression should be typeset inline (false, the default), meaning that the math starts in \textstyle and is placed in an inline-block); or display (true), meaning that the math starts in \displaystyle and is placed in a block with vertical margin.

[tabatkins]

I can't comment on the technical aspects, but that definitely satisfies my original "make it clear what True and False actually map to" goal.

[edemaine]

Cool, yeah, that was one of my additional goals. 😄

[gagern]

I like your formulation, @edemaine. Minor nit: as “expression should be typeset display” doesn't sound like correct English to me, I'd make that “in display mode”. You can use “inline mode” to keep things symmetric. You can also try other formulations like “as a displayed equation” or something like that.

[edemaine]

How about this for correct English? I believe $...$ and $$...$$ are normally referred to as inline math and display math, which is what we want to parallel here. "Mode" might also be a fine replacement, if that's more standard?

Whether the expression should be typeset as inline math (false, the default), meaning that the math starts in \textstyle and is placed in an inline-block); or as display math (true), meaning that the math starts in \displaystyle and is placed in a block with vertical margin.

@tabatkins Do you want to modify your PR accordingly, and then @gagern or I can merge?

[tabatkins]

All right, wording updated and checks passed. Ready for merge!

[xymostech]

Vague nit: the block that it's placed in is more to do horizontal centering, not to add vertical margins, right?

[edemaine]

@xymostech What if we added "centered" before "block with vertical margin"? The outer styling sets both. I'd also be fine with just "centered block" -- I agree that is the primary point of display math.