From accdc2608546b74cbbb5025204bb5f744d321c0f Mon Sep 17 00:00:00 2001 From: Georg Osang Date: Wed, 15 Jul 2026 16:09:39 +0300 Subject: [PATCH] STACK: Add documentation on usage --- doc/guide/author/overview.xml | 9 ++++++ doc/guide/author/topics.xml | 52 ++++++++++++++++++++++++++++++++++- 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/doc/guide/author/overview.xml b/doc/guide/author/overview.xml index 8fd0190469..7dea90f9e1 100644 --- a/doc/guide/author/overview.xml +++ b/doc/guide/author/overview.xml @@ -564,6 +564,15 @@ STACK exercise

STACK is an online assessment system, and these exercises can be embedded in a document. STACK is an acronym for System for Teaching and Assessment using a Computer algebra Kernel. See for details.

+ +

STACK questions must be included as assets in .xml or .yaml format, one file per question. See for how this is done and best practices.

+ +

In the web output, STACK questions will be embedded and allow students to submit answer and get feedback. + Currently there is no way of collecting student submission data though. + For static outputs such as PDF, will try to generate a static version of the question. + As STACK questions contain HTML, it will use a heuristic to convert some HTML tags. + Others will simply be ignored. Interactive elements such as JSXGraph are currently not supported + and a reference to the online version is included instead of the question text.

diff --git a/doc/guide/author/topics.xml b/doc/guide/author/topics.xml index 25480e2cd1..424caac836 100644 --- a/doc/guide/author/topics.xml +++ b/doc/guide/author/topics.xml @@ -5160,7 +5160,57 @@ STACK Exercises STACK exercise -

STACK is an assessment system with online interactive exercioses. This section will soon have instructions on how to embed these exercises.

+

+ STACK is an assessment system with online, interactive exercises that use a computer algebra system to check a student's answer and provide feedback. +

+ +

+ A STACK question must be included as an asset in .xml or .yaml format, one file per question, with the path given relative to the assets folder. For example: +

+ 
+            <exercise xml:id="ex-my-stack-question">
+                <title>An optional title</title>
+                <stack label="stk-my-stack-question"
+                       source="stack/my-stack-question.xml"/>
+            </exercise>
+
+

+ The exercise's xml:id is what you use to cross-reference the exercise elsewhere in your project, while the stack element's label is used internally to name the files generated when producing a static version of the question (see below). Currently, a stack element only supports a source attribute; there is no way to author STACK question content inline. Although the schema does not require it, you should always supply a label: without one, the files generated for the question's static version are named from an automatically assigned, positional id instead of a stable one you chose, so their names can change from build to build as you add or remove other content. +

+ +

+ In web output, STACK questions are embedded and let students submit answers and get feedback. There is currently no way to collect or review student submission data. For static outputs such as PDF, generates a static version of the question instead. Since STACK questions contain HTML, a heuristic is used to convert some HTML tags; any tags it doesn't recognize are simply ignored. Interactive elements, such as JSXGraph applets, are not currently supported, and a reference to the online version of the question is included in their place. +

+ + + Not Every STACK Question Converts Cleanly to Static Output +

+ Because the conversion to a static version relies on a heuristic and does not support every HTML construct or interactive element a STACK question might use, a question that renders well in web output may still be missing pieces, or read awkwardly, in PDF and other static output. There is no automated check for this; after adding a STACK question, you should check the static output (with hints, answers, and feedback exposed, if applicable) to be sure it is complete and makes sense on its own. +

+ + +

+ Questions must have deployed variants, unless they contain no randomization; this is a requirement of the STACK API. A static version of a question is not generated automatically—you need to run pretext generate stack explicitly. (This is expected to change in the future, so that static versions are generated automatically alongside other assets.) +

+ +

+ Questions are rendered using a deployment of the STACK API. Its URL is given by the attribute + /publication/stack/@server + in the publication file. For testing, such as when compiling the minimal example, you can use a publicly deployed API, but for production use you should run your own deployment. Docker images are available; see the installation instructions and the API's repository. +

+ + + Question Management + +

+ Currently, the most common way of authoring STACK questions is in Moodle, or a similar Learning Management System (LMS). It is possible to export a question bank from Moodle as a single XML file and split it into one STACK question XML file per question, but this makes maintenance difficult, since you have to re-export and re-split the file every time you want to make a change. +

+ +

+ The recommended way to maintain a bank of questions for inclusion in a textbook is with moodle-qbank_gitsync. The setup is not straightforward, and requires administrator permissions in Moodle, but it exports the questions in a question bank as one XML file per question, organized into folders, along with a command-line tool to pull changes from, and push changes to, the Moodle server—making it easy to keep the XML files in sync with the questions on the Moodle server. +

+ +