summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/stex-tutorial.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/stex/doc/stex-tutorial.tex')
-rw-r--r--macros/latex/contrib/stex/doc/stex-tutorial.tex354
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