\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}]
!$\Sigma$!
n
=
1
!$\infty$!
1
2
n
\end{lstlisting}
...containing all the semantic information. The \mmt system
can extract from this the following \openmath snippet:
\begin{lstlisting}[escapechar=!]
\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