[latex3-commits] [latex3/latex2e] latex-lab/uf-review-05: start to move mml-code, WIP (108db277)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : latex-lab/uf-review-05
Link       : https://github.com/latex3/latex2e/commit/108db27729a2f5cdafa536f2edb5ac1d3c9de8aa

>---------------------------------------------------------------

commit 108db27729a2f5cdafa536f2edb5ac1d3c9de8aa
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Mon Jan 8 17:02:49 2024 +0100

    start to move mml-code, WIP


>---------------------------------------------------------------

108db27729a2f5cdafa536f2edb5ac1d3c9de8aa
 required/latex-lab/latex-lab-math.dtx | 77 +++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/required/latex-lab/latex-lab-math.dtx b/required/latex-lab/latex-lab-math.dtx
index 2a912e06..7e26c544 100644
--- a/required/latex-lab/latex-lab-math.dtx
+++ b/required/latex-lab/latex-lab-math.dtx
@@ -229,6 +229,55 @@
 %    
 %  \subsection{Display math}
 %    
+%  \textit{to be written}
+%    
+%  \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 source code should be attached as second file.)
+%  
+%  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. 
+%  The file can start with \verb|<x>| and end with \verb|</x>| to make it a valid
+%  xml-file that can be validated.
+%  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}
+%  
+%  \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/filelist={filename1,filename2}| (without extension, 
+%  |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, 
+%  it is not checked first if it is actually used (simply writing everything to the PDF 
+%  is a bit easier than keeping everything in memory and also means that 
+%  the snippets are one after the other in the PDF). 
+%  
+%  The MathML-AF can be suppressed for the equations in a group with |mathml/AF=false|, or
+%  completly by setting |mathml/filelist=| in the preamble. 
+%  
+%  Files embedded in a PDF can be listed in the attachments panel of a PDF viewer.
+%  This is probably not so useful for lots of small files (but one could create
+%  collections), but as long as PDF editors or viewers don't offer 
+%  proper support to access the AF it can help so have them there. The MathML are
+%  added by default, but the \LaTeX{} source not. This can be changed with
+%  |texsource/panel=true| (anywhere in the document) and |mathml/panel=false| (in the
+%  preamble, before the external file is read).  
+%  
+%  \subsection{Options}
 %      
 %   
 % \section{Known current bugs, etc.}
@@ -486,6 +535,34 @@
 %    \end{macrocode}
 % \end{macro}
 % 
+% \subsection{Code related to AF}
+% 
+% This internal variant of the \cs{mml} command
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_AF_mml:nnnn #1 #2 #3 #4
+%#1 number, #2 tex source for debugging, #3 hash, #4 mathml
+  {
+%    \end{macrocode}
+    % mathml with the same hash should be included only once:
+%    \begin{macrocode}
+    \tl_if_exist:cF { g_@@_mathml_#3_tl }
+     {
+%    \end{macrocode}
+%  a simple Desc key, take care that it is a valid string!
+%    \begin{macrocode}
+       \pdfdict_put:nne {l_pdffile/Filespec} {Desc}{(mathml-#1)} 
+       \pdffile_embed_stream:nnN {#4}{mathml-#1.xml}\l_tmpa_tl
+%    \end{macrocode}
+%  not strictly necessary but makes the files visible in the file attachment 
+%  page TODO add test for option
+%    \begin{macrocode}
+       \pdfmanagement_add:nne {Catalog/Names}{EmbeddedFiles}{\l_tmpa_tl}
+       \tl_new:c{g_@@_mathml_#3_tl}
+       \tl_gset_eq:cN{g_@@_mathml_#3_tl}\l_tmpa_tl
+     }
+  }   
+%    \end{macrocode}
+%
 % \subsection{Sockets}
 % \subsubsection{Main inline math sockets}
 %