JKQTMathText: improved documentation

doc/dox/jkqtmathtext.dox

@@ -1,6 +1,6 @@
 /*!
 
-\defgroup jkqtmathtext JKQTMathText LaTeX-Renderer for Qt
+  \defgroup jkqtmathtext JKQTMathText LaTeX-Renderer for Qt
 
 	This group contains JKQTMathText, a self-contained LaTeX-renderer for Qt. It is used to renderer
 	labels in JKQTPlotter, but can be used independently. The class does not depend on any library, 
@@ -18,22 +18,45 @@
   \image html jkqtmathtext/jkqtmathtext_sqrt.png
   \image html jkqtmathtext/jkqtmathtext_OldEnglish.png
 
-  
-  \defgroup jkqtmathtext_render Main (Render) Class (JKQTMathText)
+  \defgroup jkqtmathtext_general General Information
   \ingroup jkqtmathtext
 
-  \defgroup jkqtmathtext_items Render-Tree Items for JKQTMathText
+  This group assembles general information around JKQTMathText. It explains the rendering model, lists the supported LaTeX-subset etc.
+
+  
+  \defgroup jkqtmathtext_render Math Renderer Class (JKQTMathText)
   \ingroup jkqtmathtext
+  
+  This group contains the main rendering class JKQTMathText, which is the central access point for the functionality of this library.
+  This class is a non-visual class that allows to parse a string and draw the resulting object tree (see \ref jkqtmathtext_items )
+  using a <a href="https://doc.qt.io/qt-6/qpainter.html">QPainter</a> onto any target supported by the Qt painter library.
+  
+  \note There are additional widget classes available in \ref jkqtmathtext_widgets 
 
   \defgroup jkqtmathtext_widgets Widgets using JKQTMathText
   \ingroup jkqtmathtext
 
-  \defgroup jkqtmathtext_tools Tool Functions and Types for JKQTMathText
+  This group contains widgets that use JKQTMathText in order to render math onto the screen.
+
+  \defgroup jkqtmathtext_interaltools Library-internal Types and Functions
   \ingroup jkqtmathtext
   
+  This group contains all library-internal classes, types and functions. 
+  Normal users of the library do note have to have knowledge of these. They are important,
+  if you want to extend the functionality of the class.
+  
+  \defgroup jkqtmathtext_items Render-Tree Items for JKQTMathText
+  \ingroup jkqtmathtext_interaltools
+  
+  This group contains all classes that are used to build a memory-representation of the math to be rendered.
+  They form a tree in memory.
+
+  \defgroup jkqtmathtext_tools Tool Functions and Types for JKQTMathText
+  \ingroup jkqtmathtext_interaltools
+  
   
   \defgroup jkqtmathtext_libfacilities Library Facilities for JKQTMathText
-  \ingroup jkqtmathtext
+  \ingroup jkqtmathtext_interaltools
 
 
 */

doc/dox/jkqtmathtext_renderingmodel.dox

@@ -0,0 +1,42 @@
+/*!
+
+  \defgroup jkqtmathtext_renderingmodel JKQTMathText Rendering Model
+  \ingroup jkqtmathtext_general
+
+  JKQTMathText parses an (LaTeX) input string of mathematicalkmarkup and in a first step generates a memory representation of the it (cf. \ref jkqtmathtext_items ).
+  Then this memory representation is used to draw the represented math using the renndering API of <a href="https://doc.qt.io/qt-6/qpainter.html">QPainter</a>.
+  
+  As an example, we look at the following LaTeX markup, representing the solution to a quadratic equation:
+  
+  \code{.tex}
+    $x_{1/2} = \frac{-b\pm\sqrt{b^2-4ac}}{2a}$
+  \endcode
+  
+  LaTeX itself would render this as follows:
+  
+  \image html jkqtmathtext/jkqtmathtext_doc_quadraticeq_latex.png
+  
+  JKQTMathText produces this output:
+
+  \image html jkqtmathtext/jkqtmathtext_doc_quadraticeq.png
+
+  The memory representation of the expression above looks like this:
+  
+  \image html jkqtmathtext/jkqtmathtext_doc_quadraticeq_tree.png
+
+  \note  The memory representation is independent of the actual math markup language (e.g. LaTeX) which was initially parsed. 
+  But of course it is modelled, so the features of the supported markup languages are supported by the memory model.
+
+
+  You can see that each node corresponds to a box, if these are overlayed over the rendering:
+  
+  \image html jkqtmathtext/jkqtmathtext_doc_quadraticeq_boxes.png
+  
+  
+  The box, representing each node, is characterized by its width and height, as well as the ascent (or "baseline-height"):
+  
+  \image html jkqtmathtext_node_geo.png
+  
+   
+
+*/

doc/dox/jkqtmathtext_supportedlatex.dox

@@ -0,0 +1,162 @@
+/*!
+
+  \defgroup jkqtmathtext_supportedlatex Supported LaTeX-Subset
+  \ingroup jkqtmathtext_general
+  
+  \tableofcontents
+
+    \section JKQTMathTextSuppoertedLaTeXMathTextMode Switch between Math- and Text-Mode
+    
+    These LaTeX-instructions allow to switch between math and text-mode:
+      - \c $...$ , \c \\ensuremath{...} , \c \\equation{...} : inside is math-mode
+      - \c \\text{...} , \c \\mbox{...} , \c \\ensuretext{...} : switches from math back to text-mode (or stays in text-mode)
+    .
+    
+    The following image shows the difference between text- and math-mode:
+    
+    \image html jkqtmathtext/jkqtmathtext_mathmode_and_textmode.png
+    
+    In text mode the text is rendered normally. In math mode the rendering is changed:
+      - normal text is typeset in an italic font
+      - numbers, parantheses ... are typeset in an upright font
+      - operators are typeset with additional space around them
+    .
+    
+    \section JKQTMathTextSuppoertedLaTeXFontProps Font Properties
+    The supported LaTeX subset is listes below. Please note that some commands are used differently than in actual LaTeX.
+    For example \c \\bf is just a renamed form of \c \\textbf and used as \c \\bf{...} and NOT as \c {\\bf...} .
+
+      - \c \\bf{...} \c \\textbf{...} \c \\mathbf{...}:  draw the contained text in bold face \image html jkqtmathtext/jkqtmathtext_bold.png
+      - \c \\it{...} \c \\textit{...} \c \\mathit{...} :  draw the contained text in italic face \image html jkqtmathtext/jkqtmathtext_italic.png
+      - \c \\rm{...} \c \\textrm{...} \c \\mathrm{...} \c \\mbox{...} :  draw the contained text in normal upright roman font face \image html jkqtmathtext/jkqtmathtext_fonts.png
+      - \c \\sf{...} \c \\textsf{...} \c \\mathsf{...} :  draw the contained text in normal upright sans-serif font face \image html jkqtmathtext/jkqtmathtext_fonts.png
+      - \c \\script{...} \c \\textscript{...} \c \\mathscript{...} :  draw the contained text in a script font face \image html jkqtmathtext/jkqtmathtext_fonts.png
+      - \c \\sc{...} : draw the text in small caps \image html jkqtmathtext/jkqtmathtext_sc.png
+      - \c \\ul{...} \c \\underline{...} \c \\underlined{...} : draw the text with underlining \image html jkqtmathtext/jkqtmathtext_ul.png
+      - \c \\ol{...} \c \\overline{...} \c \\overlined{...} : draw the text with overlining \image html jkqtmathtext/jkqtmathtext_ol.png
+      - \c \\tt{...} \c \\texttt{...} \c \\mathtt{...} : draw text in typewriter font \image html jkqtmathtext/jkqtmathtext_fonts.png
+      - \c \\textcolor{color}{...} \c \\color{color} \c \\mathcolor{color}{...} : draw colored text \image html jkqtmathtext/jkqtmathtext_colored.png
+      - \c \\userfont{font}{...} : draw text in a user-specific font, available on the system \image html jkqtmathtext/jkqtmathtext_userfont.png (generated by <code>default, \\userfont{Arial}{Arial}, \\userfont{Comic Sans MS}{Comic Sans MS}</code> )
+      - \c \\sout{...} : strike out the text \image html jkqtmathtext/MTDstrike.png
+      - \c \\cancel{...} : slanted strike out the text \image html jkqtmathtext/MTDcancel.png
+      - \c \\bcancel{...} : back-strike out the text \image html jkqtmathtext/MTDbcancel.png
+      - \c \\xcancel{...} : x-strike out the text \image html jkqtmathtext/MTDxcancel.png
+    .
+    
+    
+    \section JKQTMathTextSuppoertedLaTeXBoxes Boxes
+
+    These instructions draw boxes in various ways:
+      - \c \\boxed{...} : draw text with a box around it \image html jkqtmathtext/jkqtmathtext_boxed.png
+      - \c \\doublebox{...} : draw text with a rounded box around it \image html jkqtmathtext/jkqtmathtext_doublebox.png
+      - \c \\ovalbox{...} : draw text with a rounded box around it \image html jkqtmathtext/jkqtmathtext_ovalboxed.png
+      - \c \\Ovalbox{...} : draw a thick oval box \image html jkqtmathtext/jkqtmathtext_oovalbox.png
+      - \c \\dashbox{...} , \c \\dbox{...} : draw a dashed box \image html jkqtmathtext/jkqtmathtext_dashbox.png
+      - \c \\dottedbox{...} : draw a dottted box \image html jkqtmathtext/jkqtmathtext_dottedbox.png
+      - \c \\ovaldoublebox{...} : draw a double oval box \image html jkqtmathtext/jkqtmathtext_doubleovalbox.png
+      - \c \\colorbox{bordercolor}{...} : draw a colored box \image html jkqtmathtext/jkqtmathtext_colorbox.png
+      - \c \\shaded{backgroundcolor}{...} : draw a filled box \image html jkqtmathtext/jkqtmathtext_shaded.png
+      - \c \\fcolorbox{bordercolor}{backgroundcolor}{...} : draw a colored, filled box \image html jkqtmathtext/jkqtmathtext_fcolorbox.png
+      - \c \\colorbox{color}{...} : draw a colored box around text \image html jkqtmathtext/jkqtmathtext_colorbox.png
+    .
+
+
+    
+    \section JKQTMathTextSuppoertedLaTeXSymbols Symbols and special characters
+
+    These instructions draw boxes in various ways:
+      - \c \\alpha ... : display the according greek letter \image html jkqtmathtext/jkqtmathtext_greek.png
+      - \c \\charDECIMAL and \c \\char\"HEX and \c \\char\'OCTAL : draws a unicode character from its 32-bit codepoint \image html jkqtmathtext/jkqtmathtext_char.png (generated by <code>A: \\char65, circonflex: \\char\"109 accent: \\char\'351</code>)
+      - \c \\unicode{HEX} and \c \\usym{HEX} : draws a unicode character from its 32-bit codepoint \image html jkqtmathtext/jkqtmathtext_unicode.png (generated by <code>star: \\unicode{2605}, circonflex: \\unicode{109} emoticons: \\usym{1F440} \\usym{1F929}</code>)
+      - \c \\utfeight{HEX} : draws a unicode character from its UTF-8 encoding \image html jkqtmathtext/jkqtmathtext_utf8.png (generated by <code>star: \\utfeight{e29885} emoticons \\utfeight{F09F9881} \\utfeight{f09f98bb}</code>)
+      - \c \\{ / \\} : display opening/closing brace
+      - \c \\_ : display underscore
+      - \c \\sum \c \\prod \c \\int ... : plot special symbol. Note that depending on the fontEncoding the available
+                                          symbols may differ (there are not all symbols defined in the MS Windows Symbol
+                                          font!). Best coverage should be given by Unicode font encoding with a good
+                                          unicode font installed!<br>\image html jkqtmathtext/jkqtmathtext_symbols.png
+      - \c - : draw a hyphen \image html jkqtmathtext/jkqtmathtext_hyphen.png
+      - \c -- : draw an en-dash \image html jkqtmathtext/jkqtmathtext_endash.png
+      - \c --- : draw an em-dash \image html jkqtmathtext/jkqtmathtext_emdash.png
+      - <code>\\vec{x} \\dot{x} \\ddot{x} \\overline{x} \\underline{x} \\hat{x} \\tilde{x} \\uul{x} \\ool{x} \\bar{x} \\arrow{x} \\widehat{x} \\widetilde{x} ...</code>: Decorations over/under symbols \image html jkqtmathtext/jkqtmathtext_mathdeco.png
+      - <code>\\verb{don't parse this _aaa\\LaTeX} </code>: interpret enclosed text as verbose \image html jkqtmathtext/jkqtmathtext_verb.png
+    .
+
+    \section JKQTMathTextSuppoertedLaTeXTextAlignment Environments for Multi-line text
+    Several environments are supported that allow to layout text with linebreaks and different alignemnts:
+      - <code>$\\begin{document} ... \\\\ ... \\end{document}$</code> \image html jkqtmathtext/jkqtmathtext_beginflushleft.png
+      - <code>$\\begin{flushleft} ... \\\\ ... \\end{flushleft}$</code> \image html jkqtmathtext/jkqtmathtext_beginflushleft.png
+      - <code>$\\begin{flushright} ... \\\\ ... \\end{flushright}$</code> \image html jkqtmathtext/jkqtmathtext_beginflushright.png
+      - <code>$\\begin{center} ... \\\\ ... \\end{center}$</code> \image html jkqtmathtext/jkqtmathtext_begincenter.png
+      - <code>$\\begin{framed} ... \\\\ ... \\end{framed}$</code> \image html jkqtmathtext/jkqtmathtext_beginframed.png
+      - <code>$\\begin{shaded} ... \\\\ ... \\end{shaded}$</code> \image html jkqtmathtext/jkqtmathtext_beginshaded.png
+      - <code>$\\begin{snugshade} ... \\\\ ... \\end{snugshade}$</code> \image html jkqtmathtext/jkqtmathtext_beginsnugshade.png
+    .
+    
+    
+    \section JKQTMathTextSuppoertedLaTeXMathSupport Supported Mathematical Constructs
+
+    \subsection JKQTMathTextSuppoertedLaTeXSubSuper Sub- and Superscript
+    The standard LaTeX sub-/superscript instructions (i.e. \c text_{sub} or \c text^{super} ) are supported:
+         - \c ^{...} \c _{...} : display the contents of braces in superscript/subscript \image html jkqtmathtext/jkqtmathtext_supersub.png
+        <br>Special subscript/superscript typesetting applies, when the sub/super follows \c \\sum \c \\Prod ...: \image html jkqtmathtext/jkqtmathtext_specialsubsuper.png
+    .
+ 
+    \subsection JKQTMathTextSuppoertedLaTeXBraces Braces/Parantheses ...
+    Braces in math mode are adjusted in size, so they are a small bit (factor \c brace_factor ) larger than the contents.
+    To enable this you have to write braces with \c \\left and \c \\right. These types of braces are defined (slight
+    differences to LaTeX standard):
+      - \c \\left( \c \\right) : default meaning (), \image html jkqtmathtext/jkqtmathtext_brace_round.png
+      - \c \\left[ \c \\right] : default meaning [], \image html jkqtmathtext/jkqtmathtext_brace_rect.png
+      - \c \\left\\{ \c \\right\\} : default meaning {}, \image html jkqtmathtext/jkqtmathtext_brace_curly.png
+      - \c \\left< \c \\right> : "averaging" braces , \image html jkqtmathtext/jkqtmathtext_brace_tri.png
+      - \c \\left\\lfloor \c \\right\\rfloor : floor braces , \image html jkqtmathtext/jkqtmathtext_brace_floor.png
+      - \c \\left~ \c \\right~ \c \\left\\lceil \c \\right\\rceil : ceil braces , \image html jkqtmathtext/jkqtmathtext_brace_ceil.png
+      - \c \\left| \c \\right| : absolute value braces | |, \image html jkqtmathtext/jkqtmathtext_brace_oneline.png
+      - \c \\left\\| \c \\right\\| \endcode : norm braces || ||, \image html jkqtmathtext/jkqtmathtext_brace_dblline.png
+      - You can use \c \\left. or \c \\right. to have only right or only left brace
+    .
+
+    \subsection JKQTMathTextSuppoertedLaTeXRoots Roots
+    There are also instructions that allow to write roots:
+      - <code>$\\sqrt{1+\\sqrt{1+x}}$</code> \image html jkqtmathtext/jkqtmathtext_sqrt.png
+      - <code>$\\sqrt[3]{1+\\sqrt[3]{1+x}}$</code> \image html jkqtmathtext/jkqtmathtext_cbrt.png
+    .
+
+    \subsection JKQTMathTextSuppoertedLaTeXUnderOver Undersetting, Oversetting, Underbraces, Overbraces ...
+    There are also instructions that allow to under/overset braces, arrows, ...:
+      - <code>$\\underbrace{x+x+...+x}{k\\ \\mathrm{times}}$</code> \image html jkqtmathtext/jkqtmathtext_brace_underbrace.png
+      - <code>$\\overbrace{x+x+...+x}{k\\ \\mathrm{times}}$</code> \image html jkqtmathtext/jkqtmathtext_brace_overbrace.png
+      - <code>$\\underbracket{x+x+...+x}{k\\ \\mathrm{times}}$</code> \image html jkqtmathtext/MTFMunderbracket.png
+      - <code>$\\overbracket{x+x+...+x}{k\\ \\mathrm{times}}$</code> \image html jkqtmathtext/MTFMoverbracket.png
+      - <code>$\\overset{main}{over}$</code> \image html jkqtmathtext/jkqtmathtext_brace_overset.png
+      - <code>$\\underset{main}{under}$</code> \image html jkqtmathtext/jkqtmathtext_brace_underset.png
+    .
+
+    \subsection JKQTMathTextSuppoertedLaTeXFrac Fraction Type Instructions
+    Several Matrix/Array-typed LaTeX instructions are supported:
+      - <code>$\\frac{...}{...}$</code> \image html jkqtmathtext/MTFMfrac.png
+      - <code>$\\tfrac{...}{...}$</code> (70% smaller font) \image html jkqtmathtext/MTFMtfrac.png
+      - <code>$\\dfrac{...}{...}$</code> \image html jkqtmathtext/MTFMdfrac.png
+      - <code>$\\sfrac{...}{...}$</code> \image html jkqtmathtext/MTFMsfrac.png
+      - <code>$\\stfrac{...}{...}$</code> (70% smaller font) \image html jkqtmathtext/MTFMstfrac.png
+   .
+
+    \subsection JKQTMathTextSuppoertedLaTeXMatrix Matrix/Array Type Instructions
+    Several Matrix/Array-typed LaTeX instructions are supported:
+      - <code>$\\stackrel{...}{...}$ $\\binom{...}{...}$</code> \image html jkqtmathtext/jkqtmathtext_brace_stackrel.png
+      - <code>$\\begin{cases} ... & ... \\\\ ... & ... \\end{cases}$</code> \image html jkqtmathtext/jkqtmathtext_brace_begincases.png
+      - <code>$\\begin{array} a & b & ...\\\\ c & d & ...\\end{array}$</code> <code>$\\begin{matrix} a & b & ...\\\\ c & d & ...\\end{matrix}$</code> \image html jkqtmathtext/jkqtmathtext_array.png
+      - <code>$\\begin{pmatrix} a & b & ...\\\\ c & d & ...\\end{pmatrix}$</code> \image html jkqtmathtext/jkqtmathtext_pmatrix.png
+      - <code>$\\begin{bmatrix} a & b & ...\\\\ c & d & ...\\end{bmatrix}$</code> \image html jkqtmathtext/jkqtmathtext_bmatrix.png
+      - <code>$\\begin{Bmatrix} a & b & ...\\\\ c & d & ...\\end{Bmatrix}$</code> \image html jkqtmathtext/jkqtmathtext_bbmatrix.png
+      - <code>$\\begin{vmatrix} a & b & ...\\\\ c & d & ...\\end{vmatrix}$</code> \image html jkqtmathtext/jkqtmathtext_vmatrix.png
+      - <code>$\\begin{Vmatrix} a & b & ...\\\\ c & d & ...\\end{Vmatrix}$</code> \image html jkqtmathtext/jkqtmathtext_vvmatrix.png
+      - <code>$\\substack[lrc]{...\\\\...}$</code> \image html jkqtmathtext/jkqtmathtext_substack.png
+      - <code>$\\lsubstack{...\\\\...}$</code> \image html jkqtmathtext/jkqtmathtext_lsubstack.png
+      - <code>$\\rsubstack{...\\\\...}$</code> \image html jkqtmathtext/jkqtmathtext_rsubstack.png
+    .
+
+
+    
+*/