document html format (WIP)

latex3 · Jan 22, 2024 · 500d852 · 500d852
1 parent 43a7bfb
commit 500d852
Showing 1 changed file with 64 additions and 10 deletions.
diff --git a/required/latex-lab/latex-lab-math.dtx b/required/latex-lab/latex-lab-math.dtx
@@ -233,32 +233,86 @@
 %    
 %  \subsection{Associated Files}
 %  
-%  The current code allows to attach two type of associated files to the Formula structure:
-%  the \LaTeX\ source and a MathML representation. Technically both can be attached---AF is an array
-%  if file references---practically it could lead to problems with PDF consumers: from the
-%  two consumer which handle AF-files, ngpdf uses both and so show the equation twice. 
-%  Foxit seems to see only the first AF in the array (which means that 
+%  The current code allows to attach two type of associated files to the 
+%  Formula structure:
+%  the \LaTeX\ source and a MathML representation. 
+%  Technically both can be attached---AF is an array
+%  if file references---practically there can be problems with PDF consumers as: 
+%  from the two consumer which handles currently AF-files, ngpdf used both and 
+%  so showed the equation twice (this has been corrected in the development version). 
+%  Foxit seemed to see only the first AF in the array (which means that 
 %  the source code should be attached as second file.)
 %  
-%  The \LaTeX\ source can be (and is) attached automatically. It can be suppressed by an option,
+%  The \LaTeX\ source can be (and is) attached automatically. 
+%  It can be suppressed by an option,
 %  \texttt{texsource/AF=false}, see below. 
 %  
 %  For a MathML representation a file with such representations must be provided. 
+%  If the equation is numbered the numbering should be part of the MathML as 
+%  the |Lbl| substructure is ignored if an MathML is used (see https://github.com/foxitsoftware/PDF_UA-2).
+%    
+%  Currently two input syntax for the MathML
+%  are supported\footnote{We do not expect
+%  both formats to stay. Experience will show which one is more useful and if more
+%  adaptions are needed.}:
+%  \begin{description}
+%  \item[xml/tex-format]   
 %  The file can start with \verb|<x>| and end with \verb|</x>| to make it a valid
 %  xml-file that can be validated.
+%  It should have the extension \texttt{.xml}.
 %  The file should contain a number of representations in this format:
 %  \begin{syntax}
 %  \cs{mml}\Arg{key}\Arg{source}\Arg{hash}\Arg{mathml}
 %  \end{syntax}
 %  
+%  The file is read in with the catcodes of \texttt{\#} and \texttt{\%} set to other
+%  so that they can be used in the \meta{mathml}. But braces must be correctly balanced.
+%   
 %  \meta{key} and \meta{source} are currently only used for debugging, they help to identify
 %  the equation referred by this representation. \meta{hash} is a hash key and is used 
 %  to identify the equation to which the MathML should be attached. If the equation is changed 
 %  it must be adapted. \meta{mathml} is the MathML representation.
 %  
-%  By default the code tries at the begin of the document to read a file |\jobname-mathml.xml|.
-%  The file name can be changed with |mathml/setfiles={filename1,filename2}| (without extension, 
-%  |xml| is added automatically). If there is a list, all files are loaded. 
+%  \item[\texttt{html}-format] A second format is meant to be a valid html file
+%  to view and check the mathml representation of the math in a browser.
+%  For this it can start with |<!DOCTYPE html><html>| and end with |</html>|
+%  It should have the extension \texttt{.html}.
+%  
+%  The file should contain a number of representations in this format:
+%  \begin{quote}
+%  |<div>| \\
+%  |  <h2>\mml| \meta{key}|</h2>|\\
+%  |  <p>|\meta{source}|</p>| \\
+%  |  <p>|\meta{hash}|</p>|   \\
+%  |  <math | \meta{attributes} |>|\\
+%  \meta{mathml}\\
+%  |  </math>|\\
+%  |</div>|
+%  \end{quote}
+%  The html tags |<div>|, |h2|, |<p>|, |<math|, |</math>| |</dvi>| are required as
+%  they are used to delimit the arguments by the \LaTeX{} code.
+%  
+%  |\mml|, \meta{key} and \meta{source} are only used for debugging, they help to identify
+%  the equation referred by this representation. The source should be used correctly escaped
+%  |&| and |<| so that if gives valid html!
+%  
+%  \meta{attributes} is not required either, but can e.g. contain attributes
+%  to improve the display in a browser:
+%  \begin{verbatim}
+%  <math alttext="\mathbf{G}" class="ltx_Math" display="inline">
+%  \end{verbatim}
+%  It can also contain the name space declaration: |xmlns="http://www.w3.org/1998/Math/MathML"|%
+%  \footnote{But it is probably not needed and only blows up the PDF.}
+%  \end{description}
+%  
+%  
+%  By default the code tries at the begin of the document 
+%  to read a file |\jobname-mathml.html| in the |html|-format. 
+%  The input format can be changed to the |xml/tex| format with
+%  |mathml/input=xml/tex|. 
+%  The file name can be changed with |mathml/setfiles={filename1,filename2}| 
+%  (without extension, |html| or |xml| is added automatically). 
+%  If there is a list, all files are loaded. 
 %  If a file doesn't exist it is ignored, only an info is written to the log.
 %  
 %  Currently every MathML-snippet from a file is embedded into the PDF, 
@@ -669,7 +723,7 @@
    }    
 
 %    \end{macrocode}
-% \end{macro}
+%
 %
 % \begin{macro}{\@@_AF_process_mathml_files:}
 %    \begin{macrocode}