diff options
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, 354 insertions, 0 deletions
diff --git a/macros/latex/contrib/stex/doc/stex-tutorial.tex b/macros/latex/contrib/stex/doc/stex-tutorial.tex new file mode 100644 index 0000000000..dcd4c442e0 --- /dev/null +++ b/macros/latex/contrib/stex/doc/stex-tutorial.tex @@ -0,0 +1,354 @@ + \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 |