Flexibility of math syntax about remark-math

[vhf]

Actually I misunderstood my users needs, it's not kramdown because kramdown has no way to display math in middle of paragraph.

I'll work on adding that option if that's ok for you. Current behaviour is : $ and $$ inline. $$ on its own line makes a block. So $$'s behaviour depends on where it's placed. What I'll do is that it doesn't depend on the context:

• $ inline
• $$ inline puts formula on its own line but still inside the same inline paragraph
• $$ not inline acts the same as above: it's wrapped in a paragraph, it's just that there's nothing but the formula in the paragraph.

With this behaviour, $$ always puts formula on its own line. If it's already in a paragraph, it doesn't break it. If it's not, it gets wrapped in one.

---

The following would be achieved by using $ for the 1st formula, $$ on its own line for the 2nd, $$ inline for the 3rd:

[Rokt33r]

Hmm... The syntax looks fine. But, putting block-level elements into a paragraph seems to be quite harmful.

HTML forbid it explicitly, although it looks fine semantically.

The P element represents a paragraph. It cannot contain block-level elements (including P itself).
https://www.w3.org/TR/html401/struct/text.html#h-9.3.1

As long as we render Markdown into HTML, we shouldn't wrap it in a paragraph. Also, Paragraph 3 should be split into 2 paragraphs and one displayMath.

[vhf]

Hmm... The syntax looks fine. But, putting block-level elements into a paragraph seems to be quite harmful.

Yes, I'm not advocating putting a block element inside a paragraph. In the above example, I'd see Paragraph 3 like : <p>Foo … <br><span class="math">…</span><br> … bar.</p>.

(P1 would be as it is now, and P2 would be what $$\nformula\n$$ currently does)

As long as we render Markdown into HTML, we shouldn't wrap it in a paragraph. Also, Paragraph 3 should be split into 2 paragraphs and one displayMath.

That's what I'd like to avoid. A long formula or equation inside a paragraph is fine, but it's hard to read if we cannot put it centered on its own line. :)

[Rokt33r]

Oh,,... I see. This seems to be just an aesthetic issue. So, the math in P3 is just another inlineMath although it looks like a block.

Here is my suggestion:

1. Fork remark-math instead of creating a new PR because this feature is quite peculiar.
   If there are many people want this, we could merge it later. 😄
2. Define displayMath node type.
   It is almost ready to go. Just split this conditional expression and define it!
   https://github.com/Rokt33r/remark-math/blob/master/packages/remark-math/inline.js#L11
3. Fork and extend remark-html-katex or rehype-katex to render displayMath.

[vhf]

Ok, thanks @Rokt33r .

Since I'd like to avoid maintaining a fork (and having to replicate the good work you're doing here in my fork), let me suggest an easy solution: we add another class to the inlineMath spans when the syntax is $$.

This way I can simply fix my issue with CSS, something like: p > .inlineMath.inlineMathDouble { display: block; }.

What do you think?

[geyang]

@Rokt33r @vhf This problem has came up before. Here is my summary:

1. Use span.displayMath for the display math blocks inside paragraphs. Semantically this is crucial. This is supported by math-jax -- use of span tag for display math is enabled by default.

2. In html contenteditable, node.style.display=block will cause containing block elements to break apart in some browsers. Namely some browser enforce the no-block inside <p> rule even for presentation attributes.

3. To mitigate this problem, it is common to treat the paragraph as a semantic one, and use div.paragraph as the actual html element. The saying is that

   The html <p> tag is broken. Don't use it.

[geyang]

In my app I am not affected by the compiling step b/c I am using my own react renderer. However, I am affected by the semantic correctness of the parsing.

[geyang]

I looked at the PR, and noticed that you are calling it inlineDouble.

In LaTeX all display math and inline-blocks. A display math block never exist standalone, and it is assumed that it is always wrapped by a paragraph. The display:block aspect of the displayMath from math-jax is a pure html concept and it diverges from those of the LaTeX layout algorithm.

We shouldn't call it inlineDouble. We should just call it displayMath, and always wrap a paragraph around displayMath.

I am very impressed by the current treatment of parsing the math deliminaters. @cben has done a stellar job of summarizing the different markdown syntax for LaTeX, and @vhf has done a great job writing the parser. Thank you for your work!

My main motivation is to help create a "correct" markdown math parser. Most of the math parsers are not implemented correctly.

[vhf]

@episodeyang thanks, I'm all in favour of getting the semantics right.

Could you please clarify, for each of the following examples, how you think they should be named and what you think an ideal HTML markup would be?

1 Foo $\alpha$ bar.

---

2 Foo $$\alpha$$ bar.

---

3 Foo.

$$\alpha$$

Bar.

---

4 Foo.

$$
\alpha
$$

Bar.

Here is what it currently does, with ps highlighted in lightgreen and divs highlighted in lightblue.

(Are you using mathjax or did you mean KaTeX?)

[geyang]

@vhf absolutely! Thanks for your reply. I will check the ast in my next reply since there might be some subtleties with the AST that doesn't show in the html.

It is getting late in Chicago (4AM), so I will come back to this tomorrow :P Again thanks for this great work!

ps: I'm tend to oscillate back and forth between KaTeX and math-jax. KaTeX is more mature now but I haven't used it for two years. For math-jax I have some hacky code for the equation numbers, but references is still a pain. This is also why some form of understanding of the LaTeX is necessary.

[geyang]

I took a look at the output:

• I think 3 and 4 should be treated the same way for the following reasons

As long as you enter display math mode, line-return and non-white space characters right after the $$ should be treated as a single line. For example:

A paragraph $$ \alpha + \beta $$

{ type: "paragraph", children: [ {type: text...}, {type: displayMath, value...} ] }

In addition, when a stand-alone math block appears, it should be automatically wrapped with a paragraph component. Similarly, if it is inside a blockquote, it should be wrapped with blockquote without first being wrapped by a paragraph. We should treat displayMath (as well as inline math) as inline-block nodes that can only appear inside block nodes, and otherwise would be auto-wrapped with one.

[vhf]

I agree and disagree at the same time. Let me explain.

There are two main math environment in Latex (some explanation):

1. $$ ... $$
2. \[ ... \] (same as \begin{displaymath} ... \end{displaymath}

Now I totally agree the following two would produce the exact same thing in LaTeX:

$$
a
$$

$$a$$

The reason why we have a distinction in remark-math for this is that the syntax for 2. \[ ... \] (same as \begin{displaymath} ... \end{displaymath} is too heavy. What we went with is therefore the following:

1. md $$ ... $$ gives equivalent to tex $$ ... $$
2. md $$\n...\n$$ gives equivalent to tex \[ ... \] (same as \begin{displaymath} ... \end{displaymath}

[geyang]

That make sense. Most users doesn't use the \[ \] syntax in my experience, and collaborators usually get mad if you change $$ to \[. 😂

However I think the design choice should be done with a certain depth to it. What I mean by this is that for people who are familiar with \[ and \(, they are going to expect a multi-line $$\n newline\n$$ to behave the same way as a single line $$math$$.

So I think you are right, we should definitely have two different type for \[<...>\] and $$(\n)[^!\s]* delimiters b/c in LaTeX they are treated differently.

However the $$\n == \[ syntax is doing something expected for rookie users as well as users who use \[ exclusively.

[vhf]

Yep, we're already in macro-land, but this package focuses on math. I have no idea which other latex environments KaTeX supports?

Back to $$ vs \[, I understand your concern but I'm not sure it'd be worth changing the syntax we currently use. Perhaps giving examples of the markdown syntax you'd like to use for both of these math environment would help?

[geyang]

Sorry about the digression. I will move that to a different thread.

Here are what I suggest as the syntax: There will be only one type of displayMath. The delimiters are saved in the delimiter data key for the math block

A paragraph $$ \alpha + \beta $$	{ type: "paragraph", children: [ {type: text...}, {type: displayMath, delimiters: ["$$", "$$"], value...} ] }
A paragraph \[ \alpha + \beta \]	{ type: "paragraph", children: [ {type: text...}, {type: displayMath, delimiters: ["\[", "\]"], value...} ] }
A paragraph \begin{equations*} \alpha + \beta \begin{equations*}	{ type: "paragraph", children: [ {type: text...}, { type: displayMath, delimiters: ["\begin{equations*}", "\end{equations*}"], value... } ] }

[vhf]

I like these suggestions except for the node types. They should be different, at the very least to be able to add different classes to them.

The way we currently use \[, we generate a div to get the math outside of a paragraph. We could also have it in a paragraph instead, that's not an issue, but we need to get somewhat close to what \[ does in latex when it's at the beginning of a paragraph, i.e. add \nointerlineskip.

Having different node types makes it easier to add different classes to HTML elements to then be able to style them separately (particularly vertical margins).

[geyang]

@vhf I see, so you are mostly concerned about how to handle the presentation styling.

To emulate \nointerlineskip, I usually do this in my css:

p, .paragraph {
   .math:not(:first-child) {
      margin-top: 0.5em
   }
   .math:not(:last-child) {
      margin-bottom: 0.5em
   }
}

Would something like this work in your case?

For what \[ does, we can reference David Carlisle's answer here: \[ is the shorthand of \begin{displayMath}

After reading his answer I am tempted to treat \[ as a shorthand for displayMath environment, and do something like:

{
 type: "latexEnv"
 env: "displayMath"
 delimiters: ["\\]", "\\]"]
 children: [{...
 ...
}

I also took a close look at some of existing AST convention of remark. It looks like it is common to use the same type for different html tags depending on some type-specific attribute. For example:

Lists: Ordered and Unordered

A list - some text - another text	{ (type: "paragraph", children:...}, {type: "list", ordered: false, loose: true, children: [ {type: "listItem...}, {type: "listItem"...} ] }
An ordered list 1. first item 2. second item	{ (type: "paragraph", children:...}, {type: "list", ordered: true, loose: false, children: [ {type: "listItem...}, {type: "listItem"...} ] }

Also notice how the loose true/false affects the listItem's and how the listItem changes in wrapping tag w.r.t. to whether it is loose or not.

Header Tags, h

Header tags is another example. Depending on the heading order, it gives h1, h2 etc. You have to handle different tags using an attribute of the AST node.

[wooorm]

Folks, I’m going to close this. It’s a wonderful thread with great ideas, but it doesn’t seem like there’s something actionable that came out of it.

This project is now maintained under remarkjs. Please raise a new issue if this is still relevant and we can go from there!