diff options
author | Norbert Preining <norbert@preining.info> | 2023-03-22 03:01:52 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-03-22 03:01:52 +0000 |
commit | cbbc6dbdbf08b70a7e7d8d184ca51c57c835415a (patch) | |
tree | 97ded8ca7095c54f6ff9b661be6b93f80bf792c4 /macros/latex/contrib/stex/doc/stex-tutorial.tex | |
parent | de9a0afa47c2ee09e1d4704821cad2b231d36b3f (diff) |
CTAN sync 202303220301
Diffstat (limited to 'macros/latex/contrib/stex/doc/stex-tutorial.tex')
-rw-r--r-- | macros/latex/contrib/stex/doc/stex-tutorial.tex | 354 |
1 files changed, 0 insertions, 354 deletions
diff --git a/macros/latex/contrib/stex/doc/stex-tutorial.tex b/macros/latex/contrib/stex/doc/stex-tutorial.tex deleted file mode 100644 index 7b3b723826..0000000000 --- a/macros/latex/contrib/stex/doc/stex-tutorial.tex +++ /dev/null @@ -1,354 +0,0 @@ - \begin{sfragment}{A First \sTeX Document} - Having set everything up, we can write a first - \sTeX document. As an example, we will use the - |smglom/calculus| and |smglom/arithmetics| archives, - which should be present in the designated |MathHub|-folder, - and write a small fragment defining the \emph{geometric series}: - - % \textcolor{red}{TODO: use some sTeX-archive instead of smglom, - % use a convergence-notion that includes the limit, - % mark-up the theorem properly} - - \begin{framed}\begin{latexcode}[gobble=8] - \documentclass{article} - \usepackage{stex,xcolor,stexthm} - - \begin{document} - \begin{smodule}{GeometricSeries} - \importmodule[smglom/calculus]{series} - \importmodule[smglom/arithmetics]{realarith} - - \symdef{geometricSeries}[name=geometric-series]{\comp{S}} - - \begin{sdefinition}[for=geometricSeries] - The \definame{geometricSeries} is the \symname{series} - \[\defeq{\geometricSeries}{\definiens{ - \infinitesum{\svar{n}}{1}{ - \realdivide[frac]{1}{ - \realpower{2}{\svar{n}} - }} - }}.\] - \end{sdefinition} - - \begin{sassertion}[name=geometricSeriesConverges,type=theorem] - The \symname{geometricSeries} \symname{converges} towards $1$. - \end{sassertion} - \end{smodule} - \end{document} - \end{latexcode}\end{framed} - - Compiling this document with |pdflatex| should yield - the output - - \begin{mdframed} - \noindent\textbf{Definition 0.1. }\ The - \pdftooltip{\textcolor{blue}{\textbf{geometric series}}}{URI: file://your/file/name/here?GeometricSeries?geometric-series} - is the - \pdftooltip{\textcolor{blue}{series}}{URI: http://mathhub.info/smglom/calculus?series?series} - \[ - \pdftooltip{\textcolor{blue}S}{URI: file://your/file/name/here?GeometricSeries?geometric-series} - \pdftooltip{\textcolor{blue}{:=}}{URI: http://mathhub.info/smglom/mv?defeq?definitional-equation} - \mathop{\pdftooltip{\textcolor{blue}{\sum}}{URI: http://mathhub.info/smglom/calculus?series?infinitesum} - }_{ - \pdftooltip{\textcolor{gray}{n}}{Variable var://n}=1 - }^{ - \pdftooltip{\textcolor{blue}\infty}{URI: http://mathhub.info/smglom/calculus?series?infinitesum} - } \frac{1}{2^{\pdftooltip{\textcolor{gray}{n}}{Variable var://n}}} - .\] - \noindent\textbf{Theorem 0.2. }\ The - \pdftooltip{\textcolor{blue}{geometric series}}{URI: file://your/file/name/here?GeometricSeries?geometric-series} - \pdftooltip{\textcolor{blue}{converges}}{URI: http://mathhub.info/smglom/calculus?sequenceConvergence?converges} towards $1$. - \end{mdframed} - - Move your cursor over the various highlighted parts of the document -- depending on - your pdf viewer, this should yield some interesting (but possibly for now cryptic) - information. - - \begin{sparagraph}[type=remark] - Note that all of the highlighting, tooltips, coloring and the environment headers - come from \pkg{stexthm} -- by default, the amount of additional packages loaded - is kept to a minimum and all the presentations can be customized, - see \sref{sec.customhighlight}. - \end{sparagraph} - - Let's investigate this document in detail to understand the respective parts of the - \sTeX markup infrastructure:\bigskip - - \begin{environment}{smodule} - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=8] - \begin{smodule}{GeometricSeries} - ... - \end{smodule} - \end{latexcode} - First, we open a new \emph{module} called |GeometricSeries|. The main purpose of - the |smodule| environment is to group the contents and associate it with a - \emph{globally unique} identifier (URI), which is computed from the name - |GeometricSeries| and the document context. - - (Depending on your pdf viewer), the URI should pop up in a tooltip if you hover over - the word \pdftooltip{\textcolor{blue}{\textbf{geometric series}}}{URI: - file://your/file/name/here?GeometricSeries?geometric-series}. - \end{environment}\bigskip - - \begin{function}{\importmodule} - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=8] - \importmodule[smglom/calculus]{series} - \importmodule[smglom/arithmetics]{realarith} - \end{latexcode} - Next, we \emph{import} two modules -- |series| from the \sTeX archive - |smglom/calculus|, and |realarith| from the \sTeX archive |smglom/arithmetics|. If - we investigate these archives, we find the files |series.en.tex| and - |realarith.en.tex| (respectively) in their respective |source|-folders, which - contain the statements \stexcode"\begin{smodule}{series}" and - \stexcode"\begin{smodule}{realarith}" (respectively). - \iffalse\end{smodule}\end{smodule}\fi - - The \stexcode"\importmodule"-statements make all \stex symbols and associated - semantic macros (e.g. \stexcode"\infinitesum", \stexcode"\realdivide", - \stexcode"\realpower") in the imported module available to the current module - |GeometricSeries|. The module |GeometricSeries| ``exports'' all of these symbols to - all modules imports it via an \stexcode"\importmodule{GeometricSeries}" - instruction. Additionally it exports the local symbol \stexcode"\geometricSeries". - \end{function} - - \begin{function}{\usemodule} - If we only want to \emph{use} the content of some module |Foo|, - e.g. in remarks or examples, but none - of the symbols in our current module actually \emph{depend} on - the content of |Foo|, we can use \stexcode"\usemodule" instead -- like - \stexcode"\importmodule", this will make the module content available, - but will \emph{not} export it to other modules. - \end{function}\bigskip - - \begin{function}{\symdef} - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=6] - \symdef{GeometricSeries}[name=geometric-series]{\comp{S}} - \end{latexcode} - Next, we introduce a new \emph{symbol} with name - |geometric-series| and assign it the semantic macro - \stexcode"\geometricSeries". - \stexcode"\symdef" also immediately assigns this symbol a \emph{notation}, - namely $S$. - \end{function} - - \begin{function}{\comp} - The macro \stexcode"\comp" marks the $S$ in the notation as a - \emph{notational component}, as opposed to e.g. arguments - to \stexcode"\geometricSeries". - It is the notational components that get highlighted - and associated with the corresponding symbol (i.e. in this - case |geometricSeries|). Since \stexcode"\geometricSeries" takes - no arguments, we can wrap the whole notation in a \stexcode"\comp". - \end{function}\bigskip - - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=8] - \begin{sdefinition}[for=geometricSeries] - ... - \end{sdefinition} - \begin{sassertion}[name=geometricSeriesConverges,type=theorem] - ... - \end{sassertion} - \end{latexcode} - What follows are two \sTeX-\emph{statements} (e.g. definitions, - theorems, examples, proofs, ...). These are semantically marked-up - variants of the usual environments, which take additional optional - arguments (e.g. |for=|, |type=|, |name=|). Since many \LaTeX\xspace templates - predefine environments like |definition| or |theorem| with - different syntax, we use \stexcode"sdefinition", - \stexcode"sassertion", \stexcode"sexample" - etc. instead. You can customize these environments to e.g. - simply wrap around some predefined |theorem|-environment. - That way, we can still use \stexcode"sassertion" to provide semantic - information, while being fully compatible with (and using - the document presentation of) predefined environments. - - In our case, the \pkg{stexthm}-package patches - e.g. \stexcode"\begin{sassertion}[type=theorem]" to use - a |theorem|-environment defined (as usual) using the \pkg{amsthm} package. - \bigskip \iffalse \end{sassertion}\fi - - \begin{function}{\symname} - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=6] - ... is the \symname{?series} - \end{latexcode} - The \stexcode"\symname"-command prints the name of a symbol, - highlights it (based on customizable settings) - and associates the text printed with the corresponding - symbol. - - Note that the argument of \stexcode"\symref" can be - an imported symbol - (here the |series| symbol is imported from the |series| module). \sTeX tries to - determine the full symbol URI from the argument. If there are name clashes in or - with the imported symbols, the name of the exporting module can be prepended to the - symbol name before the |?| character. - - If you hover over the word - \pdftooltip{\textcolor{blue}{series}}{URI: http://mathhub.info/smglom/calculus?series?series} - in the pdf output, you should see a tooltip showing the full URI - of the symbol used. - \end{function} - \begin{function}{\symref} - The \stexcode"\symname"-command is a special case of the more general - \stexcode"\symref"-command, which allows customizing the precise text associated - with a symbol. \stexcode"\symref" takes two arguments: the first ist the symbol - name (or macro name), and the second a variant verbalization of the symbol, e.g. an inflection - variant, a different language or a synonym. In our example - \stexcode"\symname{?series}" abbreviates \stexcode|\symref{?series}{series}|. - - \end{function} - \begin{function}{\definame,\definiendum} - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=6] - The \definame{geometricSeries} ... - \end{latexcode} - The \stexcode"sdefinition"-environment provides two additional - macros, \stexcode"\definame" and \stexcode"\definiendum" which behave - similarly to \stexcode"\symname" and \stexcode"\symref", but explicitly mark - the symbols as \emph{being defined} in this environment, - to allow for special highlighting. - \end{function}\bigskip - - \begin{latexcode}[numbers=none,aboveskip=0pt,belowskip=0pt,gobble=8] - \[\defeq{\geometricSeries}{\definiens{ - \infinitesum{\svar{n}}{1}{ - \realdivide[frac]{1}{ - \realpower{2}{\svar{n}} - }} - }}.\] - \end{latexcode} - The next snippet -- set in a math environment -- uses - several semantic macros imported from (or recursively via) - |series| and |realarithmetics|, such as \stexcode"\defeq", - \stexcode"\infinitesum", - etc. In math mode, using a semantic macro inserts its (default) - definition. A semantic macro can have several notations -- in - that case, we can explicitly choose a specific notation by - providing its identifier as an optional argument; e.g. - \stexcode"\realdivide[frac]{a}{b}" will use the explicit notation named |frac| - of the semantic macro \stexcode"\realdivide", which yields $\frac ab$ - instead of $a/b$. - \begin{function}{\svar} - The \stexcode"\svar{n}" command marks up the |n| as a variable - with name |n| and notation |n|. - \end{function} - \begin{function}{\definiens} - The \stexcode"sdefinition"-environment additionally provides the - \stexcode"\definiens"-command, which allows for explicitly - marking up its argument as the \emph{definiens} of the - symbol currently being defined. - \end{function} - - \begin{sfragment}{\omdoc/xhtml Conversion} - So, if we run |pdflatex| on our document, then \sTeX yields pretty colors and - tooltips\footnote{...and hyperlinks for symbols, and indices, and allows reusing - document fragments modularly, and...}. But \sTeX becomes a lot more powerful if - we additionally convert our document to |xhtml| while preserving all the \sTeX - markup in the result. - - \textcolor{red}{TODO VSCode Plugin} - - Using \rustex \cite{RusTeX:on}, we can convert the document to |xhtml| - using the command |rustex -i /path/to/file.tex -o /path/to/outfile.xhtml|. - Investigating the resulting file, we notice additional semantic - information resulting from our usage of semantic macros, - \stexcode"\symref" etc. Below is the (abbreviated) snippet inside - our \stexcode"\definiens" block: - -\begin{lstlisting}[escapechar=!, -morekeywords={property,resource,stex:comp,stex:arg,stex:OMA,stex:OMV}] -<mrow resource="" property="stex:definiens"> - <mrow resource="...?series?infinitesum" property="stex:OMBIND"> - <munderover displaystyle="true"> - <mo resource="...?series?infinitesum" property="stex:comp">!$\Sigma$!</mo> - <mrow> - <mrow resource="1" property="stex:arg"> - <mi resource="var://n" property="stex:OMV">n</mi> - </mrow> - <mo resource="...?series?infinitesum" property="stex:comp">=</mo> - <mi resource="2" property="stex:arg">1</mi> - </mrow> - <mi resource="...?series?infinitesum" property="stex:comp">!$\infty$!</mi> - </munderover> - <mrow resource="3" property="stex:arg"> - <mfrac resource="...?realarith?division#frac#" property="stex:OMA"> - <mi resource="1" property="stex:arg">1</mi> - <mrow resource="2" property="stex:arg"> - <msup resource="...realarith?exponentiation" property="stex:OMA"> - <mi resource="1" property="stex:arg">2</mi> - <mrow resource="2" property="stex:arg"> - <mi resource="var://n" property="stex:OMV">n</mi> - </mrow> - </msup> - </mrow> - </mfrac> - </mrow> - </mrow> -</mrow> - \end{lstlisting} - ...containing all the semantic information. The \mmt system - can extract from this the following \openmath snippet: - - \begin{lstlisting}[escapechar=!] -<OMBIND> - <OMID name="...?series?infinitesum"/> - <OMV name="n"/> - <OMLIT name="1"/> - <OMA> - <OMS name="...?realarith?division"/> - <OMLIT name="1"/> - <OMA> - <OMS name="...realarith?exponentiation"/> - <OMLIT name="2"/> - <OMV name="n"/> - </OMA> - </OMA> -</OMBIND> - \end{lstlisting} - ...giving us the full semantics of the snippet, allowing for - a plurality of knowledge management services -- in particular - when serving the |xhtml|. - - \begin{remark} - Note that the |html| when opened in a browser will - look slightly different than the |pdf| when it comes - to highlighting semantic content -- that is because - naturally |html| allows for much more powerful - features than |pdf| does. Consequently, the |html| - is intended to be served by a system like \mmt, - which can pick up on the semantic information and - offer much more powerful highlighting, linking - and similar features, and being customizable by - \emph{readers} rather than being prescribed by an author. - - Additionally, not all browsers (most notably Chrome) - support \mathml natively, and might require - additional external JavaScript libraries such as - MathJax to render mathematical formulas properly. - \end{remark} - \end{sfragment} - - - \begin{sfragment}{\mmt/\omdoc Conversion} - Another way to convert our document to \emph{actual} - \mmt/\omdoc is to put it in an \sTeX \textbf{archive} - (see \sref{sec.stexarchives}) and have \mmt take care of - everything. - - Assuming the above file is |source/demo.tex| in - an \sTeX archive |MyTest|, you can run \mmt and - do - |build MyTest stex-omdoc demo.tex| to convert the - document to both |xhtml| (which you will find in - |xhtml/demo.xhtml| in the archive) and formal - \mmt/\omdoc, which you can subsequently view in - the \mmt browser (see \url{https://uniformal.github.io//doc/applications/server.html#the-mmt-web-site} - for details). - \end{sfragment} -\end{sfragment} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "stex-manual" -%%% End: - -% LocalWords: coloring sec.customhighlight realarith infinitesum realarithmetics |