summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/stex-tutorial.tex
blob: dcd4c442e00046281913ec125973568f68f3fe24 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
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