History for BestPractices

changed:
-
Best practices for Content MathML

  - Anywhere a math operation occurs, you should surround it with math tags and properly mark up the math with MathML, even if the math occurs within the text.  Variables should also be marked up with math tags.  Numbers being referenced in text can be left as keyboard strokes.

  - When writing a subscripted symbol, write it as:: 

    <m:ci><m:msub>
        <m:mi>X</m:mi>
        <m:mn>0</m:mn>
       </m:msub></m:ci>

  - Common errors when writing subscripts include:

    - forgetting to wrap the entire thing in &lt;m:ci>
  
    - incorrectly using &lt;m:apply>
  
    - using content elements inside the msub
  
  - When using a superscript or mover for an accent mark (or hat, etc.), put the attribute 'accent="true"' on the msup or mover tag

  - When presentation markup is required, remember to use mo for operators, including commas used as separators, instead of mi::

    <m:ci><m:msub>
      <m:mi>K</m:mi>
      <m:mrow>
        <m:mi>t</m:mi>
        <m:mo>,</m:mo>
        <m:mrow>
          <m:mi>n</m:mi>
          <m:mo>&minus;</m:mo>
          <m:mn>1</m:mn>
        </m:mrow>
      </m:mrow>
     </m:msub></m:ci>


  - Don't use &lt;m:apply> around a single content item

  - Always use &lt;m:imaginaryi/> to represent the square root of -1 not &lt;m:ci>i&lt;/m:ci> (or j) unless you are specifically discussing notation
  
  - For a full-fledged complex number (like 3 + 4j), use &lt;m:cn type="complex-cartesian">3&lt;m:sep/>4&lt;/m:cn> instead of constructing it by hand.

  - Use UTF-8-encoded characters, if possible, instead of named entity references for special characters, i.e. "Σ" instead of "&amp;Sigma;".  If entering UTF-8 characters directly is too difficult, prefer numeric Unicode character references to MathML character entities, i.e. "&amp;#x03A3;" is preferable to "&amp;Sigma;".  Entity references are handy because mnemonic, but they entail technical limitations that are incompatible with Connexions software.  For this reason, character entity references are deprecated in Connexions content.

  - There are several inline operators that have no MathML content tag (for example, the "much greater than", or "plus/minus" symbols).  To use these in content MathML, use the following (note the appearance of the presentation tag "mo" to indicate that this is an operator.  Use the appropriate numeric Unicode character reference for whatever operator you need.  Be sure to nest the "mo" tags in "ci" tags.)::

      <m:apply>
        <m:ci>
          <m:mo>&gg;</m:mo>
        </m:ci>
        <m:ci>x</m:ci>
        <m:ci>y</m:ci>
      </m:apply>
   
  - When using Laplace Transform, remember that it is an operator and not &lt;m:ci type="fn">::

    <m:apply>
      <m:ci><m:mo>&Laplacetrf;</m:mo></m:ci>
      <m:ci>x</m:ci>
      <m:ci>t</m:ci>
    </m:apply>

 
  - When encountering an operator that has no tag in MathML, &lt;m:csymbol definitionURL="    "/> can be used to extend MathML.  Do this only after discussing the desired extension with the MathML team (see the MathML csymbol page on this site for operators already defined).

  - Don't use MathML just to get a single greek letter unless it is really being used as a mathematical variable.   Just use the numeric Unicode character reference inline with text.  

  - Don't use &lt;m:fn> for a simple function.  Instead, use &lt;m:ci type="fn">.  For example: f(t) would be written::

    <m:apply>
      <m:ci type="fn">f</m:ci>
      <m:ci>t</m:ci>
    </m:apply>


  - Use the MathML empty tags for entities such as &lt;m:pi/>, &lt;m:infinity/>, and &lt;integers/>, instead of entity descriptive names, for example:  &lt;m:ci>&amp;pi;&lt/m:ci>.  The entity descriptive names will need to be used when presentation MathML is required, such as in subscripts::

    <m:ci><m:msub>
      <m:mi>L</m:mi>
      <m:mi>&infin;</m:mi>
     </m:msub></m:ci>


  - When using &lt;m:root/> for square root, do not use &lt;m:degree>&lt;m:cn>2&lt;/m:cn>&lt;/m:degree> since square root is the default.

  - In contrast to displaying the negative of a variable, when designating a negative number, you may use &lt;m:cn>-1&lt;/m:cn> instead of::

     <m:apply>
       <m:minus/>
       <m:cn>1</m:cn>
     </m:apply> 

  
  - Always consider the mathematical meaning before the presentation.

    - When encountering x*, determine if the asterisk denotes 'otherness', complex conjugate, or in some cases conjugate transpose (also called Hermitian or Adjoint).  Use &lt;m:conjugate/> for complex conjugate and superscript for 'otherness'.

    - When encountering x', determine if the prime denotes 'otherness' or derivative or other mathematical operator.  Use superscript for 'otherness' and derivative without a bvar::

     <m:apply>
       <m:diff>
       <m:ci>x</m:ci>
     </m:apply>


  - When an equation has a condition such as y=x+7, x>2, markup the equation as a forall expression.  Remember this is only when the equation is surrounded with the equation tags.::

    <equation id='eqn1'>
      <m:math>
        <m:apply>
          <m:forall/>
          <m:bvar><m:ci>x</m:ci></m:bvar>
          <m:condition>
            <m:apply>
              <m:gt/>
              <m:ci>x</m:ci>
              <m:cn>2</m:cn>
            </m:apply>
          </m:condition>
          <m:apply>
            <m:eq/>
            <m:ci>y</m:ci>
            <m:apply>
              <m:plus/>
              <m:ci>x</m:ci>
              <m:cn>7</m:cn>
            </m:apply>
          </m:apply>
        </m:apply>
      </m:math>
    </equation>

  - When marking up partial diff with complex degrees (this is not power), the degree tag outside of the bvar is the overall degree which is displayed on top.  If you want a degree displayed on the bottom variable, you must add a degree tag inside of the bvar.  See the following example markup of (d^4/d^2x dy dz)f::

    <m:apply>
      <m:partialdiff/>
      <m:bvar>
        <m:degree><m:cn>2</m:cn></m:degree>
        <m:ci>x</m:ci>
      </m:bvar>
      <m:bvar><m:ci>y</m:ci></m:bvar>
      <m:bvar><m:ci>z</m:ci></m:bvar>
      <m:degree><m:cn>4<m:cn></m:bvar>
      <m:ci>f</m:ci>
    </m:apply>

  - When marking up the zero vector, instead of placing the 0 in "cn" tags, use &lt;ci type='vector'>::

    <m:ci type='vector'>0</m:ci>

  - When marking up coordinates, use MathML's set tags.  For example, (0,1) would be marked up as::

    <m:set>
      <m:cn>0</m:cn>
      <m:cn>1</m:cn>
    </m:set>

  - Also see AllisonsNotes