Merge branch 'iss1748' of https://github.com/maths/moodle-qtype_stack into iss1757

Author: EJMFarrow

doc/en/Authoring/Inputs/Text_input.md

@@ -22,14 +22,25 @@ Notes
 
 1.  All the notes for "string" inputs above still apply.
 2.  The freetext input takes the default option value is `manualgraded:true`.  If you specify `manualgraded:true` then the _whole STACK question_ will require manual grading!
-3.  Part of this input can be linked to an automatically graded STACK input, e.g. an algebraic input (final answer), textarea (last lines) or units input.
+3.  Part of this input can be [linked to an automatically graded STACK input](../../Specialist_tools/Free_text_input/index.md), e.g. an algebraic input (final answer), textarea (last lines) or units input.
 
 #### JSON input ####
 
 The JSXGraph, GeoGebra and Parsons blocks return a JSON object.  When linking to a STACK input we recommend using the dedicated JSON/Geogebra/Parsons inputs rather than the string input.  String inputs will continue to work (maintaining legacy JSXGraph questions), but using the JSON input for inputs linked to JSXGraph logically indicates the expected type of string.
 
 This input gives the _teacher_ a JSON pretty print view of the JSON object for debugging.
 
+JSON input can be used in PRTs, but note these are always strings.  STACK provides limited faciliites to process JSON within Maxima, to extract parts of the JSON.
+
+For example, if you have
+
+    s1: "{\"matches\":[ \"Apple\", \"Bannan\", \"Cherry\"]}";
+    l1: stackmap_get(stackjson_parse(s1), "matches");
+
+Then the value of `l1` will be the Maxima list `["Apple", "Bannan", "Cherry"]`.
+
+By design it is impossible to parse the value of these strings as Maxima expressions.  If you want Maxima expressions from students then these must be entered via a STACK input (such as algebraic).
+
 ### Parsons input ###
 
 A special [Parsons input](../../Specialist_tools/Drag_and_drop/index.md), is available to store the JSON object generated by the Parsons block.

doc/en/Authoring/Question_blocks/ASCII.md

@@ -0,0 +1,92 @@
+# ASCII block
+
+This block has two purposes:
+
+1. to process and display the contents of a [free-text input](../Inputs/Text_input.md) using client-side Javascript to process markdown, AsciiMath and LaTeX (etc).
+2. to extract information from the text (as it is processed) and link that to another STACK input.
+
+Examples of how to use this block are given in the [free-text specialist tools](../../Specialist_tools/Free_text_input/index.md) documentation.
+
+This example links free-text input `ans1` to another input `ans2`
+
+```
+[[ascii input="ans1" answer="ans2"]][[/ascii]]
+```
+
+Currently, it is only possible to link to one input.
+
+### Block parameters
+
+Functionality and styling can be customised through the use of block parameters.
+
+1. `input`: string. The name of the free-text input which provides input to this block.
+2. `answer`: string. The name of the STACK input which receives an answer from the extractor.
+3. `height`: string containing a positive float + a valid CSS unit (e.g.`"480px"`, `"100%"`, ...). Default is to create a window of automatic height to fit all the content upon load. Entering a value for the `height` parameter in the block header fixes the height of the window containing the drag-and-drop lists and will disable automatic resizing of the window containing the lists. Students will still be able to automatically resize the window with the expand button.
+4. `width`: string containing a positive float + a valid CSS unit (e.g.`"480px"`, `"100%"`, ...).  Default is `"100%"`. This fixes the width of the window containing the drag-and-drop lists.
+5. `aspect-ratio`: string, containing a float between 0 and 1. This can be used with `height`/`length` _or_ `width` (not both) and automatically determines the value of the un-used parameter in accordance with the value of `aspect-ratio`; unset by default. An error will occur if one sets values for `aspect-ratio`, `width`, `height` _or_ `aspect-ratio`, `width`, `length`.
+6. `hidden`: To hide the display of the contents use the block option `hidden="true"`.
+
+
+## Filters
+
+To use optional filters, use the block option `filters="latexwrap"`.
+
+The `latexwrap` formats multiple-line mathematics aligned on the first `=` sign, or similar operators such as inequality.
+
+Takes an array of LaTeX strings (one per line) and returns an array whose first element is `\[\begin{align*}` and last element is `\end{align*}\]`, with the content lines in between formatted for a 3-column aligned layout:
+
+* col 1 - leading implies/therefore symbol (if present)
+* col 2 - left-hand side up to (but not including) the relation symbol
+* col 3 - relation symbol and right-hand side
+
+A `\text{…}` that is not `\text{or/and/if}` is pushed into a 4th column.
+
+* The `boldfilter` changes text to bold.  (This is experimental for testing and development only.)
+
+### Filter developer notes
+
+Filters are defined in `corscripts/ascii/filters`.  This has been designed to add flexibility for filtering.
+
+(In the future we may add the option to use the block contents to allow bespoke filtering.)
+
+(In the future we may add a filter which parses AsciiMath into strict Maxima syntax.)
+
+## Extractors
+
+The purpose of "extractors" is to identify parts of the student's text, extract this, and send it to another STACK input for automatic assessment.
+
+The following are important use-cases.
+
+1. Extract the last mathematical expression and send this to an input.  This is either (i) the last inline AsciiMath delimited by backticks, or (ii) the _last line_ of the last multi-line mathematical expression/derivation.
+2. Extract the whole of the last mathematical expression and send this to an input.  This is either (i) the last inline AsciiMath delimited by backticks, or (ii) the _whole_ of the last multi-line mathematical expression/derivation.  This option relies on having a multi-line STACK input such as equiv or textarea to receive the potential multi-line expression.
+3. Identify the last mathematical expression (as in 1) and match part of this using a regular expression.  Logically, this is situation (1) with a non-trivial regular expression as a parameter.  The first match is sent to a STACK input.  This could be a Maxima input (e.g. algebraic) or STACK's string input. (See below)
+4. Apply a regular expression to the entire text input, and assemble a JSON object with all the matched patterns.  This is not assumed to be mathematics, and so is sent to STACK as a string/JSON object.  This option relies on having a string/JSON input (choose JSON for better debugging). (See below)
+
+### Extract Maxima using regular expressions
+
+Imagine we are expecting a student to conclude with \(f(x) = \) `expr` and we wish to assess their answer `expr` in a PRT automatically.
+
+One way to do this would be to use a regular expression client-side, e.g. the regular expression `^*f\(x\)\s*=\s*` will match this, and we then send only the match to the input.  This approach gives the validation message "Your last answer ..." only including `expr` as validated.
+
+Another way to do this would be to send _everything_ to the input (e.g. `ans1`) and sort out the student's answer in the PRT.  For example you could define
+
+    sa1: if equationp(ans1) then rhs(ans1) else ans1;
+
+in the feebdack variables.  If `ans1` is an equation, this takes the right-hand side of `ans1`, or the whole expression otherwise.  This second approach condones lack of `f(x)=` in a student's answer or them using something else.
+
+Both client-side regular expressions, and post-processing in Maxima, have their merits and uses and so we suppport both options for teachers.
+
+### Extract strings using regular expressions
+
+We may want to match text within the answer using regular expressions.
+
+If you have a regular expressions which matches "fruit" within the student's answer (!), then you would expect the STACK input to contain the Maxima string
+
+    "{\"matches\":[ \"Apple\", \"Bannan\", \"Cherry\"]}";
+
+If this is assigned to input `ans1` then you can create a Maxima list of the matched strings with `sa1: stackmap_get(stackjson_parse(ans1), "matches");` in the PRT.
+
+### Extractor developer notes
+
+(In the future we may add more flexible functionality, linking arbitrary extractors to multiple inputs.)
+

doc/en/Authoring/Question_blocks/Fact_sheets.md

@@ -596,4 +596,14 @@ d}x}\left\{\int g(x)\mathrm{d}x\right\}\mathrm{d}x.\]
 or alternatively: \[\int f(x)g(x)\,\mathrm{d}x=f(x)\,\int
 g(x)\mathrm{d}x -\int {\mathrm{d}f\over \mathrm{d}x}\left\{\int g(x)\mathrm{d}x\right\}\mathrm{d}x.\]
 
+### Free-text inputs
 
+<code>[[facts:free_text]]</code>
+
+This input allows you to type in free text, e.g. your complete working or mathematical proof.
+<ol>
+<li>You can type markdown text.</li>
+<li>You can type AsciiMath between backticks for mathematics: <code>`...`</code></li>
+<li>You can include LaTeX between brackets, <code>\(...\)</code> for inline mathematics and <code>\[...\]</code> displayed mathematics.</li>
+</ol>
+More specific documentation on markdown, AsciiMath and LaTeX is available online.

doc/en/Authoring/Question_blocks/index.md

@@ -44,6 +44,7 @@ Question blocks are divided into three broad groups.
   * Geogebra
   * Parsons
   * JavaScript
+  * [ASCII](ASCII.md)
 4. [System blocks](System_blocks.md), which are not realy intended for end-users.
 5. [Iframe blocks](Iframe_blocks.md), which allow creation of sandboxed iframes that can be included in the output.
   * Iframe

doc/en/Developer/Development_track.md

@@ -12,10 +12,11 @@ Issues with [github milestone 4.13.0](https://github.com/maths/moodle-qtype_stac
 1. Remove all "cte" code from Maxima - mostly install.
 2. Support for Maxima 5.47.0, 5.48.0, and 5.49.0.  This includes a fix for issue #1281 from 5.48.0.
 3. Question tests can now test the whole route through a PRT, rather than just the final node.  This is a significant improvement on the ability to test questions.  This is back-compatible with older questions.
-4. Add in a new "free-text" input to allow student to input typed free-text proof.
+4. Add in a new ["free-text" input](../Specialist_tools/Free_text_input/index.md) to allow students to input typed free-text proof.
 5. Allow most input types to use the extra option 'manualgraded'.
 6. Expand the use of "align" and "monospace" input options to textarea and equiv inputs.
 
+
 ## Better testing
 
 ### Add in a new keyvals field "test variables".

doc/en/Specialist_tools/Free_text_input/index.md

@@ -0,0 +1,24 @@
+# Free text input
+
+At it's core, STACK provides input boxes into which students can type algebraic expressions. The "equivalence reasoning" input type extends this, allowing multi-line input but that's also limited to algebraic expressions. What's missing is the facility to type a complete mathematical argument.
+
+The free-text input allows students to type a complete mathematical argument.
+
+1. Students type unicode text. Text-formats give complete transparency over what the student types and are future-proof.
+2. Students use markdown for document structure and formatting.
+3. Students can include [AsciiMath](https://asciimath.org/)/Space Math for mathematics.
+4. Students optionally include LaTeX mathematics environments (using brackets `\(...\)`, leaving `$` for currency).
+
+This can be used with [semi-automatic marking](../../Moodle/Semi-automatic_Marking.md).  Or, (algebraic) expressions can be extracted and used in standard STACK inputs for automatic marking.
+
+### Help for students
+
+Built-in help for students can be provided with either
+
+    [[facts:free_text]]
+
+or
+
+    [[hint title="Input help"]][[commonstring key="free_text_fact"/]][[/hint]]
+
+There is also [documentation for students](../../Students/Free_text.md).