1065843 - there is no help for entering mathematical formulas

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Johannes Leushuis]

User Agent: Mozilla/5.0 (Windows NT 5.1; rv:32.0) Gecko/20100101 Firefox/32.0 SeaMonkey/2.29
Build ID: 20140904220358

Steps to reproduce:

In Seamonkey 2.29 the addition of mathematical formulas in a insertion box is implemented
I wanted to know the syntax/grammar of Mathml/Tex mathematical formulas or have a weblink there, so
I pressed F1: Seamonkey Help shows
searched for 'mathematical'
searched for 'formula'


Actual results:

while searching for 'mathematical' 'no results' was shown
while searching for 'formula' idem dito.


Expected results:

while searching for 'mathematical' the syntax for Mathml/Tex mathematical formulas should appear, or a weblink thereto
while searching for 'formula' idem dito.

Comment 1

[rsx11m]

Not really a "major" loss of function given that it's a new feature where just the documentation lags behind (and there may be some dev-docs coming up helping to derive an adequate SM Help content).

Comment 2

[Frédéric Wang (:fredw)]

TeXZilla is used as a LaTeX-to-MathML parser, but the exact documentation is not done yet:

https://github.com/fred-wang/TeXZilla/wiki#texzilla-syntax

Essentially, the reference is itex2MML:

http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html

For the general Unicode/LaTeX character mappings to MathML token elements, TeXZilla relies on the unicode.xml file of the "XML Entity Definitions for Characters" (http://www.w3.org/TR/xml-entity-names/) is used. Unfortunately, this unicode.xml file has some mapping errors at the moment (the Math WG recently fixed some of them, but I haven't had a chance to take a look yet...)

Comment 4

[Frédéric Wang (:fredw)]

Attachment: Patch

Here is a first draft. Note that some features will only be available after bug 1098150

Comment 5

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 8657179 [details] [diff] [review]
Patch

Review of attachment 8657179 [details] [diff] [review]:
-----------------------------------------------------------------

Sorry but for the time being I can only offer my help (pun intended) proofreading. In particular, I have NOT checked:
* the included formulas
* HTML tags (esp. whether all that are opened are being closed)
* placement of content in the hierarchy (sections, order etc.)
* whether it compiles as part of the build-from-source process
* whether anything is missing or too much from a content perspective

I hope the below is still of value for you.

::: suite/locales/en-US/chrome/common/help/composer_help.xhtml
@@ +1253,5 @@
> +<h1 id="adding_mathematical_formulas_to_your_web_page">Adding Mathematical
> +  Formulas to Your Web Page</h1>
> +
> +<h2 id="inserting_a_mathematical_formula_into_your_page">Inserting a
> +  Mathematical formula into Your Web Page</h2>

Captial F in Formula please.

@@ +1256,5 @@
> +<h2 id="inserting_a_mathematical_formula_into_your_page">Inserting a
> +  Mathematical formula into Your Web Page</h2>
> +
> +<p>&brandShortName; Composer allows you to write mathematical formulas, encoded
> +  in your Web page as <a href="glossary.xhtml#mathml">MathML</a> and

Small W in web please.

@@ +1291,5 @@
> +  </li>
> +  <li>Choose the overall direction of your formula:
> +    <ul>
> +      <li><strong>Left-to-right direction</strong>: If selected, the formula
> +        will be layout from left to right e.g. <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><msqrt><mi>x</mi></msqrt><annotation encoding="TeX">\sqrt{x}</annotation></semantics></math>.

I'm not a native speaker of the English language but I'd reckon it's "laid out" rather than "layout", if that's even the right word in this context.

@@ +1294,5 @@
> +      <li><strong>Left-to-right direction</strong>: If selected, the formula
> +        will be layout from left to right e.g. <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><msqrt><mi>x</mi></msqrt><annotation encoding="TeX">\sqrt{x}</annotation></semantics></math>.
> +        This is the standard orientation in most countries.</li>
> +      <li><strong>Right-to-left direction</strong>: If selected, the formula
> +        will be layout from right to left e.g.

As above (layout).

@@ +1308,5 @@
> +  call the Insert Math menu and
> +  <a href="#editing_the_latex_source">edit the LaTeX source</a> again.</p>
> +
> +<p><strong>Note</strong>: &brandShortName; Composer attaches the LaTeX source to
> +  the generated MathML expressions, so that they can be edited again. In

I think there should be no comma here.

@@ +1309,5 @@
> +  <a href="#editing_the_latex_source">edit the LaTeX source</a> again.</p>
> +
> +<p><strong>Note</strong>: &brandShortName; Composer attaches the LaTeX source to
> +  the generated MathML expressions, so that they can be edited again. In
> +  general, it is  currently not possible to edit an arbitrary MathML expression,

Please remove double space.
Again I think no comma here.

@@ +1310,5 @@
> +
> +<p><strong>Note</strong>: &brandShortName; Composer attaches the LaTeX source to
> +  the generated MathML expressions, so that they can be edited again. In
> +  general, it is  currently not possible to edit an arbitrary MathML expression,
> +  unless it has an associated LaTeX expression supported by

I feel "it has a LaTeX expression associated that is supported" sounds better / more correct.

@@ +1314,5 @@
> +  unless it has an associated LaTeX expression supported by
> +  &brandShortName; Composer.
> +</p>
> +
> +<h2 id="editing_the_latex_source">Editing a LaTeX formula</h2>

Captial F in Formula.

@@ +1357,5 @@
> +<p>There exists a large collection of LaTeX commands and there is not any
> +  finite and well-defined list of them. &brandShortName; Composer only supports
> +  the <a href="https://github.com/fred-wang/TeXZilla/wiki/TeXZilla-Commands">TeXZilla commands</a>
> +  which are themselves based on the <a href="https://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html">itex2MML commands</a>
> +  and should cover the most popular constructions. One of the nice feature of

features.

@@ +1364,5 @@
> +  <tt>\left\lfloor\alpha^2\right\rfloor</tt> and generates
> +  <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo>⌊</mo><msup><mi>α</mi><mn>2</mn></msup><mo>⌋</mo></mrow><annotation encoding="TeX">\left⌊α^2\right⌋</annotation></semantics></math>.</p>
> +
> +<p>You do not need to know all the LaTeX commands to edit formulas. Instead, a
> +  panel of predefined expressions is available. Click on any of the panel button

I think it's just "click" rather than "click on" in English, but if in doubt, please ask a native speaker.
Also: buttons.

@@ +1366,5 @@
> +
> +<p>You do not need to know all the LaTeX commands to edit formulas. Instead, a
> +  panel of predefined expressions is available. Click on any of the panel button
> +  to insert the corresponding LaTeX expression. Arguments in LaTeX expressions
> +  are represented by ellipses and you can just edit the LaTeX source to

I feel a full stop after "ellipses", followed by a new sentence would make this more readable.

@@ +1371,5 @@
> +  replace them with the actual content you want.</p>
> +
> +<p><strong>Tip</strong>: If you select a subexpression in the LaTeX source field
> +  and use the construction panel to insert a LaTeX expression with at least one
> +  argument, then that subexpression will be used as the first argument of the

I feel "then" is superfluous here.

Comment 6

[Frédéric Wang (:fredw)]

Attachment: Patch V2

Thanks, here is an updated patch with the suggested changes.

Comment 7

[Stefan [:stefanh]]

(In reply to Frédéric Wang (:fredw) from comment #6)
> Created attachment 8657277 [details] [diff] [review]
> Patch V2
> 
> Thanks, here is an updated patch with the suggested changes.

Don't forget to request review of your patch. As it is (without a review request), it might just sit here for ages.

Comment 8

[Frédéric Wang (:fredw)]

(In reply to Stefan [:stefanh] from comment #7)
> Don't forget to request review of your patch. As it is (without a review
> request), it might just sit here for ages.

For now I'm just asking feedback. I'll ask for review after bug 1098150 is fixed.

Comment 9

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 8657277 [details] [diff] [review]
Patch V2

Review of attachment 8657277 [details] [diff] [review]:
-----------------------------------------------------------------

Looks good overall, almost there. Thanks for the contribution!

I could actually grab a nightly and compare to the Insert Math dialog now so this part has been verified. I did not check the resulting Help page though, so I have to trust you that you checked that it looks OK.

I'd like to see a new version with my nits addressed but I'm pretty sure we'll have it then.

Please remove the r=neil from the patch description.

::: suite/locales/en-US/chrome/common/help/composer_help.xhtml
@@ +1276,5 @@
> +    <a href="#editing_the_latex_source">Editing the LaTeX source</a>.
> +  </li>
> +  <li>Choose the style for your formula:
> +    <ul>
> +      <li><strong>inline mode</strong>: If selected, the formula is inserted

Captialize Inline to match the label.

@@ +1281,5 @@
> +        inside the current paragraph of text and rendered in a way that
> +        minimizes its height as much as possible. This mode is typically used
> +        for small expressions. For example this is an expression in inline mode:
> +        <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><msub><mo>∫</mo><mi>D</mi></msub><mi>x</mi><mi>d</mi><mi>x</mi></mrow><annotation encoding="TeX">\int_D x dx</annotation></semantics></math>.</li>
> +      <li><strong>display mode</strong>: If selected, the formula is inserted

Captialize Display to match the label.

@@ +1294,5 @@
> +      <li><strong>Left-to-right direction</strong>: If selected, the formula
> +        will be laid out from left to right e.g. <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><msqrt><mi>x</mi></msqrt><annotation encoding="TeX">\sqrt{x}</annotation></semantics></math>.
> +        This is the standard orientation in most countries.</li>
> +      <li><strong>Right-to-left direction</strong>: If selected, the formula
> +        will be laid out from right to left e.g.

I feel there should be a comma before e.g.

@@ +1304,5 @@
> +    Insert to create your new formula.</li>
> +</ol>
> +
> +<p>To modify a mathematical formula, move the insertion point inside it,
> +  call the Insert Math menu and

There is no Insert Math menu. You are referring to the Insert menu, Math menu item. Suggestion for improvement: "open the Insert menu, choose Math and"

Also worth mentioning (because much more obvious than entering the Insert menu for an editing action) is that when within a MathML expression, the context menu contains an entry called Advanced Properties which opens the same dialog. Please add this as the preferred way of editing (i.e. mention it first, then the Insert menu way).

@@ +1309,5 @@
> +  <a href="#editing_the_latex_source">edit the LaTeX source</a> again.</p>
> +
> +<p><strong>Note</strong>: &brandShortName; Composer attaches the LaTeX source to
> +  the generated MathML expressions so that they can be edited again. In
> +  general it is  currently not possible to edit an arbitrary MathML expression

remove double space

Comment 10

[Frédéric Wang (:fredw)]

Attachment: help-math-1.png

Comment 11

[Frédéric Wang (:fredw)]

Attachment: help-math-2.png

Comment 12

[Frédéric Wang (:fredw)]

Attachment: Patch V3

This should address your latest comments.

I also attached two screenshots of how the help page look for me in case you can not check that yourself.

Comment 13

[Philip Chee]

http://hg.mozilla.org/comm-central/rev/27c91093129e