diff options
author | Karl Berry <karl@freefriends.org> | 2022-09-14 19:58:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-09-14 19:58:16 +0000 |
commit | 17b3bbda651c5296c1e222bb44b6a1d348a737bd (patch) | |
tree | e895b9d34f6ca6723d2b106d94fd0b334d31a9a4 /Master/texmf-dist/doc/latex/stex | |
parent | 732ae3fbb7543a76e6ed337dcc853e4dec34efbb (diff) |
stex (14sep22)
git-svn-id: svn://tug.org/texlive/trunk@64383 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/stex')
24 files changed, 964 insertions, 380 deletions
diff --git a/Master/texmf-dist/doc/latex/stex/Makefile b/Master/texmf-dist/doc/latex/stex/Makefile index b727f2f94dd..7544a3c2fdc 100644 --- a/Master/texmf-dist/doc/latex/stex/Makefile +++ b/Master/texmf-dist/doc/latex/stex/Makefile @@ -2,7 +2,7 @@ STY = stex extensions SPATH = $(STY:%=../source/%) DTX = $(shell ls $(SPATH:%=%/*.dtx)) INS = $(shell ls $(SPATH:%=%/*.ins)) -DOC = stex-doc.pdf stex-manual.pdf +DOC = stex-doc.pdf stex-manual.pdf stex-ide.pdf TEXDIR = ../tex TEXINPUTS = $(TEXDIR)//: diff --git a/Master/texmf-dist/doc/latex/stex/img/vsc1.png b/Master/texmf-dist/doc/latex/stex/img/vsc1.png Binary files differnew file mode 100644 index 00000000000..c6c3847f692 --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/img/vsc1.png diff --git a/Master/texmf-dist/doc/latex/stex/img/vsc2.png b/Master/texmf-dist/doc/latex/stex/img/vsc2.png Binary files differnew file mode 100644 index 00000000000..e6365ad8024 --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/img/vsc2.png diff --git a/Master/texmf-dist/doc/latex/stex/img/vsc3.png b/Master/texmf-dist/doc/latex/stex/img/vsc3.png Binary files differnew file mode 100644 index 00000000000..d7b67ae278b --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/img/vsc3.png diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-document-structure.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-document-structure.tex index f8d570ea5e0..f2cabec6c08 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-document-structure.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-document-structure.tex @@ -1,3 +1,4 @@ +\begin{sfragment}[id=sec:ds:intro]{Introduction} The \pkg{document-structure} package supplies an infrastructure for writing {\omdoc} documents in {\LaTeX}. This includes a simple structure sharing mechanism for \sTeX that allows to to move from a copy-and-paste document development model to a copy-and-reference model, which @@ -17,7 +18,9 @@ after translation. DAG models of documents allow to replace the ``Copy and Paste'' in the source document with a label-and-reference model where document are shared in the document source and the formatter does the copying during document formatting/presentation. +\end{sfragment} +\begin{sfragment}{Package Options} The \pkg{document-structure} package accepts the following options: \begin{center} \begin{tabular}{|l|p{10cm}|}\hline @@ -26,7 +29,9 @@ The \pkg{document-structure} package accepts the following options: \meta{sect} is \texttt{section}\\\hline \end{tabular} \end{center} +\end{sfragment} +\begin{sfragment}{Document Fragments} \begin{environment}{sfragment} The structure of the document is given by nested |sfragment| environments. In the {\LaTeX} route, the |sfragment| environment is flexibly mapped to sectioning commands, @@ -36,8 +41,8 @@ The \pkg{document-structure} package accepts the following options: sfragment. The optional metadata argument has the keys |id| for an identifier, |creators| and |contributors| for the Dublin Core metadata~\cite{DCMI:dmt03}. The option |short| allows to give a short title for the generated section. If the title contains - semantic macros, they need to be protected by |\protect|\ednote{MK: still?}, and we need - to give the |loadmodules| key it needs no value. For instance we would have + semantic macros, we need to give the |loadmodules| key (it needs no value). For instance + we would have \begin{latexcode} \begin{smodule}{foo} \symdef{bar}{B^a_r} @@ -90,9 +95,8 @@ Here we use two levels of |blindfragment|: the introductory remarks become a ``chapter'' instead of a ``part''. \item The inner one groups the frontmatter\footnote{We shied away from redefining the |frontmatter| to induce a blindfragment, but this may be the ``right'' way to go in - the future.} and makes the preface of the book a section-level construct.\ednote{MK: - We need a substitute for the ``Note that here the |display=flow| on the |sfragment| - environment prevents numbering as is traditional for prefaces.''} + the future.} and makes the preface of the book a section-level construct. The + |frontmatter| environment also suppresses numbering as is traditional for prefaces. \end{itemize} \end{environment} @@ -110,11 +114,13 @@ Here we use two levels of |blindfragment|: will\ldots'' in an |sfragment| environment, where we do not know which sectioning level we will end up. \end{function} +\end{sfragment} +\begin{sfragment}{Ending Documents Prematurely} \begin{function}{\prematurestop,\afterprematurestop} For prematurely stopping the formatting of a document, \sTeX provides the |\prematurestop| macro. It can be used everywhere in a document and ignores all input - after that -- backing out of the |sfragment| environment as needed. After that -- and + after that -- backing out of the |sfragment| environments as needed. After that -- and before the implicit |\end{document}| it calls the internal |\afterprematurestop|, which can be customized to do additional cleanup or e.g. print the bibliography. @@ -132,7 +138,12 @@ instance, the admin section of a course can be made course-independent (and ther re-usable) by using variables (actually token registers) |courseAcronym| and |courseTitle| instead of the text itself. The variables can then be set in the \sTeX preamble of the course notes file. - +\end{sfragment} + +\begin{sfragment}{Global Document Variables} + To make document fragments more reusable, we sometimes want to make the content depend + on the context. We use \defemph{document variables} for that. + \begin{function}{\setSGvar,\useSGvar} |\setSGvar{|\meta{vname}|}{|\meta{text}|}| to set the global variable \meta{vname} to \meta{text} and |\useSGvar{|\meta{vname}|}| to reference it. @@ -144,6 +155,7 @@ course notes file. variable \meta{vname}, only if (after expansion) it is equal to \meta{val}, the conditional text \meta{ctext} is formatted. \end{function} +\end{sfragment} %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-features.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-features.tex index b5ce5906d15..4e0cd214576 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-features.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-features.tex @@ -144,8 +144,16 @@ and be a \symname{monoid} on $\Int$ ... } - We will return to these two example later, when we also know - how to handle the \emph{axioms} of a monoid. + +We will return to these two example later, when we also know how to handle the +\emph{axioms} of a monoid. + +\begin{environment}{usestructure} + The |usestructure{<struct>}| environment is used in multilingual settings as a parallel + to the |mathstructure|. It opens a group and then issues a + |\usemodule{.../<struct>-structure}| that gives the body access to all the semantic + macros in the referenced structure. +\end{environment} \end{smodule} \end{sfragment} diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-hwexam.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-hwexam.tex index 5aced96e664..a3679d0d948 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-hwexam.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-hwexam.tex @@ -1,15 +1,29 @@ - +\begin{sfragment}{Introduction} The \pkg{hwexam} package and class supplies an infrastructure that allows to format nice-looking assignment sheets by simply including problems from problem files marked up -with the \pkg{roblem} package. It is designed to be compatible with |problems.sty|, and +with the \pkg{problem} package. It is designed to be compatible with |problems.sty|, and inherits some of the functionality. +\end{sfragment} +\begin{sfragment}{Package Options} \begin{variable}{solutions,notes,hints,gnotes,pts,min} - The \pkg{wexam} package and class take the options |solutions|, |notes|, |hints|, + The \pkg{hwexam} package and class take the options |solutions|, |notes|, |hints|, |gnotes|, |pts|, |min|, and |boxed| that are just passed on to the \pkg{problems} package (cf. its documentation for a description of the intended behavior). \end{variable} +Furthermore, the \pkg{hwexam} package takes the option +\DescribeMacro{multiple}|multiple| that allows to combine multiple assignment sheets +into a compound document (the assignment sheets are treated as section, there is a table +of contents, etc.). + +Finally, there is the option \DescribeMacro{test}|test| that modifies the behavior to +facilitate formatting tests. Only in |test| mode, the macros |\testspace|, +|\testnewpage|, and |\testemptypage| have an effect: they generate space for the +students to solve the given problems. Thus they can be left in the {\LaTeX} source. +\end{sfragment} + +\begin{sfragment}{Assignments} This package supplies the \DescribeEnv{assignment}|assignment| environment that groups problems into assignment sheets. It takes an optional KeyVal argument with the keys \DescribeMacro{number}|number| (for the assignment number; if none is given, 1 is @@ -19,23 +33,22 @@ is referenced in the title of the assignment sheet), \DescribeMacro{type}|type| assignment type; e.g. ``quiz'', or ``homework''), \DescribeMacro{given}|given| (for the date the assignment was given), and \DescribeMacro{due}|due| (for the date the assignment is due). +\end{sfragment} -Furthermore, the \pkg{hwexam} package takes the option -\DescribeMacro{multiple}|multiple| that allows to combine multiple assignment sheets -into a compound document (the assignment sheets are treated as section, there is a table -of contents, etc.). - -Finally, there is the option \DescribeMacro{test}|test| that modifies the behavior to -facilitate formatting tests. Only in |test| mode, the macros |\testspace|, -|\testnewpage|, and |\testemptypage| have an effect: they generate space for the -students to solve the given problems. Thus they can be left in the {\LaTeX} source. +\begin{sfragment}{Including Assignments} +\begin{function}{\inputassignment} + The |\inputassignment| macro can be used to input an assignment from another file. It + takes an optional KeyVal argument and a second argument which is a path to the file + containing the problem (the macro assumes that there is only one |assignment| + environment in the included file). The keys |number|, |title|, |type|, |given|, and + |due| are just as for the |assignment| environment and (if given) overwrite the ones + specified in the |assignment| environment in the included file. +\end{function} +\end{sfragment} -\DescribeMacro{\testspace}|\testspace| takes an argument that expands to a dimension, -and leaves vertical space accordingly. \DescribeMacro{\testnewpage}|\testnewpage| makes -a new page in |test| mode, and \DescribeMacro{\testemptypage}|\testemptypage| generates -an empty page with the cautionary message that this page was intentionally left empty. +\begin{sfragment}{Typesetting Exams} -Finally, the \DescribeEnv{testheading}|\testheading| takes an optional keyword argument +The \DescribeEnv{testheading}|\testheading| takes an optional keyword argument where the keys \DescribeMacro{duration}|duration| specifies a string that specifies the duration of the test, \DescribeMacro{min}|min| specifies the equivalent in number of minutes, and \DescribeMacro{reqpts}|reqpts| the points that are required for a perfect @@ -68,17 +81,12 @@ Will result in \end{center} \ednote{MK: The first three ``problems'' come from the stex examples above, how do we get rid of this?} - -\begin{function}{\inputassignment} - The |\inputassignment| macro can be used to input an assignment from another file. It - takes an optional KeyVal argument and a second argument which is a path to the file - containing the problem (the macro assumes that there is only one |assignment| - environment in the included file). The keys |number|, |title|, |type|, |given|, and - |due| are just as for the |assignment| environment and (if given) overwrite the ones - specified in the |assignment| environment in the included file. -\end{function} +\end{sfragment} %%% Local Variables: %%% mode: latex %%% TeX-master: "../stex-manual" %%% End: + +% LocalWords: hwexam solutions,notes,hints,gnotes,pts,min gnotes testemptypage reqpts +% LocalWords: inputassignment reqpts hour,min 60,reqpts diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-idesetup.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-idesetup.tex new file mode 100644 index 00000000000..b4d495b6281 --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-idesetup.tex @@ -0,0 +1,61 @@ +\begin{sfragment}{Setting up the \sTeX IDE} + + The \sTeX IDE consists of two components using the + \emph{Language Server Protocol (LSP)}: A \emph{client} + in the form of a VSCode extension, and a \emph{server} + included in the \mmt system. Installing the extension will + open up a setup routine that will guide you through the rest. + + \begin{sfragment}{The \sTeX VSCode Extension} + + If you have not already, you should first install the VSCode editor + available at \url{https://code.visualstudio.com/}. + + Next, open VSCode and install the \sTeX extension by clicking on + the \emph{extensions} menu on the very left of the VSCode window + and searching for ``sTeX'' in the + \emph{``Search Extensions in Marketplace''} field, as in + \autoref{fig:install}, and clicking the \emph{Install}-button + of the \sTeX extension by KWARC. + + \begin{figure} + \begin{center} + \includegraphics[width=0.6\textwidth]{img/vsc1.png} + \end{center} + \caption{Installing the \sTeX extension for VSCode}\label{fig:install} + \end{figure} + + \end{sfragment} + + \begin{sfragment}{Setting up \mmt} + + Next, open any directory (\texttt{File $\to$ Open Folder...}) that contains + a \verb|.tex|-file, and a setup window as in \autoref{fig:setup} + will pop up. Clik on the highlighted link `\emph{here}' and download + the latest version of the \texttt{MMT.jar} file (at least version 23.0.0) + anywhere you like. Then click the \emph{``Browse...''}-button + and select your freshly downloaded \texttt{MMT.jar}. + + If you have already set a system variable for your MathHub-directory, + you are now done and can click \emph{``Finish''}. If you have not, + you can now also enter a directory path in the lower text field, + and the VSCode extension will attempt to globally set one up + for you, depending on your operating system. + + \begin{figure} + \begin{center} + \includegraphics[width=\textwidth]{img/vsc2.png} + \end{center} + \caption{\sTeX Setup Routine}\label{fig:setup} + \end{figure} + + Once you click \emph{``Finish''}, the client will connect + to \url{https://stexmmt.mathhub.info/:sTeX}, query for + available archives, download the core libraries required + for all (or most) semantic services (\texttt{MMT/urtheories} + and \texttt{sTeX/meta-inf}) and set up \RusTeX for you + automatically. + + \end{sfragment} + + \end{sfragment}
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex index fb872acfbad..eb09414ac74 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhub.tex @@ -1,4 +1,4 @@ -\begin{sfragment}{The Local MathHub-Directory} +\begin{sfragment}[id=sec:localmh]{The Local MathHub-Directory} \stexcode"\usemodule", \stexcode"\importmodule", \stexcode"\inputref" etc. allow for including content modularly without having to specify absolute diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-mathhubsetup.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhubsetup.tex new file mode 100644 index 00000000000..7a653186b3e --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-mathhubsetup.tex @@ -0,0 +1,25 @@ + \begin{sfragment}{Setting your MathHub Directory} + One of \sTeX's features is a proper \emph{module system} + of interconnected document snippets for mathematical + content. Analogously to \emph{object-oriented programming}, + it allows for ``object-oriented mathematics'' via individual + combinable and, importantly, \emph{reusable} modules, developed + collaboratively. + + To make use of such modules, the \sTeX system needs to be told + where to find them. There are several ways to do so (see + \sref[file=stex-mathhub]{sec:localmh}[in=../stex-manual, + title={\href{\basedocurl/stex-manual.pdf}{the \sTeX{}3 Manual}}]), + but the most convenient way to do so is via a system variable. + + To do so, create a directory \texttt{MathHub} somewhere on + your local file system and set the environment + variable \texttt{MATHHUB} to the file path to that directory. + + In linux, you can do so by writing + \begin{lstlisting}[language=bash] + export MATHHUB="/path/to/your/MathHub" + \end{lstlisting} + in your \verb|~/.profile| (for all shells) or \verb|~/.bashrc| + (for the bash terminal only) file. + \end{sfragment}
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-slides.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-notesslides.tex index a900c1fcbb8..75fd9ee9e8e 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-slides.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-notesslides.tex @@ -1,4 +1,5 @@ -The \pkg{notesslides} document class is derived from |beamer.cls|~\cite{beamerclass:on}, +\begin{sfragment}{Introduction} + The \pkg{notesslides} document class is derived from |beamer.cls|~\cite{beamerclass:on}, it adds a ``notes version'' for course notes that is more suited to printing than the one supplied by |beamer.cls|. @@ -14,27 +15,36 @@ In practice we want to generate two documents from the same source: the slides f presentation in the lecture and the course notes as a narrative document for home study. To achieve this, the \pkg{notesslides} class has two modes: \emph{slides mode} and \emph{notes mode} which are determined by the package option. +\end{sfragment} + +\begin{sfragment}{Package Options} + The \pkg{notesslides} class takes a variety of class options: + + \begin{variable}{slides,notes} The options |slides| and |notes| switch between slides + mode and notes mode (see \sref{sec:user:notesslides}). + \end{variable} + + \begin{variable}{sectocframes} If the option |sectocframes| is given, then for the + |sfragment|s, special frames with the |sfragment| title (and number) are generated. + \end{variable} + \begin{variable}{frameimages,fiboxed} + If the option |frameimages| is set, then slide mode also shows the + |\frameimage|-generated frames (see \sref{sec:user:frameimage}). If also the |fiboxed| + option is given, the slides are surrounded by a box. + \end{variable} +\end{sfragment} + +\begin{sfragment}[id=sec:user:notesslides]{Notes and Slides} -\begin{variable}{slides,notes,sectocframes,frameimages,fiboxed} - The \pkg{notesslides} class takes a variety of class options: - \begin{itemize} - \item The options |slides| and |notes| switch between slides mode and notes mode (see - Section~\ref{sec:user:notesslides}). - \item If the option |sectocframes| is given, then for the |sfragment|s, special frames - with the |sfragment| title (and number) are generated. - \item If the option |frameimages| is set, then slide mode also shows the - |\frameimage|-generated frames (see section~\ref{sec:user:frameimage}). If also the - |fiboxed| option is given, the slides are surrounded by a box. - \end{itemize} -\end{variable} - -\begin{environment}{frame,note} +\begin{environment}{frame} Slides are represented with the |frame| environment just like in the \pkg{beamer} class, - see~\cite{Tantau:ugbc} for details. The \pkg{notesslides} class adds the |note| - environment for encapsulating the course note fragments.\footnote{MK: it would be very - nice, if we did not need this environment, and this should be possible in principle, - but not without intensive LaTeX trickery. Hints to the author are welcome.} + see~\cite{Tantau:ugbc} for details. +\end{environment} + +\begin{environment}{note} + The \pkg{notesslides} class adds the |note| environment for encapsulating the course + note fragments. \end{environment} \begin{dangerbox} @@ -86,6 +96,7 @@ here: least in conjunction with |\newpage|, frame numbering behaves funnily (we have tried to fix this, but who knows). \end{dangerbox} +\end{sfragment} \begin{function}{\inputref*} If we want to transclude a the contents of a file as a note, we can use a new variant @@ -101,6 +112,17 @@ here: |ndefinition|, |nexample|, |nsproof|, and |nassertion| environments. \end{environment} +\begin{sfragment}{Customizing Header and Footer Lines} + The \pkg{notesslides} package and class comes with a simple default theme named + \pkg{sTeX} that provided by the \pkg{beamterthemesTeX}. It is assumed as the default + theme for \sTeX-based notes and slides. + The result in |notes| mode (which is like the |slides| version except that the slide + hight is variable) is + + \includegraphics[width=.95\textwidth]{\libfolder{img/notes-frame}} + +The footer line can be customized. In particular the logos. + \begin{function} {\setslidelogo} The default logo provided by the \pkg{notesslides} package is the {\sTeX} logo it can be customized using |\setslidelogo{|\meta{logo name}|}|. @@ -108,10 +130,9 @@ here: \begin{function}{\setsource} The default footer line of the \pkg{notesslides} package mentions copyright and - licensing. In the \pkg{beamer} class, |\source| stores the author's name as the - copyright holder . By default it is \emph{Michael Kohlhase} in the \pkg{notesslides} - package since he is the main user and designer of this - package. |\setsource{|\meta{name}|}| can change the writer's name. + licensing. In \pkg{notesslides} |\source| stores the author's name as the copyright + holder. By default it is the author's name as defined in the |\author| macro in the + preamble. |\setsource{|\meta{name}|}| can change the writer's name. \end{function} \begin{function}{\setlicensing} @@ -120,8 +141,10 @@ here: hyperlink to the license logo. |\setlicensing[|\meta{url}|]{|\meta{logo name}|}| is used for customization, where \meta{url} is optional. \end{function} +\end{sfragment} -Sometimes, we want to integrate slides as images after all -- e.g. because we already +\begin{sfragment}[id=sec:user:frameimages]{Frame Images} + Sometimes, we want to integrate slides as images after all -- e.g. because we already have a PowerPoint presentation, to which we want to add \sTeX notes. \begin{function}{\frameimage,\mhframeimage} @@ -150,21 +173,28 @@ argument is redundant, so we can just use \begin{latexcode} \mhframeimage{baz/foobar} \end{latexcode} +\end{sfragment} \begin{function}{\textwarning} The |\textwarning| macro generates a warning sign: \textwarning \end{function} +\begin{sfragment}[id=sec:user:excursions]{Excursions} In course notes, we sometimes want to point to an ``excursion'' -- material that is either presupposed or tangential to the course at the moment -- e.g. in an appendix. The typical setup is the following: \begin{latexcode} -\excursion{founif}{../ex/founif}{We will cover first-order unification in} +\excursion{founif}{../fragments/founif.en} + {We will cover first-order unification in} ... \begin{appendix}\printexcursions\end{appendix} \end{latexcode} +It generates a paragraph that references the excursion whose source is in the file +|../fragments/founif.en.tex| and automatically books the file for the |\printexcursions| +command that is used here to put it into the appendix. We will look at the mechanics now. + \begin{function}{\excursion} The |\excursion{|\meta{ref}|}{|\meta{path}|}{|\meta{text}|}| is syntactic sugar for @@ -198,6 +228,7 @@ setup is the following: \end{note} \end{latexcode} \end{function} +\end{sfragment} \begin{dangerbox} When option |book| which uses |\pagestyle{headings}| is given and semantic macros are diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-problem.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-problem.tex index a90c36412d0..53316b28bc8 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-problem.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-problem.tex @@ -1,4 +1,5 @@ -The \pkg{problem} package supplies an infrastructure that allows specify problem. Problems +\begin{sfragment}{Introduction} + The \pkg{problem} package supplies an infrastructure that allows specify problem. Problems are text fragments that come with auxiliary functions: hints, notes, and solutions\footnote{for the moment multiple choice problems are not supported, but may well be in a future version}. Furthermore, we can specify how long the solution to a @@ -7,7 +8,11 @@ solution. Finally, the \pkg{problem} package facilitates the management of problems in small files, so that problems can be re-used in multiple environment. +\end{sfragment} + +\begin{sfragment}{Problems and Solutions} + \begin{function}{solutions,notes,hints,gnotes,pts,min,boxed,test} The \pkg{problem} package takes the options |solutions| (should solutions be output?), |notes| (should the problem notes be presented?), |hints| (do we give the hints?), @@ -43,7 +48,7 @@ so that problems can be re-used in multiple environment. \begin{exnote} Justify your answer \end{exnote} -\begin{solution}[for=elefants,height=3cm] +\begin{solution}[for=elefants] Four, two in the front seats, and two in the back. \begin{gnote} if they do not give the justification deduct 5 pts @@ -66,7 +71,7 @@ so that problems can be re-used in multiple environment. \begin{environment}{hint,exnote,gnote} The |hint| and |exnote| environments can be used in a |problem| environment to give hints and to make notes that elaborate certain aspects of the problem. The |gnote| - (grading notes) environment can be used to document situtations that may arise in + (grading notes) environment can be used to document situations that may arise in grading. \end{environment} @@ -80,7 +85,22 @@ so that problems can be re-used in multiple environment. Also, sometimes, we want content (e.g. in an exam with master solutions) conditional on whether solutions are shown. This can be done with the |\ifsolutions| conditional. \end{function} +\end{sfragment} + +\begin{sfragment}{Markup for Added-Value Services} + +\begin{sparagraph} + The |problem| package is all about specifying the meaning of the various moving parts of + practice/exam problems. The motivation for the additional markup is that we can base + added-value services from these, for instance auto-grading and immediate feedback. + The simplest example of this are multiple-choice problems, where the |problem| package + allows to annotate answer options with the intended values and possibly feedback that + can be delivered to the users in an interactive setting. In this section we will give + some infrastructure for these, we expect that this will grow over time. +\end{sparagraph} + +\begin{sfragment}{Multiple Choice Blocks} \begin{environment}{mcb} Multiple choice blocks can be formatted using the |mcb| environment, in which single choices are marked up with |\mcc| macro. @@ -96,8 +116,8 @@ so that problems can be re-used in multiple environment. \item |feedback| for a short feedback text given to the student. \end{itemize} \end{function} - -If we start the solutions, then we get +What we see when this is formatted to PDF depends on the context. In solutions mode (we +start the solutions in the code fragment below) we get \stexexample{% \startsolutions @@ -111,8 +131,8 @@ If we start the solutions, then we get \end{mcb} \end{sproblem} } -without solutions (that is what the students see during the exam/quiz)\ednote{MK: that did -not work!} + +In ``exam mode'' where disable solutions (here via |\stopsolutions|) \stexexample{% \stopsolutions \begin{sproblem}[title=Functions,name=functions1] @@ -125,7 +145,44 @@ not work!} \end{mcb} \end{sproblem} } - +we get the questions without solutions (that is what the students see during the +exam/quiz). +\end{sfragment} + +\begin{sfragment}{Filling-In Concrete Solutions} +The next simplest situation, where we can implement auto-grading is the case where we +have fill-in-the-blanks + +\begin{function}{\fillinsol} + The |\fillinsol| macro takes\Ednote{for now; more to come} an a single argument, which + contains a concrete solution (i.e. a number, a string, \ldots), which generates a + fill-in-box in test mode: +\stexexample{% + \stopsolutions + \begin{sproblem}[id=elefants.fillin,title=Fitting Elefants] + How many Elefants can you fit into a Volkswagen beetle? \fillinsol{4} +\end{sproblem}} + and the actual solution in solutions mode: +\end{function} +\stexexample{% + \begin{sproblem}[id=elefants.fillin,title=Fitting Elefants] + How many Elefants can you fit into a Volkswagen beetle? \fillinsol{4} + \end{sproblem}} +If we do not want to leak information about the solution by the size of the blank we can +also give |\fillinsol| an optional argument with a size: |\fillinsol[3cm]{12}| makes a box + three cm wide. + + Obviously, the required argument of |\fillinsol| can be used for auto-grading. For + concrete data like numbers, this is immediate, for more complex data like strings ``soft + comparisons'' might be in order. \ednote{For the moment we only assume a single concrete + value as correct. In the future we will almost certainly want to extend the + functionality to multiple answer classes that allow different feedback like im + MCQ. This still needs a bit of design. Also we want to make the formatting of the + answer in solutions/test mode configurable.} +\end{sfragment} +\end{sfragment} + +\begin{sfragment}{Including Problems} \begin{function}{\includeproblem} The |\includeproblem| macro can be used to include a problem from another file. It takes an optional KeyVal argument and a second argument which is a path to the file containing @@ -144,8 +201,32 @@ The |\min| and |\pts| macros allow to specify (i.e. to print to the margin) the distribution of time and reward to parts of a problem, if the |pts| and |pts| options are set. This allows to give students hints about the estimated time and the points to be awarded. +\end{sfragment} + +\begin{sfragment}{Testing and Spacing} +The |problem| package is often used by the |hwexam| package, which is used to create +homework assignments and exams. Both of these have a ``test mode'' (invoked by the +package option |test|), where certain information --master solutions or feedback -- is +not shown in the presentation. + +\DescribeMacro{\testspace}|\testspace| takes an argument that expands to a dimension, and +leaves vertical space accordingly. Specific instances exist: +\DescribeMacro{\testsmallspace}|\testsmallspace|, +\DescribeMacro{\testsmallspace}|\testsmallspace|, +\DescribeMacro{\testsmallspace}|\testsmallspace| give small (1cm), medium (2cm), and big (3cm) +vertical space. + +\DescribeMacro{\testnewpage}|\testnewpage| makes a new page in |test| mode, and +\DescribeMacro{\testemptypage}|\testemptypage| generates an empty page with the cautionary +message that this page was intentionally left empty. +\end{sfragment} %%% Local Variables: %%% mode: latex %%% TeX-master: "../stex-manual" %%% End: + +% LocalWords: solutions,notes,hints,gnotes,pts,min,boxed,test gnotes elefants,pts gnote +% LocalWords: 2,title exnote hint,exnote,gnote ifsolutions mcb keyvals Ttext Ftext +% LocalWords: Functions,name F,feedback Nooooooooo,feedback 2,title includeproblem +% LocalWords: elefants.fillin,title diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-proofs.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-proofs.tex index d06db1282f5..9e6e44f5ca2 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-proofs.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-proofs.tex @@ -1,100 +1,308 @@ +\begin{sfragment}{Proofs} + The \pkg{stex-proof} package supplies macros and environment that allow to annotate the structure of mathematical proofs in \sTeX document. This structure can be used by MKM systems for added-value services, either directly from the \sTeX sources, or after translation. -We will go over the general intuition by way of a running example: +Its central component is the |sproof|-environment, whose body consists +of: +\begin{itemize} + \item \emph{subproofs} via the |subproof|-environment, + \item \emph{proof steps} via the |\spfstep|, |\eqstep| + |\assumption|, and |\conclude| macros, and + \item \emph{comments}, via normal text without special markup. +\end{itemize} + +|sproof|, |subproof| and the various proof step macros take the following +optional arguments: +\begin{itemize} + \item[|id|] (\meta{string}) for referencing, + \item[|method|] (\meta{string}) the proof method (e.g. contradiction, induction,...) + \item[|term|] (\meta{token list}) the (ideally semantically-marked up) + proposition that is derived/proven by this proof/subproof/proof step. +\end{itemize} +Additionally, they take one mandatory argument for the document text +to be annotated, or (in the case of the environments) +as an introductory description of the proof itself. Since +the latter often contains the |term| to be derived +as text, alternatively to providing it as +an optional argument, the mandatory argument can use the +|\yield|-macro to mark it up in the text. + +The |sproof| and |subproof| environments additionally take +two optional arguments: +\begin{itemize} + \item[|for|] the symbol identifier/name corresponding to the |sassertion| + to be proven. This too subsumes |\yield| and the |term|-argument. + \item[|hide|] In the pdf, this only shows the mandatory argument text + and hides the body of the environment. In the HTML (as served by \mmt), + the bodies of all |proof| and |subproof| environments are \emph{collapsible}, + and |hide| collapses the body by default. +\end{itemize} + +\begin{smodule}{sproofs} + \symdef{coprime}[args=2]{#1 \comp\bot #2} + \symdef{realroot}[args=1]{\sqrt{#1}} + \symdecl{irrational}[args=1] + \symdecl{rational}[args=1] + \symdef{eq}[args=2]{#1 \comp= #2} + \symdef{ratfrac}[args=2,prec=1]{\frac{#1}{#2}} + \symdef{intpow}[args=2,prec=-1]{{#1}^{#2}} + \symdef{ratpow}[args=2]{{#1}^{#2}} + \symdef{inset}[args=ai]{#1\comp\in#2}{##1\comp,##2} + \symdef{Int}{\comp{\mathbb Z}} + \symdef{PosInt}{\comp{{\mathbb Z}^+}} + \symdef{inttimes}[args=2]{#1 #2} + \symdef{divides}[args=2]{#1\comp\|#2} + + \vardef{vara}{\comp a} + \vardef{varb}{\comp b} + \vardef{varc}{\comp c} + + \def\contradiction{} \begin{latexcode} -\begin{sproof}[id=simple-proof] + \begin{sassertion}[type=theorem,name=sqrt2irr] + \conclusion{\irrational{$\arg{\realroot{2}}$ is \comp{irrational}}}. +\end{sassertion} + +\begin{sproof}[for=sqrt2irr,method=contradiction]{By contradiction} + \assumption{Assume \yield{\rational{$\arg{\realroot{2}}$ is + \comp{rational}}}} + \begin{subproof}[method=straightforward]{Then + \yield{$\eq{\ratfrac{\intpow{\vara}{2}}{\intpow{\varb}2}}{2}$ + for some $\inset{\vara,\varb}\PosInt$ with + \coprime{$\arg{\vara},\arg{\varb}$ \comp{coprime}}}} + \assumption{By assumption, \yield{there are + $\inset{\vara,\varb}\PosInt $ with + $\realroot{2}=\ratfrac{\vara}{\varb}$}} + \spfstep{wlog, we can assume \coprime{$\arg{\vara},\arg{\varb}$ + to be \comp{coprime}}} + % a comment: + If not, reduce the fraction until numerator and denominator + are coprime, and let the resulting components be + $\vara $ and $\varb $ + \spfstep{Then \yield{$\eq{\intpow{\ratfrac{\vara}{\varb}}2}2$}} + \eqstep{\ratfrac{\intpow{\vara}2}{\intpow{\varb}2}} + \end{subproof} + \begin{subproof}[term=\divides{2}{\vara},method=straightforward]{ + Then $\vara $ is even} + \spfstep{Multiplying the equation by $\intpow{\varb}2$ yields + $\yield{\eq{\intpow{\vara}2}{\inttimes{2}{\intpow{\varb}2}}}$} + \spfstep[term=\divides{2}{\intpow{\vara}2}]{Hence + $\intpow{\vara}2$ is even} + \conclude[term=\divides{2}{\vara}]{Hence $\vara $ is even as well} + % another comment: + Hint: Think about the prime factorizations of $\vara $ and + $\intpow{\vara}2$ + \end{subproof} + \begin{subproof}[term=\divides{2}{\varb},method=straightforward,]{ + Then $\varb $ is also even} + \spfstep{Since $\vara $ is even, we have \yield{some $\varc $ + such that $\eq{\inttimes{2}{\varc}}{\vara}$}} + \spfstep{Plugging into the above, we get + \yield{$\eq{\intpow{\inttimes{2}{\vara}}2} + {\inttimes{2}{\intpow{\varb}2}}$}} + \eqstep{\inttimes{4}{\intpow{\vara}2}} + \spfstep{Dividing both sides by $2$ yields + \yield{$\eq{\intpow{\varb}2}{\inttimes{2}{\intpow{\vara}2}}$}} + \spfstep[term=\divides{2}{\intpow{\varb}2}]{Hence + $\intpow{\varb}2$ is even} + \conclude[term=\divides{2}{\varb}]{Hence $\varb $ is even} + % one more comment: + By the same argument as above + \end{subproof} + \conclude[term=\contradiction]{Contradiction to $\vara,\varb $ being + \symname{coprime}.} +\end{sproof} +\end{latexcode} + +which will produce: + +\begin{mdframed} +\begin{sassertion}[type=theorem,name=sqrt2irr] + \conclusion{\irrational{$\arg{\realroot2}$ is \comp{irrational}}}. +\end{sassertion} + +\begin{sproof}[for=sqrt2irr,method=contradiction]{By contradiction} + \assumption{Assume \yield{\rational{$\arg{\realroot2}$ is \comp{rational}}}} + \begin{subproof}[method=straightforward]% + {Then \yield{$\eq{\ratfrac{\intpow \vara2}{\intpow \varb2}}{2}$ for some $\inset{\vara,\varb}\PosInt$ with \coprime{$\arg \vara,\arg \varb$ \comp{coprime}}}} + \assumption{By assumption, \yield{there are $\inset{\vara,\varb}\PosInt$ with $\realroot2=\ratfrac\vara\varb$}} + \spfstep{wlog, we can assume \coprime{$\arg{\vara},\arg{\varb}$ to be \comp{coprime}}} + If not, reduce the fraction until numerator and denominator are + coprime, and let the resulting components be $\vara$ and $\varb$ + \spfstep{Then \yield{$\eq{\intpow{\ratfrac\vara\varb}2}2$}} + \eqstep{\ratfrac{\intpow\vara2}{\intpow\varb2}} + \end{subproof} + \begin{subproof}[term=\divides{2}{\vara},method=straightforward]{Then $\vara$ is even} + \spfstep{Multiplying the equation by $\intpow\varb2$ yields $\yield{\eq{\intpow\vara2}{\inttimes2{\intpow\varb2}}}$} + \spfstep[term=\divides{2}{\intpow\vara2}]{Hence $\intpow\vara2$ is even} + \conclude[term=\divides{2}{\vara}]{Hence $\vara$ is even as well} + Hint: Think about the prime factorizations of $\vara$ and $\intpow\vara2$ + \end{subproof} + \begin{subproof}[term=\divides{2}{\varb},method=straightforward]{Then $\varb$ is also even} + \spfstep{Since $\vara$ is even, we have \yield{some $\varc$ such that $\eq{\inttimes2\varc}{\vara}$}} + \spfstep{Plugging into the above, we get \yield{$\eq{\intpow{\inttimes2\vara}2}{\inttimes2{\intpow\varb2}}$}} + \eqstep{\inttimes4{\intpow\vara2}} + \spfstep{Dividing both sides by $2$ yields \yield{$\eq{\intpow\varb2}{\inttimes2{\intpow\vara2}}$}} + \spfstep[term=\divides{2}{\intpow\varb2}]{Hence $\intpow\varb2$ is even} + \conclude[term=\divides{2}{\varb}]{Hence $\varb$ is even} + By the same argument as above + \end{subproof} + \conclude[term=\contradiction]{Contradiction to $\vara,\varb$ being \symname{coprime}.} +\end{sproof} +\end{mdframed} + +If we mark all subproofs with |hide|, we will obtain the following +instead: + +\begin{mdframed} + \begin{sassertion}[type=theorem,name=sqrt2irr] + \conclusion{\irrational{$\arg{\realroot2}$ is \comp{irrational}}}. + \end{sassertion} + + \begin{sproof}[for=sqrt2irr,method=contradiction]{By contradiction} + \assumption{Assume \yield{\rational{$\arg{\realroot2}$ is \comp{rational}}}} + \begin{subproof}[hide,method=straightforward]% + {Then \yield{$\eq{\ratfrac{\intpow \vara2}{\intpow \varb2}}{2}$ for some $\inset{\vara,\varb}\PosInt$ with \coprime{$\arg \vara,\arg \varb$ \comp{coprime}}}} + \assumption{By assumption, \yield{there are $\inset{\vara,\varb}\PosInt$ with $\realroot2=\ratfrac\vara\varb$}} + \spfstep{wlog, we can assume \coprime{$\arg{\vara},\arg{\varb}$ to be \comp{coprime}}} + If not, reduce the fraction until numerator and denominator are + coprime, and let the resulting components be $\vara$ and $\varb$ + \spfstep{Then \yield{$\eq{\intpow{\ratfrac\vara\varb}2}2$}} + \eqstep{\ratfrac{\intpow\vara2}{\intpow\varb2}} + \end{subproof} + \begin{subproof}[hide,term=\divides{2}{\vara},method=straightforward]{Then $\vara$ is even} + \spfstep{Multiplying the equation by $\intpow\varb2$ yields $\yield{\eq{\intpow\vara2}{\inttimes2{\intpow\varb2}}}$} + \spfstep[term=\divides{2}{\intpow\vara2}]{Hence $\intpow\vara2$ is even} + \conclude[term=\divides{2}{\vara}]{Hence $\vara$ is even as well} + Hint: Think about the prime factorizations of $\vara$ and $\intpow\vara2$ + \end{subproof} + \begin{subproof}[hide,term=\divides{2}{\varb},method=straightforward,]{Then $\varb$ is also even} + \spfstep{Since $\vara$ is even, we have \yield{some $\varc$ such that $\eq{\inttimes2\varc}{\vara}$}} + \spfstep{Plugging into the above, we get \yield{$\eq{\intpow{\inttimes2\vara}2}{\inttimes2{\intpow\varb2}}$}} + \eqstep{\inttimes4{\intpow\vara2}} + \spfstep{Dividing both sides by $2$ yields \yield{$\eq{\intpow\varb2}{\inttimes2{\intpow\vara2}}$}} + \spfstep[term=\divides{2}{\intpow\varb2}]{Hence $\intpow\varb2$ is even} + \conclude[term=\divides{2}{\varb}]{Hence $\varb$ is even} + By the same argument as above + \end{subproof} + \conclude[term=\contradiction]{Contradiction to $\vara,\varb$ being \symname{coprime}.} + \end{sproof} + \end{mdframed} + + However, the hidden subproofs will still be shown in the HTML, + only in an expandable section which is collapsed by default. + + +The above style of writing proofs is usually called \emph{structured proofs}. +They have a huge advantage over the traditional purely prosaic style, +in that (as the name suggests) the actual \emph{structure} of the proof +is made explicit, which almost always makes it considerably more +comprehensible. We, among many others, encourage the general use of +structured proofs. + +Alas, most proofs are not written in this style, and we would +do users a disservice by insisting on this style. For that reason, +the |spfblock| environment turns all subproofs and proof step +macros into presentationally neutral \emph{inline} annotations, +as in the induction step of the following example: + +\begin{latexcode} +\begin{sproof}[id=simple-proof,method=induction] {We prove that $\sum_{i=1}^n{2i-1}=n^{2}$ by induction over $n$} - \begin{spfcases}{For the induction we have to consider three cases:} - \begin{spfcase}{$n=1$} - \begin{spfstep}[type=inline] then we compute $1=1^2$\end{spfstep} - \end{spfcase} - \begin{spfcase}{$n=2$} - \begin{spfcomment}[type=inline] + For the induction we have to consider three cases: % <- a comment + \begin{subproof}{$n=1$} + \spfstep*{then we compute $1=1^2$} + \end{subproof} + \begin{subproof}{$n=2$} This case is not really necessary, but we do it for the fun of it (and to get more intuition). - \end{spfcomment} - \begin{spfstep}[type=inline] We compute $1+3=2^{2}=4$.\end{spfstep} - \end{spfcase} - \begin{spfcase}{$n>1$} - \begin{spfstep}[type=assumption,id=ind-hyp] + \spfstep*{We compute $1+3=2^{2}=4$.} + \end{subproof} + \begin{subproof}{$n>1$}\begin{spfblock} + \assumption[id=ind-hyp]{ Now, we assume that the assertion is true for a certain $k\geq 1$, - i.e. $\sum_{i=1}^k{(2i-1)}=k^{2}$. - \end{spfstep} - \begin{spfcomment} + i.e. \yield{$\sum_{i=1}^k{(2i-1)}=k^{2}$}. + } + We have to show that we can derive the assertion for $n=k+1$ from this assumption, i.e. $\sum_{i=1}^{k+1}{(2i-1)}=(k+1)^{2}$. - \end{spfcomment} - \begin{spfstep} - We obtain $\sum_{i=1}^{k+1}{2i-1}=\sum_{i=1}^k{2i-1}+2(k+1)-1$ - \spfjust[method=arith:split-sum]{by splitting the sum}. - \end{spfstep} - \begin{spfstep} - Thus we have $\sum_{i=1}^{k+1}{(2i-1)}=k^2+2k+1$ - \spfjust[method=fertilize]{by inductive hypothesis}. - \end{spfstep} - \begin{spfstep}[type=conclusion] - We can \spfjust[method=simplify]{simplify} the right-hand side to + + \spfstep{ + We obtain $\yield{\sum_{i=1}^{k+1}{2i-1}= + \sum_{i=1}^k{2i-1}+2(k+1)-1}$ + \spfjust{by \splitsum{\comp{splitting the sum} + \arg*{$\sum_{i=1}^{k+1}{(2i-1)}=(k+1)^{2}$}}}. + } + \spfstep{ + Thus we have $\yield{\sum_{i=1}^{k+1}{(2i-1)}=k^2+2k+1}$ + \spfjust{by \symname{induction-hypothesis}}. + } + \conclude{ + We can \spfjust{\simplification{\comp{simplify} the right-hand side + \arg*{k^2+2k+1}}} to ${k+1}^2$, which proves the assertion. - \end{spfstep} - \end{spfcase} - \begin{spfstep}[type=conclusion] + } + \end{spfblock}\end{subproof} + \conclude{ We have considered all the cases, so we have proven the assertion. - \end{spfstep} - \end{spfcases} + } \end{sproof} \end{latexcode} + +\symdecl{splitsum}[args=1] +\symdecl{inducthypothesis}[name=induction-hypothesis] +\symdecl{simplification}[args=1] + This yields the following result: \begin{mdframed} - \begin{sproof}[id=simple-proof] - {We prove that $\sum_{i=1}^n{2i-1}=n^{2}$ by induction over $n$} - \begin{spfcases}{For the induction we have to consider the following cases:} - \begin{spfcase}{$n=1$} - \begin{spfstep}[type=inline] then we compute $1=1^2$\end{spfstep} - \end{spfcase} - \begin{spfcase}{$n=2$} - \begin{spfcomment}[type=inline] - This case is not really necessary, but we do it for the fun - of it (and to get more intuition). - \end{spfcomment} - \begin{spfstep}[type=inline] - We compute $1+3=2^{2}=4$ - \end{spfstep} - \end{spfcase} - \begin{spfcase}{$n>1$} - \begin{spfstep}[type=hypothesis,id=ind-hyp] - Now, we assume that the assertion is true for a certain $k\geq 1$, i.e. - $\sum_{i=1}^k{(2i-1)}=k^{2}$. - \end{spfstep} - \begin{spfcomment} - We have to show that we can derive the assertion for $n=k+1$ from this - assumption, i.e. $\sum_{i=1}^{k+1}{(2i-1)}=(k+1)^{2}$. - \end{spfcomment} - \begin{spfstep}[id=splitit] - We obtain $\sum_{i=1}^{k+1}{(2i-1)}=\sum_{i=1}^k{(2i-1)}+2(k+1)-1$ - \spfjust[method=arith:split-sum]{by splitting the sum}. - \end{spfstep} - \begin{spfstep}[id=byindhyp] - Thus we have $\sum_{i=1}^{k+1}{(2i-1)}=k^2+2k+1$ - \spfjust[method=fertilize]{by \premise[ind-hyp]{inductive hypothesis}}. - \end{spfstep} - \begin{spfstep}[type=conclusion] - We can \spfjust[method=simplify-eq]{simplify the \justarg[rhs]{right-hand side}} to - $(k+1)^2$, which proves the assertion. - \end{spfstep} - \end{spfcase} - \begin{spfstep}[type=conclusion] - We have considered all the cases, so we have proven the assertion. - \end{spfstep} - \end{spfcases} -\end{sproof} + \begin{sproof}[id=simple-proof,method=induction] + {We prove that $\sum_{i=1}^n{2i-1}=n^{2}$ by induction over $n$} + For the induction we have to consider three cases: % <- a comment + \begin{subproof}{$n=1$} + \spfstep*{then we compute $1=1^2$} + \end{subproof} + \begin{subproof}{$n=2$} + This case is not really necessary, but we do it for the + fun of it (and to get more intuition). + \spfstep*{We compute $1+3=2^{2}=4$.} + \end{subproof} + \begin{subproof}{$n>1$}\begin{spfblock} + \assumption[id=ind-hyp]{ + Now, we assume that the assertion is true for a certain $k\geq 1$, + i.e. \yield{$\sum_{i=1}^k{(2i-1)}=k^{2}$}. + } + + We have to show that we can derive the assertion for $n=k+1$ from + this assumption, i.e. $\sum_{i=1}^{k+1}{(2i-1)}=(k+1)^{2}$. + + \spfstep{ + We obtain $\yield{\sum_{i=1}^{k+1}{2i-1}=\sum_{i=1}^k{2i-1}+2(k+1)-1}$ + \spfjust{by \splitsum{\comp{splitting the sum}\arg*{$\sum_{i=1}^{k+1}{(2i-1)}=(k+1)^{2}$}}}. + } + \spfstep{ + Thus we have $\yield{\sum_{i=1}^{k+1}{(2i-1)}=k^2+2k+1}$ + \spfjust{by \symname{induction-hypothesis}}. + } + \conclude{ + We can \spfjust{\simplification{\comp{simplify} the right-hand side + \arg*{k^2+2k+1}}} to + ${k+1}^2$, which proves the assertion. + } + \end{spfblock}\end{subproof} + \conclude{ + We have considered all the cases, so we have proven the assertion. + } + \end{sproof} \end{mdframed} +\end{smodule} + \begin{environment}{sproof} The |sproof| environment is the main container for proofs. It takes an optional |KeyVal| argument that allows to specify the |id| (identifier) and |for| (for which assertion is @@ -114,78 +322,39 @@ This yields the following result: the proof. \end{function} -\begin{environment}{spfstep} - Regular proof steps are marked up with the |step| environment, which takes an optional +\begin{function}{\spfstep} + Regular proof steps are marked up with the |\spfstep| macro, which takes an optional |KeyVal| argument for annotations. A proof step usually contains a local assertion (the text of the step) together with some kind of evidence that this can be derived from already established assertions. -\end{environment} +\end{function} + +\begin{function}{\yield} + See above +\end{function} \begin{function}{\spfjust} This evidence is marked up with the |\spfjust| macro in the \pkg{stex-proofs} package. This environment totally invisible to the formatted result; it wraps the text - in the proof step that corresponds to the evidence. The environment takes an optional - |KeyVal| argument, which can have the |method| key, whose value is the name of a proof - method (this will only need to mean something to the application that consumes the - semantic annotations). Furthermore, the justification can contain ``premises'' - (specifications to assertions that were used justify the step) and ``arguments'' - (other information taken into account by the proof method). + in the proof step that corresponds to the evidence (ideally, a + semantically marked-up term). \end{function} -\begin{function}{\premise} - The |\premise| macro allows to mark up part of the text as reference to an assertion - that is used in the argumentation. In the running example we have used the |\premise| - macro to identify the inductive hypothesis. +\begin{function}{\assumption} + The |\assumption| macro allows to mark up a (justified) assumption. \end{function} \begin{function}{\justarg} - The |\justarg| macro is very similar to |\premise| with the difference that it is used - to mark up arguments to the proof method. Therefore the content of the first argument - is interpreted as a mathematical object rather than as an identifier as in the case of - |\premise|. In our example, we specified that the simplification should take place on - the right hand side of the equation. Other examples include proof methods that - instantiate. Here we would indicate the substituted object in a |\justarg| macro. \end{function} -Note that both |\premise| and |\justarg| can be used with an empty second argument to -mark up premises and arguments that are not explicitly mentioned in the text. - \begin{environment}{subproof} - The |spfcases| environment is used to mark up a subproof. This environment takes an + The |subproof| environment is used to mark up a subproof. This environment takes an optional |KeyVal| argument for semantic annotations and a second argument that allows to specify an introductory comment (just like in the |proof| environment). The |method| key can be used to give the name of the proof method executed to make this subproof. \end{environment} -\begin{environment}{spfcases} - The |spfcases| environment is used to mark up a proof by cases. Technically it is a - variant of the |subproof| where the |method| is |by-cases|. Its contents are |spfcase| - environments that mark up the cases one by one. -\end{environment} - -\begin{environment}{spfcase} - The content of a |spfcases| environment are a sequence of case proofs marked up in the - |spfcase| environment, which takes an optional |KeyVal| argument for semantic - annotations. The second argument is used to specify the the description of the case - under consideration. The content of a |spfcase| environment is the same as that of a - |sproof|, i.e. |spfstep|s, |spfcomment|s, and |spfcases| environments. -\end{environment} - -\begin{function}{\spfcasesketch} - |\spfcasesketch| is a variant of the |spfcase| environment that takes the same - arguments, but instead of the |spfstep|s in the body uses a third argument for a proof - sketch. -\end{function} - -\begin{environment}{spfcomment} - The |spfcomment| environment is much like a |step|, only that it does not have an - object-level assertion of its own. Rather than asserting some fact that is relevant - for the proof, it is used to explain where the proof is going, what we are attempting - to to, or what we have achieved so far. As such, it cannot be the target of a - |\premise|. -\end{environment} - \begin{function}{\sproofend} Traditionally, the end of a mathematical proof is marked with a little box at the end of the last line of the proof (if there is space and on the end of the next line if there @@ -205,10 +374,14 @@ in most cases, this is desirable to make the proof structure explicit, but somet wastes space (especially, if a proof ends in a case analysis which will supply its own proof end marker). To suppress it locally, just set |proofend={}| in them or use use |\sProofEndSymbol{}|. +\end{sfragment} %%% Local Variables: %%% mode: latex %%% TeX-master: "../stex-manual" %%% End: -% LocalWords: hypothesis,id geq splitit arith:split-sum byindhyp rhs proofend +% LocalWords: hypothesis,id geq splitit arith:split-sum byindhyp rhs proofend eqstep +% LocalWords: sproofs coprime ratfrac 2,prec intpow ratpow inttimes varb varc sqrt2irr +% LocalWords: theorem,name sqrt2irr,method wlog hide,method hide,term spfblock splitsum +% LocalWords: simple-proof,method inducthypothesis diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-references.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-references.tex index 11de003e9be..3850d644ee7 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-references.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-references.tex @@ -1,6 +1,90 @@ -\begin{sfragment}[id=sec.references]{Referencing Symbols and Statements} -\textcolor{red}{TODO: references documentation} -\end{sfragment} +If we take features like \stexcode"\inputref" and \stexcode"\mhinput" +(and the \stexcode"sfragment"-environment, see +\sref[file=stex-document-structure]{sec:ds:intro}[in=../stex-manual,title={the \sTeX{}3 manual}]) seriously, +and build large documents modularly from individually compiling documents for sections, chapters +and so on, cross-referencing becomes an interesting problem. + +Say, we have a document |main.tex|, which \stexcode"\inputref"s a section +|section1.tex|, which references a definition with label |some_definition| in +|section2.tex| (subsequently also inputted in |main.tex|). +Then the numbering of the definition will depend on the \emph{document context} +in which the document fragment |section2.tex| occurs - in |section2.tex| itself +(as a standalone document), it might be \emph{Definition 1}, in |main.tex| it might +be \emph{Definition 3.1}, and in |section1.tex|, the definition \emph{does not even occur}, so +it needs to be referenced by some other text. + +What we would want in that instance is an equivalent of \stexcode"\autoref", that takes +the document context into account to yield something like \emph{Definition 1}, \emph{Definition 3.1} +or ``\emph{Definition 1 in the section on Foo}'' respectively. + +The \stexcode"\sref" command attempts to do precisely that. Unlike plain \stexcode"\ref", \stexcode"\autoref" +etc., \stexcode"\sref" refers to not just a \emph{label}, but instead a pair consisting of a \emph{label} +and the \emph{document} in whose context we want to refer to it. Conversely, every \emph{document} +(i.e. standalone compilable |.tex|-file) keeps track of the ``names'' (\emph{Definition 3.1} etc.) for every +label as determined in the context of the document, and stores them in a dedicated file |\jobname.sref|. +Additionally, every document has a ``\emph{reference name}'' (e.g. ``\emph{the section on Foo}''). +This allows us to refer to ``label $x$ in document $D$'' to yield ``\emph{Definition 1 in the section on Foo}''. +And of course, \sTeX can decide based on the current document to either refer to the label by its +``full name'' or directly as e.g. \emph{Definition 3.1} depending on whether the label occurs in +the current document anyway (and link to it accordingly). + +\paragraph{} For that to work, we need to supply (up to) three pieces +of information: +\begin{itemize} + \item The \emph{label} of the reference target (e.g. |some_definition|), + \item (optionally) the \emph{file}/document containing the reference target + (e.g. |section2|). + This is not strictly necessary, but allows for additional disambiguation + between possibly duplicate labels across files, and + \item (optionally) the document context, in which we want to + refer to the reference target (e.g. |main|). +\end{itemize} +Additionally, the document in which we want to reference a label needs +a title for external references. + + +\begin{function}{\sref} + \begin{syntax} \cs{sref}|[archive=|\meta{archive1}|,file=|\meta{file}|]|% + \Arg{label}|[archive=|\meta{archive2}|,in=|\meta{document-context}|,title=|\meta{title}|]| \end{syntax} + This command references \meta{label} (declared in \meta{file} in \meta{archive1}). + If the object (section, figure, etc.) with that label occurs ultimately + in the same document, \cs{sref} will ignore the second set of optional arguments + and simply defer to \cs{autoref} if that command exists, or \cs{ref} if the \pkg{hyperref} + package is not included. + + If the referenced object does \emph{not} occur in the current document however, + \cs{sref} will refer to it by the object's name as it occurs in + the file \meta{document-context} in \meta{archive2}. + +For example, the reference to the \stexcode"sfragment"-environment above +will appear as ``subsection 7.2.1 (Introduction) in the \sTeX{}3 manual'' +if you are reading this in the package documentation for |stex-references| +directly, but as a linked ``subsection 7.2.1'' in the full documentation +or manual. This is achieved using + +\stexcode"\sref[file=stex-document-structure]{sec:ds:intro}[in=../stex-manual,title={the \sTeX{}3 manual}]". + +\end{function} + +For a further example, the following: +\begin{center} + \sref[file=../stex-doc]{part:extends}[in=../stex-doc,title={the full \sTeX{}3 documentation}] +\end{center} +will say ``Part III'' (and link accordingly) in the full documentation, +and ``Part III (Extensions) in the full \sTeX{}3 documentation'' +everywhere else. This is achieved using + +\stexcode"\sref[file=../stex-doc]{part:extends}[in=../stex-doc,title={the full \sTeX{}3 documentation}]". + +\begin{function}{\extref} + \begin{syntax} \cs{sref}|[archive=|\meta{archive1}|,file=|\meta{file}|]|% + \Arg{label}|{archive=|\meta{archive2}|,in=|\meta{document-context}|,title=|\meta{title}|}| \end{syntax} + The \cs{extref}-command behaves exactly like \cs{sref}, but takes + \emph{required} the document context argument and will always use it + for generating the document text, regardless of whether the label + occurs in the current document. +\end{function} + %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-setup.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-setup.tex new file mode 100644 index 00000000000..7e0e1fe4a44 --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-setup.tex @@ -0,0 +1,34 @@ +\begin{sfragment}{Setting up the \sTeX Package} + + \begin{sfragment}[id=sec.minimal-setup]{Minimal Setup for the \sTeX Package} + In the best of all worlds, there is no setup, as you already have a new version of + {\TeX}Live on your system as a {\LaTeX} enthusiast. If not now is the time to + install it; see \cite{TeXLive:on}. You can usually update {\TeX}Live via a package + manager or the {\TeX}Live manager \textbf{tlmgr}. + \sTeX requires a \TeX{} kernel newer than February 2022. + + Alternatively, you can install \sTeX from CTAN, the Comprehensive {\TeX} Archive + Network; see \cite{stexCTAN:on} for details. We + assume you have the \sTeX package in at least version 3.2 (September 2022). + \end{sfragment} + + \begin{sfragment}[id=sec.git-setup]{GIT-based Setup for the \sTeX Development Version} + If you want use the latest and greatest \sTeX packages + that have not even been released to CTAN, + then you can directly clone them from the \sTeX development + repository \cite{sTeX:github:on} by the following command-line instructions: + \begin{lstlisting}[language=bash] + cd <stexdir> + git clone https://github.com/slatex/sTeX.git + \end{lstlisting} + and keep it updated by pulling updates via \lstinline|git pull| in the cloned \sTeX + directory. + Make sure to either clone the \sTeX repository into a local texmf-tree or to update your \lstinline|TEXINPUTS| environment variable, e.g. by placing the following line in your \lstinline|.bashrc|: + \begin{lstlisting}[language=bash] + export TEXINPUTS="$(TEXINPUTS):<sTeXDIR>//:" + \end{lstlisting} + \end{sfragment} + + \input{packages/stex-mathhubsetup} + +\end{sfragment}
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/stex/packages/stex-symbols.tex b/Master/texmf-dist/doc/latex/stex/packages/stex-symbols.tex index e7bafeda6b6..67e9a32e704 100644 --- a/Master/texmf-dist/doc/latex/stex/packages/stex-symbols.tex +++ b/Master/texmf-dist/doc/latex/stex/packages/stex-symbols.tex @@ -413,9 +413,9 @@ Note that the precise numbers used for precedences are pretty arbitrary - what m which precedences are higher than which other precedences when used in conjunction. \begin{variable}{\infprec,\neginfprec} It is occasionally useful to have ``infinitely'' high or low precedences to enforce or - forbid automated bracketing entirely -- for those purposes, \stexcode"\infprec" and - \stexcode"\neginfprec" exist (which are implemented as the maximal and minimal integer - values accordingly). + forbid automated bracketing entirely, e.g. for bracket-like notations such as intervals + -- for those purposes, \stexcode"\infprec" and \stexcode"\neginfprec" exist (which are + implemented as the maximal and minimal integer values accordingly).g \end{variable} \begin{dangerbox} @@ -499,7 +499,7 @@ which precedences are higher than which other precedences when used in conjuncti \vardef{varx}[name=x,type=\Nat]{\comp{x}} Given a function $\varf!:\funtype{\Nat}{\Nat}$, -by $\addition{\varf!,\varn}$ we mean the function +by $\addition{\varf!,\varn}$ we mean the function\rustexBREAK $\fun{\varx}{\varf{\addition{\varx,\varn}}}$ } diff --git a/Master/texmf-dist/doc/latex/stex/stex-doc.pdf b/Master/texmf-dist/doc/latex/stex/stex-doc.pdf Binary files differindex 0d0a36720cb..e53c98213ac 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-doc.pdf +++ b/Master/texmf-dist/doc/latex/stex/stex-doc.pdf diff --git a/Master/texmf-dist/doc/latex/stex/stex-doc.tex b/Master/texmf-dist/doc/latex/stex/stex-doc.tex index 7a98ff49c2b..d2ff005554c 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-doc.tex +++ b/Master/texmf-dist/doc/latex/stex/stex-doc.tex @@ -1,4 +1,7 @@ -\def\bibfolder#1{../lib/bib/#1} +\def\libfolder#1{../lib/#1} +\newif\ifinidedoc\inidedocfalse +\newif\ifinfulldoc\inidedocfalse + \input{stex-docheader} \infulldoctrue @@ -9,8 +12,6 @@ } \ExplSyntaxOff -\expandafter\newif\csname if@infulldoc\expandafter\endcsname\csname @infulldoctrue\endcsname - \begin{document} \title{ The {\stex{3}} Package Collection @@ -185,7 +186,7 @@ \OmitDocInput{../source/stex/stex-others.dtx} \DocInput{../source/stex/stex-metatheory.dtx} -\part{Extensions}\label{part:extensions} +\part{Extensions}\label{part:extensions}\slabel{part:extends} \DocInput{../source/extensions/tikzinput.dtx} \DocInput{../source/extensions/document-structure.dtx} diff --git a/Master/texmf-dist/doc/latex/stex/stex-docheader.tex b/Master/texmf-dist/doc/latex/stex/stex-docheader.tex index d16b19703bd..c6bea9b3da5 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-docheader.tex +++ b/Master/texmf-dist/doc/latex/stex/stex-docheader.tex @@ -1,4 +1,5 @@ \RequirePackage{paralist} +\ifcsname libfolder\endcsname\else\def\libfolder#1{../lib/#1}\fi \documentclass[full,kernel]{l3doc} \usepackage[dvipsnames]{xcolor} \usepackage[utf8]{inputenc} @@ -7,15 +8,14 @@ \RequirePackage{tikzinput} \usetikzlibrary{fit} -% \usepackage[debug=all,lang=en, mathhub=./tests]{stex} -\usepackage[lang=en, mathhub=./tests]{stex} -\usepackage{url,array,float,textcomp} +\usepackage[lang=en, mathhub=./tests,debug=sref]{stex} +\usepackage{url,array,float} \usepackage[show]{ed} \usepackage[hyperref=auto,style=alphabetic]{biblatex} -\addbibresource{\bibfolder{kwarcpubs.bib}} -\addbibresource{\bibfolder{extpubs.bib}} -\addbibresource{\bibfolder{kwarccrossrefs.bib}} -\addbibresource{\bibfolder{extcrossrefs.bib}} +\addbibresource{\libfolder{bib/kwarcpubs.bib}} +\addbibresource{\libfolder{bib/extpubs.bib}} +\addbibresource{\libfolder{bib/kwarccrossrefs.bib}} +\addbibresource{\libfolder{bib/extcrossrefs.bib}} \usepackage{amssymb} \usepackage{amsfonts} \usepackage{xspace} @@ -50,7 +50,9 @@ \\symbolname,\\binarysymbol,\\newbinarysymbol,\\addition, \\summation,\\ascendingchain,\\quantforall,\\set,\\funtype, \\Nat,\\successor,\\multiplication,\\Int,\\zero,\\uminus, - \\intmonoid + \\intmonoid,\\divides,\\intpow,\\ratfrac,\\ratpow,\\inttimes, + \\inset,\\eq,\\rational,\\irrational,\\coprime,\\PosInt, + \\realroot }, classoffset=2,keywordstyle=\color{blue},morekeywords={ \\symdecl,\\symdef,\\notation,\\vardef,\\varseq,\\instantiate, @@ -64,11 +66,11 @@ classoffset=4,keywordstyle=\color{Purple},morekeywords={ \\definiendum,\\definame,\\symref,\\symname,\\comp, \\compemph,\\definiens,\\svar,\\infprec,\\neginfprec,\\ellipses, - \\Symname,\\arg + \\Symname,\\arg,\\yield,\\assumption,\\spfstep,\\eqstep,\\conclude }, classoffset=5,keywordstyle=\color{magenta},morekeywords={ smodule,sdefinition,sassertion,sparagraph,sexample, - sproof,subproof,spfcases,spfcase,spfstep,spfcomment, + sproof,subproof,spfcases,spfcase,spfstep,spfcomment,spfblock, \\spfidea,\\spfsketch,\\spfcasesketch,\\sproofend, \\spfjust,\\premise,\\justarg, copymodule,interpretmodule,mathstructure,sexample @@ -88,57 +90,12 @@ }, classoffset=8,keywordstyle=\color{red},morekeywords={ frame,note + }, + classoffset=9,keywordstyle=\color{gray},morekeywords={ + \\vara,\\varb,\\varc } } -%\lstdefinestyle{mylatex}{ -% keywordstyle=\color{BurntOrange} -%} -%\lstdefinelanguage{mylatex}{ -% emphstyle=\underbar, -% alsodigit={:}, -% %alsoletter={_}, -% alsoletter={\\} -% sensitive=true, -% classoffset=0,keywordstyle=\bfseries, -% morekeywords={\\begin,\\end,\\ExplSyntaxOn,\\ExplSyntaxOff}, -% classoffset=1,keywordstyle=\color{blue}, -% morekeywords={ -% \\symdecl, -% \\symdef, -% \\notation, -% \\abbrdef, -% \\importmodule, -% \\usemodule, -% \\STEXwithbrackets, -% \\symref -% }, -% classoffset=2,keywordstyle=\color{Purple}, -% morekeywords={ -% \\stex_path_from_string:Nn, -% \\stex_path_to_string:NN, -% \\stex_path_to_string:N, -% \\stex_require_repository:n, -% \\stex_modules_current_namespace:, -% \\stex_debug:n, -% \\stex_set_current_repository:n, -% \\stex_file_in_smsmode:nn, -% \\stex_get_symbol:n, -% }, -% classoffset=3,keywordstyle=\color{SkyBlue}, -% morekeywords={ -% \\l_stex_module_ns_str, -% \\g_stex_currentfile_seq, -% \\l_stex_current_module_prop, -% \\l_stex_get_symbol_uri_str, -% } -% classoffset=0, -%%^^A morecomment=[l][\color{Gray}]{//}, -%%^^A morecomment=[s][\color{Gray}]{/*}{*/}, -% morecomment=[s][\color{Green}]{$}{$},, -% morecomment=[s][\color{OliveGreen}]{\\[}{\\]}, -%^^A morestring=[b][\color{Purple}]\$, -%} \lstnewenvironment{latexcode}[1][]{\lstset{language=sTeX,#1}}{} \def\stexcode{\lstinline[language=sTeX]} @@ -183,28 +140,6 @@ outer arc=4pt } - -%\newtcolorbox{exampleborderbox}{ -% enhanced, -% left=0pt, -% title={Example \the\example@counter}, -% right=0pt, -% top=8pt, -% bottom=8pt, -% colback=white, -% colframe=blue, -% width=\textwidth, -% enlarge left by=0mm, -% boxsep=5pt, -% fontupper=\small, -% arc=4pt, -% outer arc=4pt, -% leftupper=1.5cm, -% fonttitle=\bfseries, -% coltitle=blue, -% boxed title style={empty,size=minimal,toprule=0pt,top=1pt,left=3mm,overlay={}}, -%} - \newenvironment{example@border} { \global\advance\example@counter by 1 @@ -262,7 +197,7 @@ Output: \begin{stextest@output} - \input{stextest.tex} + \csname @ @ input\endcsname{stextest.tex} \end{stextest@output} \end{example@border} } @@ -371,7 +306,7 @@ \def\atwintoo#1#2#3{{#1 #2 #3}\atwin{#1}{#2}{#3}} \def\cT{\mathcal{T}}\def\cD{\mathcal{D}} -\def\fileversion{3.1} +\def\fileversion{3.2} \def\filedate{\today} \RequirePackage{pdfcomment} @@ -446,4 +381,4 @@ \end{mdframed}\end{remarkbox}\endlist } -\usepackage{rustex} +\usepackage{rustex}
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/stex/stex-ide.pdf b/Master/texmf-dist/doc/latex/stex/stex-ide.pdf Binary files differnew file mode 100644 index 00000000000..a04d7ddd606 --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/stex-ide.pdf diff --git a/Master/texmf-dist/doc/latex/stex/stex-ide.tex b/Master/texmf-dist/doc/latex/stex/stex-ide.tex new file mode 100644 index 00000000000..a563d277fbd --- /dev/null +++ b/Master/texmf-dist/doc/latex/stex/stex-ide.tex @@ -0,0 +1,155 @@ +\ifcsname ifinfulldoc\endcsname\else + \expandafter\newif\csname ifinfulldoc\endcsname\infulldocfalse +\fi +\ifcsname ifinidedoc\endcsname\else + \expandafter\newif\csname ifinidedoc\endcsname\inidedoctrue +\fi + +\ifinidedoc +\input{stex-docheader} + + +\begin{document} + + \title{ + The {\stex} VSCode IDE + \thanks{Version {\fileversion} (last revised {\filedate})} + } + \author{Michael Kohlhase, Dennis Müller\\ + FAU Erlangen-Nürnberg\\ + \url{http://kwarc.info/} + } + \pagenumbering{roman} + \maketitle + + This is the user manual for the \sTeX Plugin for VSCode, available at + \url{https://marketplace.visualstudio.com/items?itemName=kwarc.stexide}. + For the manual for the \sTeX package itself, see \href{\basedocurl/stex-manual.pdf}{the \sTeX{}3 Manual}. + + \makeatletter + \renewcommand\part{% + \clearpage + \thispagestyle{plain}% + \@tempswafalse + \null\vfil + \secdef\@part\@spart% + } + \newcounter{chapter} + \numberwithin{section}{chapter} + \renewcommand\thechapter{\@arabic\c@chapter} + \renewcommand\thesection{\thechapter.\@arabic\c@section} + \newcommand*\chaptermark[1]{} + \setcounter{secnumdepth}{2} + \newcommand\@chapapp{\chaptername} + %\newcommand\chaptername{Chapter} + \def\ps@headings{% + \let\@oddfoot\@empty + \def\@oddhead{{\slshape\rightmark}\hfil\thepage}% + \let\@mkboth\markboth + \def\chaptermark##1{% + \markright{\MakeUppercase{% + \ifnum \c@secnumdepth >\m@ne + \@chapapp\ \thechapter. \ % + \fi + ##1}}% + }% + } + \newcommand\chapter{\clearpage + \thispagestyle{plain}% + \global\@topnum\z@ + \@afterindentfalse + \secdef\@chapter\@schapter% + } + \def\@chapter[#1]#2{\refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}#1}% + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \@makechapterhead{#2}% + \@afterheading% + } + \def\@makechapterhead#1{% + \vspace*{50\p@}% + {\parindent \z@ \raggedright \normalfont + \huge\bfseries \@chapapp\space \thechapter + \par\nobreak + \vskip 20\p@ + \interlinepenalty\@M + \Huge \bfseries #1\par\nobreak + \vskip 40\p@ + }% + } +\newcommand*\l@chapter[2]{% + \ifnum \c@tocdepth >\m@ne + \addpenalty{-\@highpenalty}% + \vskip 1.0em \@plus\p@ + \setlength\@tempdima{1.5em}% + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \bfseries + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil + \nobreak\hb@xt@\@pnumwidth{\hss #2% + \kern-\p@\kern\p@}\par + \penalty\@highpenalty + \endgroup + \fi} +\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.8em}} +\renewcommand*\l@subsection{\@dottedtocline{2}{3.8em}{3.2em}} +\renewcommand*\l@subsubsection{\@dottedtocline{3}{7.0em}{4.1em}} +\def\partname{Part} +\def\toclevel@part{-1} +\def\maketitle{\chapter{\@title}} +\let\thanks\@gobble +\let\DelayPrintIndex\PrintIndex +\let\PrintIndex\@empty +\providecommand*{\hexnum}[1]{\text{\texttt{\char`\"}#1}} +\makeatother + +\ExplSyntaxOn +\int_set:Nn \l_document_structure_section_level_int {1} +\ExplSyntaxOff + +\clearpage + +{% + \def\\{:}% fix "newlines" in the ToC + \tableofcontents +} + +\clearpage +\pagenumbering{arabic} + +\long\def\ignore#1{} + +\input{packages/stex-setup} +\input{packages/stex-idesetup} + +\fi + + + + +\ifinidedoc +\newpage +\printbibliography +\end{document} +\fi + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: + +% LocalWords: stex-docheader infulldoctrue l@subsubsection toclevel@part ExplSyntaxOff +% LocalWords: l_document_structure_section_level_int dangerbox mmtbox omdoc OBJref lmh +% LocalWords: own:fifom MueRabRot:rslffml20 sec.stexarchives stex-mathhub ngerman a,b +% LocalWords: Metatheory sec.customhighlight sproof stexthm xspace stexpatchmodule +% LocalWords: stexpatchexample stexpatchparagraph sexampleid amsthm sassertiontitle +% LocalWords: sdefinitiontitle compemph varemph srefsymuri stex-hwexam TeXLive:on tlmgr +% LocalWords: stexls:on,stexls-vscode-plugin:on diff --git a/Master/texmf-dist/doc/latex/stex/stex-manual.pdf b/Master/texmf-dist/doc/latex/stex/stex-manual.pdf Binary files differindex 32c1e047ca5..2facc41ad11 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-manual.pdf +++ b/Master/texmf-dist/doc/latex/stex/stex-manual.pdf diff --git a/Master/texmf-dist/doc/latex/stex/stex-manual.tex b/Master/texmf-dist/doc/latex/stex/stex-manual.tex index 31b9c4eaeb2..547e238f540 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-manual.tex +++ b/Master/texmf-dist/doc/latex/stex/stex-manual.tex @@ -1,19 +1,15 @@ -\makeatletter -\ifcsname if@infulldoc\endcsname\else - \expandafter\newif\csname if@infulldoc\endcsname\@infulldocfalse -\fi -\makeatother - -\csname if@infulldoc\endcsname\else - -\def\bibfolder#1{../lib/bib/#1} -\input{stex-docheader} +\ifcsname ifinfulldoc\endcsname\else + \expandafter\newif\csname ifinfulldoc\endcsname\infulldocfalse +\fi +\ifcsname ifinidedoc\endcsname\else + \expandafter\newif\csname ifinidedoc\endcsname\inidedocfalse +\fi -\infulldoctrue +\ifinfulldoc\else + \input{stex-docheader} \begin{document} - \csname if@infulldoc\endcsname\else \title{ The {\stex{3}} Manual \thanks{Version {\fileversion} (last revised {\filedate})} @@ -192,82 +188,55 @@ provided by several pieces of software: \end{itemize} \end{sfragment} - -\begin{sfragment}{Quickstart} - \begin{sfragment}{Setup} - There are two ways of using \sTeX: as a - \begin{enumerate} - \item way of writing {\LaTeX} more modularly (object-oriented Math) for creating PDF - documents or - \item foundation for authoring active documents in HTML5 instrumented with knowledge - management services. - \end{enumerate} - Both are legitimate and useful. The first requires a significantly smaller - tool-chain, so we describe it first. The second requires a much more substantial - (and experimental) toolchain of knowledge management systems. Both workflows profit - from an integrated development environment (IDE), which (also) automates setup as - far as possible (see \sref{sec.sTeX-IDE}). - - \begin{sfragment}[id=sec.minimal-setup]{Minimal Setup for the PDF-only Workflow} - In the best of all worlds, there is no setup, as you already have a new version of - {\TeX}Live on your system as a {\LaTeX} enthusiast. If not now is the time to - install it; see \cite{TeXLive:on}. You can usually update {\TeX}Live via a package - manager or the {\TeX}Live manager \textbf{tlmgr}. - - Alternatively, you can install \sTeX from CTAN, the Comprehensive {\TeX} Archive - Network; see \cite{stexCTAN:on} for details. - \end{sfragment} - - \begin{sfragment}[id=sec.git-setup]{GIT-based Setup for the \sTeX Development Version} - If you want use the latest and greatest \sTeX packages - that have not even been released to CTAN, - then you can directly clone them from the \sTeX development - repository \cite{sTeX:github:on} by the following command-line instructions: -\begin{lstlisting}[language=bash] - cd <stexdir> - git clone https://github.com/slatex/sTeX.git -\end{lstlisting} - and keep it updated by pulling updates via \lstinline|git pull| in the cloned \sTeX - directory. - Then update your \lstinline|TEXINPUTS| environment variable, e.g. by placing the following line in your \lstinline|.bashrc|: -\begin{lstlisting}[language=bash] -export TEXINPUTS="$(TEXINPUTS):<sTeXDIR>//:" -\end{lstlisting} - \end{sfragment} - - \begin{sfragment}[id=sec.stex-archives]{\sTeX Archives (Manual Setup)} - Writing semantically annotated \sTeX becomes much easier, if we can use - well-designed libraries of already annotated content. \sTeX provides such - libraries as \sTeX archives -- i.e. GIT repositories at - \url{https://gl.mathhub.info} -- most prominently the SMGLoM libraries at - \url{https://gl.mathhub.info/smglom}. - - To do so, we set up a \textbf{local MathHub} by creating a MathHub directory - \lstinline|<mhdir>|. Every \sTeX archive as an \textbf{archive path} - \lstinline|<apath>| and a name \lstinline|<archive>|. We can clone the \sTeX - archive by the following command-line instructions: +\begin{sfragment}{Setup} + There are two ways of using \sTeX: as a + \begin{enumerate} + \item way of writing {\LaTeX} more modularly (object-oriented Math) for creating PDF + documents or + \item foundation for authoring active documents in HTML5 instrumented with knowledge + management services. + \end{enumerate} + Both are legitimate and useful. The first requires a significantly smaller + tool-chain, so we describe it first. The second requires a much more substantial + toolchain of knowledge management systems. + + Luckily, the \sTeX-IDE will take care of much of the setup required + for the full toolchain, if you are willing to use it. + + \input{packages/stex-setup} + + \input{packages/stex-idesetup} + + \begin{sfragment}{Manual Setup} + + In lieu of using the \sTeX IDE, we can do the following: + + \begin{sfragment}[id=sec.stex-archives]{\sTeX Archives (Manual Setup)} + Writing semantically annotated \sTeX becomes much easier, if we can use + well-designed libraries of already annotated content. \sTeX provides such + libraries as \sTeX archives -- i.e. GIT repositories at + \url{https://gl.mathhub.info} -- most prominently the SMGLoM libraries at + \url{https://gl.mathhub.info/smglom}. + + To do so, we set up a \textbf{local MathHub} by creating a MathHub directory + \lstinline|<mhdir>|. Every \sTeX archive as an \textbf{archive path} + \lstinline|<apath>| and a name \lstinline|<archive>|. We can clone the \sTeX + archive by the following command-line instructions: \begin{lstlisting}[language=bash] - cd <mhdir>/<apath> - git clone https://gl.mathhub.info/smglom/<archive>.git +cd <mhdir>/<apath> +git clone https://gl.mathhub.info/smglom/<archive>.git \end{lstlisting} - Note that \sTeX archives often depend on other archives, thus you should be - prepared to clone these as well -- e.g. if \texttt{pdflatex} reports missing - files. - To make sure that \sTeX too knows where to find its archives, we need to set a global - system variable |MATHHUB|, that points to your local |MathHub|-directory (see - \sref{sec.stexarchives}). + Note that \sTeX archives often depend on other archives, thus you should be + prepared to clone these as well -- e.g. if \texttt{pdflatex} reports missing + files. + To make sure that \sTeX too knows where to find its archives, we need to set a global + system variable |MATHHUB|, that points to your local |MathHub|-directory (see + \sref{sec.stexarchives}). \begin{lstlisting}[language=bash] -export MATHHUB="<mhdir>'' +export MATHHUB="<mhdir>" \end{lstlisting} - \end{sfragment} - - \begin{sfragment}[id=sec.sTeX-IDE]{The \sTeX IDE} - We are currently working on an \sTeX IDE as an \sTeX plugin for |VScode|; - see~\cite{sTeX-IDE:on}. It will feature a setup procedure that automates the setup - described above (and below). For additional functionality see the (now obsolete) - plugin for \sTeX1 \cite{stexls:on,stexls-vscode-plugin:on}. - \end{sfragment} + \end{sfragment} \begin{sfragment}{Manual Setup for Active Documents and Knowledge Management Services} Foregoing on the \sTeX IDE, we will need several additional (on top of the minimal @@ -301,11 +270,15 @@ export MATHHUB="<mhdir>'' \end{itemize} \end{sfragment} \end{sfragment} +\end{sfragment} - \input{stex-tutorial} - +\begin{sfragment}[id=sec.sTeX-IDE]{The \sTeX IDE} + \input{stex-ide} \end{sfragment} +\input{stex-tutorial} + + \begin{sfragment}{Creating \sTeX Content} \input{packages/stex-basics} @@ -453,7 +426,6 @@ export MATHHUB="<mhdir>'' \begin{sfragment}{\sTeX Statements} \input{packages/stex-statements} \input{packages/stex-proofs} -\end{sfragment} \begin{sfragment}[id=sec.customhighlight]{Highlighting and Presentation Customizations} @@ -538,7 +510,7 @@ export MATHHUB="<mhdir>'' \begin{latexcode} \protected\def\symrefemph@uri#1#2{ \pdftooltip{ - \srefsymuri{#2}{\symrefemph{#1}} + \symrefemph{#1} }{ URI:~\detokenize{#2} } @@ -548,6 +520,10 @@ export MATHHUB="<mhdir>'' other three commands). \end{function} \end{sfragment} +\end{sfragment} +\begin{sfragment}[id=sec.references]{Cross References} + \input{packages/stex-references} +\end{sfragment} \begin{sfragment}{Additional Packages} \begin{sfragment}{Tikzinput: Treating TIKZ code as images} @@ -557,7 +533,7 @@ export MATHHUB="<mhdir>'' \input{packages/stex-document-structure} \end{sfragment} \begin{sfragment}{Slides and Course Notes} - \input{packages/stex-slides} + \input{packages/stex-notesslides} \end{sfragment} \begin{sfragment}{Representing Problems and Solutions} \input{packages/stex-problem} @@ -567,7 +543,7 @@ export MATHHUB="<mhdir>'' \end{sfragment} \end{sfragment} -\csname if@infulldoc\endcsname\else +\ifinfulldoc\else \newpage \printbibliography \end{document} diff --git a/Master/texmf-dist/doc/latex/stex/stex-tutorial.tex b/Master/texmf-dist/doc/latex/stex/stex-tutorial.tex index dcd4c442e00..7b3b723826e 100644 --- a/Master/texmf-dist/doc/latex/stex/stex-tutorial.tex +++ b/Master/texmf-dist/doc/latex/stex/stex-tutorial.tex @@ -21,7 +21,7 @@ \symdef{geometricSeries}[name=geometric-series]{\comp{S}} \begin{sdefinition}[for=geometricSeries] - The \definame{geometricSeries} is the \symname{?series} + The \definame{geometricSeries} is the \symname{series} \[\defeq{\geometricSeries}{\definiens{ \infinitesum{\svar{n}}{1}{ \realdivide[frac]{1}{ |