--- loncom/html/adm/help/tex/Authoring_Output_Tags.tex	2007/05/21 16:43:17	1.7
+++ loncom/html/adm/help/tex/Authoring_Output_Tags.tex	2021/01/22 17:16:31	1.27
@@ -4,32 +4,69 @@
 This group of tags generates useful output. 
 
 \begin{itemize}
-\item \textbf{algebra}\index{algebra}: Typesets algebraic expressions
+\item \textbf{algebra}\index{algebra}\index{format algebra}: Typesets algebraic expressions
 \begin{verbatim}
-  <algebra>2x^y+sqrt(3/x^2)</algebra>
+<algebra>2x^y+sqrt(3/x^2)</algebra>
 \end{verbatim}
-\item \textbf{chem}\index{chem}: Typesets chemical equation 
+Expressions are displayed using the math expression display mechanism for the current context.  The default is to use
+the display mechanism the user has selected in preferences. This can be overriden by setting the \textbf{display} attribute for the tag. See the section below concerning the $<$m$>$ tag for more information on how the default is set and on the display attribute.
+
+Recognized functions are all trigonometric functions, and the following:
+exp, abs, logten, log, ln, sqrt, sgn, step, fact, int, lim, funX.
+\item \textbf{chem}\index{chem}\index{format reaction}: Typesets chemical equation :
 \begin{verbatim}
-  <chem>02 + 2H2 -> 2H20</chem>
+  <chem>O2 + 2H2 -> 2H2O</chem>
 \end{verbatim}
-\item \textbf{num}\index{num}: Typesets a number 
+will be rendered:
+$\mathrm{O_2} + 2\,\mathrm{H_2} \to 2\,\mathrm{H_2O}$
+
+\textbf{Syntax Description}
+\begin{itemize}
+\item Reactants are separated from products by `\texttt{->}'.
+\item Individual reactants and products are separated by `\texttt{  +}' (leading space is obligatory).
+\item Numbers preceding the first symbol of a chemical specie are considered to be stoichiometric coefficients.
+\item Numbers appearing after the first symbol of a chemical specie are considered to be subscripts.
+\item Superscripts are initialized by `\texttt{\^{}}' and terminated by a space.
+\item Ionic charges are superscripts composed of a number followed by a sign (i.e. `\texttt{\^{}2+}').
+\end{itemize}
+
+\textbf{More examples}
+\begin{itemize}
+\item $\mathrm{Ca}(\mathrm{NO}_3)_2$ is written as:\\
+\texttt{Ca(NO3)2}
+\item $\mathrm{OH}^- + \mathrm{H_3O}^+ \to 2\mathrm{H_2O}$ is written as:\\
+\texttt{OH\^{}- + H3O\^{}+ -> 2H2O}
+\item $[\mathrm{Co}(\mathrm{H_2O})_6]^{2+} + 4\mathrm{Cl}^- \to [\mathrm{CoCl_4}]^{2-} + 6\mathrm{H_2O}$ is written as:\\
+\texttt{[Co(H2O)6]\^{}2+ + 4Cl\^{}- -> [CoCl4]\^{}2- + 6H2O}
+\item $^3_1\mathrm{H} + ^2_1\mathrm{H} \to ^4_2\mathrm{He} + ^1_0\mathrm{n}$ is written as:\\
+\texttt{\^{}3 1H + \^{}2 1H -> \^{}4 2He + \^{}1 0n}
+\end{itemize}
+
+\item \textbf{num}\index{num}\index{format number}: Typesets a number formatted in scientific notation, fixed point, fixed point with commas, fixed point with commas and dollar sign, or in significant digits. 
 \begin{verbatim}
-  <num format=''2E''>31454678</num>
+  <num format="2E">31454678</num> results in 3.15 x 10^7
+  <num format="2f">31454678</num> results in 31454678.00
+  <num format="4g">31454678</num> results in 3.145 x 10^7
+  <num format="4g">314.54678</num> results in 314.5
+  <num format=",2f">31454678</num> results in 31,454,678.00
+  <num format="$2f">31454678</num> results in $31,454,678.00
+  <num format="2s">31454678</num> results in 31000000
+  <num format=",2s">31454678</num> results in 31,000,000
 \end{verbatim}
 \item \textbf{parse}\index{parse}: to display the parsed view of a variable's
 contents
 \begin{verbatim}
-  <script type=''loncapa/perl''>
+  <script type="loncapa/perl">
    $table='<table>';
    for ($i=1;$i<=10;$i++) {
       $table.='<tr><td>'.$i.'</td><td>'.&random(1,10,1).'</td></tr>';
    }
    $table.='</table>';
   </script>
-  <parse>\$table</parse>
+  <parse>$table</parse>
 \end{verbatim}
 
-\item \textbf{standalone}\index{standalone}: Everything inbetween the
+\item \textbf{standalone}\index{standalone}: Everything in between the
 start and end tag is shown only on the web and only if the resource
 is not part of a course. 
 \item \textbf{displayduedate}\index{displayduedate}: This will insert the
@@ -105,22 +142,140 @@ in LON-CAPA style files.
 \item \textbf{window}\index{window}: This creates a link that when clicked shows the intervening information in a pop-up window. By default the window will be 500 pixels wide and 200 pixels tall, and the link text will be a superscript * (so as to look like a footnote). These can be changed using the attributes
 
 \begin{itemize}
-\item[width] controls the starting width of the popup window
-\item[height] controls the starting height of the popup window
-\item[linktext] the text that should appear as the link that causes the creation of the window
+\item \textbf{width} controls the starting width of the popup window
+\item \textbf{height} controls the starting height of the popup window
+\item \textbf{linktext} the text that should appear as the link that causes the creation of the window
+\item \textbf{printtext} the text that should appear instead of a footnote when printed
 \end{itemize}
 
-When printing this included text will get turned into a real footnote.
+When printing, the included text will get turned into a real footnote.
+
+\item \textbf{windowlink}\index{windowlink}: This creates a link to a resource that comes up in a pop-up window. The link will be the intervening information
+between the start and the end tag. By default the window will be 500 pixels wide and 200 pixels tall.
 
+\begin{itemize}
+\item \textbf{width} controls the starting width of the popup window
+\item \textbf{height} controls the starting height of the popup window
+\item \textbf{href} the address
+\end{itemize}
 
-\item \textbf{m}\index{m}: The inside text is \LaTeX{}, and is converted
-to HTML (or MathML) on the fly. If the attribute \textbf{eval} is set
-to {}``\textbf{on}'' the intervening text will have a perl variable
-expansion done to it before being converted. The default is to convert
-to the display mechanism that the user has selected. This can be
+\item \textbf{togglebox}\index{togglebox}: This creates a toggling box that can be clicked open and close.
+
+\begin{itemize}
+\item \textbf{heading} heading text of the box, by default no heading
+\item \textbf{headerbg} background color of the header, by default white
+\item \textbf{showtext} the text that appears to make the box visible, by default the translation of `show'
+\item \textbf{hidetext} the text that appears to hide the box again, by default the translation of `hide'
+\end{itemize}
+
+When printing, the included text will be rendered in a visible box.
+
+
+\item \textbf{m}\index{m}\index{equations}: The inside text is \LaTeX{}, and is converted
+to HTML (or MathML) on the fly. The default is to convert
+to the display mechanism that the user has selected in preferences. This can be
 overriden by setting the attribute \textbf{display} to one of
-``\textbf{tth}'' or ``\textbf{jsMath}'' or ``\textbf{mimetex}''which
-will force a specfic display mechanism.
+``\textbf{tth}'', ``\textbf{mimetex}'' or ``\textbf{mathjax}'' which
+will force a specific display mechanism. Note that the ``\textbf{jsmath}'' display is deprecated today, and MathJax is used instead when it is specified.  If a display attribute is not included, the display mechanism is determined in the following order, with the first one set being the one in effect:
+\begin{enumerate}
+\item In course context: Course-wide default set by Course Coordinator via Settings $>$ Course Settings $>$ Display of resources $>$ Force use of a specific math rendering engine
+\item User's own personal preference set by the user hovering over the user's name at top left of a LON-CAPA page, and selecting Preferences $>$ Math display settings
+\item Domain default set by a Domain Coordinator 
+\item System default set for the LON-CAPA version installed on the server (tth in 2.11 and earlier, mathjax in 2.12).
+\end{enumerate}
+
+The contents of \texttt{<m> </m>} are interpreted as LaTeX outside math environment, which is why using \texttt{<m>\$ \$</m>} is needed to switch to the LaTeX math environment. However, the ``\textbf{mathjax}'' display (which is used by default in recent versions of LON-CAPA) interprets all the contents of \texttt{<m> </m>} as math, and does not support non-math LaTeX. For content to work well with all the display mechanisms, it is therefore important to never use non-math LaTeX for web targets. Even purely for printing, it is better to avoid using non-math LaTeX, as the printing mechanism might use HTML instead of LaTeX in the future.
+
+If you want variables inside of this tag to be evaluated before the
+tex gets converted, then use eval=``on'' \index{eval=on}. For
+example,  \texttt{<m eval=''on''>\$ \$eqn \$</m>},
+will evaluate the variable \$eqn first and then use the
+display mechanism.  Anytime you use a variable inside of the m tag,
+you will want to set eval to on.
+
+For example, put the following in a script in the resource:
+
+\texttt{\$eqn = "\$a+\$b";}
+
+\texttt{\$eqn =~ s/\textbackslash{}+-/-/g;}
+
+and in a text area, you can type:
+
+\texttt{<m eval=''on''>\$ \$eqn \$</m>}
+
+You will get the equation rendered with no +-, no matter what value
+\$b may take on.
+
+
+\item \textbf{lm}\index{lm}\index{equations}: This is another way to input math, which does not require
+knowing \LaTeX{}.
+The lm syntax describes mathematical operations rather than appearance (as opposed to LaTeX, which describes how the math should appear). Display is the same when the math operations are the same, for instance 2*(x) will be displayed just like 2x. One advantage to that system is that math will be displayed in a consistent way, even when written by several authors. The drawback is that display cannot be chosen precisely.
+Eventually, this syntax will also be used to evaluate \texttt{<formularesponse>} (it is already used for the real-time preview).
+
+\begin{description}
+\item[Spaces]~\\
+    Spaces are always ignored.
+
+\item[Decimal separators and function parameter separators]~\\
+    To keep compatible with previous \texttt{<formularesponse>} syntax, only ``.'' can be used as a decimal separator, and ``,'' is used to separate function and vector/matrix parameters.
+    
+\item[Variables and constants]~\\
+    Variable names and constant names are used directly, without any special character before. They are displayed in italics.
+    
+\item[Units]~\\
+    Unit names are used directly. They are displayed with a straight font. LON-CAPA has a list of known units and a list of known constants to differentiate them in units mode.
+    
+\item[Parenthesis]~\\
+    Parenthesis can be used to specify evaluation order. They are only displayed when necessary.
+    
+\item[Operators]~\\
+    arithmetic: \texttt{+ - * / \^{}}\\
+    factorial: \texttt{!}\\
+    relational: \texttt{= \# < <= >= >}\\
+    units: \texttt{`}\\
+    Example: \texttt{2`m + 3`m = 5`m}\\
+    scalar product for vectors, multiplication for matrices: \texttt{.}\\
+
+\item[Implicit operators]~\\
+    \texttt{*} and \texttt{`} are implicit.
+
+    The parser will try to guess which operator is missing whenever possible. The choice between * and ` depends on the mode for interpreting equations.
+
+    Example: \texttt{2c+3m/s} is understood in unit mode to be \texttt{2*c + 3`(m/s)}. In symbolic mode, it would be interpreted \texttt{2*c + (3*m)/s} (m and s being variables).
+    
+\item[Functions]~\\
+    Functions use the syntax \texttt{f(a,b)}.
+
+        basic:
+
+        \quad \texttt{sqrt(x)}, \texttt{abs(x)}, \texttt{exp(x)=e\^{}x}, \texttt{factorial(x)=x!}
+
+        binomial (displayed like a vector):
+
+        \quad \texttt{binomial(n,p)=n!/(p!*(n-p)!)}
+
+        sum and product (requiring symbolic mode):
+
+        \quad \texttt{sum(f(x),x,x1,x2)}, \texttt{product(f(x),x,x1,x2)}
+
+        differential, integral, limit:
+
+        \quad \texttt{diff(expr,x,n)}, \texttt{integrate(expr,x,a,b)}, \texttt{limit(expr,x,val,dir)}
+
+\item[Vectors and matrices]~\\
+    Vectors and matrices are defined with square brackets. A matrix is made of a list of row vectors.
+
+        vectors: \texttt{[1,2,3]}\\
+        matrices: \texttt{[[1,2],[3,4]]}
+
+\item[Sets]~\\
+    Sets are defined with curly brackets: \texttt{\{1,2,3\}}
+
+        union: \texttt{union(\{1,2\},\{1,3\}) = \{1,2,3\}}\\
+        intersection: \texttt{intersection(\{1,2\},\{1,3\}) = \{1\}}
+    
+\end{description}
+
 
 \item \textbf{randomlabel}\index{randomlabel}: This shows a specified image
 with images or text labels randomly assigned to a set of specific
@@ -159,4 +314,14 @@ external image or a LON-CAPA resource. I
 \item \textbf{height}\index{height}: The height of the image in pixels.
 \item \textbf{texwidth}\index{texwidth}: The width of the image in millimeters.
 \end{itemize}
+
+\item \textbf{problemtype}\index{problemtype}: This tag allows you to show or hide output based on what the problem-type parameter is set to in the course. For example: \begin{verbatim}
+<problemtype mode="show" for="exam,survey">
+  <startouttext />
+  The formula for the circumference of a circle is 2*pi*r
+  <endouttext />
+</problemtype>
+\end{verbatim}
+Will only show the output text when the problem is set to the type of exam or survey in the course.  The attribute for mode can be set to show or hide.  The attribute for for can be problem, exam, survey, or practice.
+
 \end{itemize}