| Name | text2qti JSON |
| Version |
0.7.1
JSON |
| download |
| home_page | |
| Summary | Create quizzes in QTI format from Markdown-based plain text |
| upload_time | 2023-10-29 20:17:11 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | BSD 3-Clause License Copyright (c) 2020, Geoffrey M. Poore All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
qti
ims question & test interoperability
quiz
test
exam
assessment
markdown
latex
plain text
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# text2qti – Create quizzes in QTI format from Markdown-based plain text
text2qti converts
[Markdown](https://daringfireball.net/projects/markdown/)-based plain text
files into quizzes in QTI format (version 1.2), which can be imported by
[Canvas](https://www.instructure.com/canvas/) and other educational software.
It supports multiple-choice, true/false, multiple-answers, numerical,
short-answer (fill-in-the-blank), essay, and file-upload questions. It
includes basic support for LaTeX math within Markdown, and allows a limited
subset of [siunitx](https://ctan.org/pkg/siunitx) notation for units and for
numbers in scientific notation.
## Examples
text2qti allows quick and efficient quiz creation. Example
**multiple-choice** plain-text quiz question that can be converted to QTI and
then imported by Canvas:
```
1. What is 2+3?
a) 6
b) 1
*c) 5
```
A **question** is created by a line that starts with a number followed by a
period and one or more spaces or tabs ("`1. `"). Possible **choices** are
created by lines that start with a letter followed by a closing parenthesis
and one or more spaces or tabs ("`a) `"). Numbers and letters do not have to
be ordered or unique. The **correct** choice is designated with an asterisk
("`*c) `"). All question and choice text is processed as
[Markdown](https://daringfireball.net/projects/markdown/).
There is also support for a quiz title and description, as well as question
titles, point values, and feedback. Note that unlike most other text, titles
like quiz and question titles are treated as plain text, not Markdown, due to
the QTI format. **Also note that Canvas correctly shows question titles
within its quiz editor for instructors, but always replaces them with titles
like "Question 1" in the student view.** Question point values must be
positive integers or half-integers.
```
Quiz title: Addition
Quiz description: Checking addition.
Title: An addition question
Points: 2
1. What is 2+3?
... General question feedback.
+ Feedback for correct answer.
- Feedback for incorrect answer.
a) 6
... Feedback for this particular answer.
b) 1
... Feedback for this particular answer.
*c) 5
... Feedback for this particular answer.
```
**Multiple-answers questions** use `[]` or `[ ]` for incorrect answers and
`[*]` for correct answers.
```
1. Which of the following are dinosaurs?
[ ] Woolly mammoth
[*] Tyrannosaurus rex
[*] Triceratops
[ ] Smilodon fatalis
```
**Numerical questions** use an equals sign followed by one or
more spaces or tabs followed by the numerical answer. Acceptable answers can
be designated as a range of the form `[<min>, <max>]` or as a correct answer
with a specified acceptable margin of error `<ans> +- <margin>`. When the
latter form is used, `<margin>` can be either a number or a percentage.
`<margin>` can be omitted when the answer is an integer and an exact answer is
required. In this case, scientific notation is not permitted, but the
underscore can be used as a digit separator; for example, `1000` and `1_000`
are both valid, but `1e3` is not. An exact answer can be required for
floating-point numbers, but this requires an explicit `+- 0`, since a range is
typically more appropriate for floating-point values. Numerical questions
have the limitation that the absolute value of the smallest acceptable answer
must be greater than or equal to 0.0001 (1e-4).
```
1. What is the square root of 2?
= 1.4142 +- 0.0001
2. What is the cube root of 2?
= [1.2598, 1.2600]
3. What is 2+3?
= 5
```
**Short-answer (fill-in-the-blank) questions** use an asterisk followed by one
or more spaces or tabs followed by an answer. Multiple acceptable answers can
be given. Answers are restricted to a single line each and are treated as
plain text, not Markdown.
```
1. Who lives at the North Pole?
* Santa
* Santa Claus
* Father Christmas
* Saint Nicholas
* Saint Nick
```
**Essay questions** are indicated by a sequence of three or more underscores.
They only support general question feedback.
```
1. Write an essay.
... General question feedback.
____
```
**File-upload questions** are indicated by a sequence of three or more
circumflex accents. They only support general question feedback.
```
1. Upload a file.
... General question feedback.
^^^^
```
**Text regions** outside of questions are supported. Note that unlike most
other text, titles like text region titles are treated as plain text, not
Markdown, due to the QTI format. Also note that Canvas apparently ignores the
text region title and only displays the text itself. Text regions are not
required to have both a title and text; either may be used alone, but the
title must come first when both are present.
```
Text title: Instructions about the next questions
Text: General comments about the next questions.
```
## File format
The text2qti file format is a plain-text file format that serves as a wrapper
around Markdown. Each individual chunk of text (question, answer, feedback,
etc.) is Markdown. But the outermost level of text (no indentation) is the
text2qti plain-text quiz format. The fact that the Markdown is indented
within the text2qti format is only really visible when multiple lines of
Markdown are involved. The indentation for each chunk of Markdown text doesn't
have to be 4 spaces; it just has to be the same for the whole chunk of text
that makes up each element of a question.
```
**No indentation: text2qti wrapper syntax for Markdown**
|
| **Indentation: Now using Markdown**
| **Everything below this must have at least this indentation**
| |
1. Question.
| |
| Question continued, so indentation.
| |
*a) Correct answer.
| |
| Correct answer continued, so indentation.
| |
b) Another answer.
| |
```
## Installation
Install **Python 3.8+** if it is not already available on your machine. See
https://www.python.org/, or use the package manager or app store for your
operating system. Depending on your use case, you may want to consider a
Python distribution like [Anaconda](https://www.anaconda.com/distribution/)
instead.
Install
[setuptools](https://packaging.python.org/tutorials/installing-packages/)
for Python if it is not already installed. This can be accomplished by
running
```
python -m pip install setuptools
```
on the command line. Depending on your system, you may need to use `python3`
instead of `python`. This will often be the case for Linux and OS X.
Install text2qti by running this on the command line:
```
python -m pip install text2qti
```
Depending on your system, you may need to use `python3` instead of `python`.
This will often be the case for Linux and OS X.
### Upgrading
```
python -m pip install text2qti --upgrade
```
Depending on your system, you may need to use `python3` instead of `python`.
This will often be the case for Linux and OS X.
### Installing the development version
If you want to install the development version to use the latest features,
download `text2qti` from [GitHub](https://github.com/gpoore/text2qti) and
extract the files. A few different ways to install the development version
are listed below. Depending on your system, you may need to use `python3`
instead of `python` in the commands below. This will often be the case for
Linux and OS X.
* You can install using the included `setup.py` by running
```
python setup.py install
```
Depending on your system configuration, especially if you do not have root
or administrator privileges, you may want to
[customize the installation location](https://docs.python.org/3.8/install/#alternate-installation-the-user-scheme).
For example, you can add `--user` to install under `%APPDATA%\Python` (Windows), `~/.local` (UNIX, and Mac OS X non-framework builds), or
`~/Library/Python/<VERSION>` (Mac framework builds):
```
python setup.py install --user
```
* You can install using `pip`. For example, in the directory with `setup.py`,
run this:
```
python -m pip install .
```
## Usage
text2qti has been designed to create QTI files for use with
[Canvas](https://www.instructure.com/canvas/). Some features may not be
supported by other educational software. You should **always preview**
quizzes or assessments after converting them to QTI and importing them.
Write your quiz or assessment in a plain text file. You can use a basic
editor like Notepad or gedit, or a code editor like
[VS Code](https://code.visualstudio.com/). You can even use Microsoft Word,
as long as you save your file as plain text (*.txt).
text2qti includes a graphical application and a command-line application.
* To use the graphical application, open a command line and run `text2qti_tk`.
* To use the command-line application, open a command line in the same folder
or directory as your quiz file. Under Windows, you can hold the SHIFT
button down on the keyboard, then right click next to your file, and select
"Open PowerShell window here" or "Open command window here". You can also
launch "Command Prompt" or "PowerShell" through the Start menu, and then
navigate to your file using `cd`.
Run the `text2qti` application using a command like this:
```
text2qti quiz.txt
```
Replace "quiz.txt" with the name of your file. This will create a file like
`quiz.zip` (with "quiz" replaced by the name of your file) which is the
converted quiz in QTI format.
Instructions for using the QTI file with Canvas:
* Go to the course in which you want to use the quiz.
* Go to Settings, click on "Import Course Content", select "QTI .zip file",
choose your file, and click "Import". Typically you should not need to
select a question bank; that should be managed automatically.
* While the quiz upload will often be very fast, there is an additional
processing step that can take up to several minutes. The status will
probably appear under "Current Jobs" after upload.
* Once the quiz import is marked as "Completed", the imported quiz should be
available under Quizzes. If the imported quiz does not appear after
several minutes, there may be an error in your quiz file or a bug in
`text2qti`. When Canvas encounters an invalid quiz file, it tends to fail
silently; instead of reporting an error in the quiz file, it just never
creates a quiz based on the invalid file.
* You should **always preview the quiz before use**. text2qti can detect a
number of potential issues, but not everything.
Typically, you should start your quizzes with a title, like this:
```
Quiz title: Title here
```
Otherwise, all quizzes will have the default title "Quiz", so it will be
difficult to tell them apart. Another option is to rename quizzes after
importing them. Note that unlike most other text, the title is treated as
plain text, not Markdown, due to the QTI format.
When you run `text2qti` for the first time, it will attempt to create a
configuration file called `.text2qti.bespon` in your home or user directory.
It will also ask for an institutional LaTeX rendering URL. This is only
needed if you plan to use LaTeX math and if the default URL
`/equation_images/` will not work with your system. In typical cases, you can
simply press ENTER to continue with the default value.
* If you use Canvas, log into your account and look in the browser address
bar. You will typically see an address that starts with something like
`institution.instructure.com/` or `canvas.institution.edu/`, with
`institution` replaced by the name of your school or an abbreviation for
it. The LateX rendering URL that you want to use will then be something
like `https://institution.instructure.com/equation_images/` or
`https://canvas.institution.edu/equation_images/`, with `institution`
replaced by the appropriate value for your school. If the URL is like the
second form, you may need to replace the `.edu` domain with the appropriate
value for your institution.
* If you use other educational software that handles LaTeX in a manner
compatible with Canvas, consult the documentation for your software. Or
perhaps create a simple quiz within the software using its built-in tools,
then export the quiz to QTI and look through the resulting output to find
the URL.
* If you are using educational software that does not handle LaTeX in a
manner compatible with Canvas, try the `--pandoc-mathml` command-line
option when creating QTI files (note that this requires that
[Pandoc](https://pandoc.org/) be installed). If that does not work, please
open an issue requesting support for that software, and include as much
information as possible about how that software processes LaTeX.
## Additional features
### Question groups
A question group contains multiple questions, and only a specified number of
these are randomly selected and used each time a quiz is taken.
```
GROUP
pick: 1
points per question: 1
1. A question.
*a) true
b) false
2. Another question.
*a) true
b) false
END_GROUP
```
The number of questions from the group that are used is specified with
"`pick:`". If this is omitted, it defaults to `1`. The points assigned per
question is specified with "`points per question:`". If this is omitted, it
defaults to `1`. All questions within a group must be worth the same number
of points.
### Executable code blocks
text2qti can execute the code in Markdown-style fenced code blocks. Code can
be used to generate questions within a quiz. Everything written to stdout by
the executed code is included in the quiz file; the code block is replaced by
stdout.
``````
```{.python .run}
import textwrap
for x in [2, 3]:
print(textwrap.dedent(rf"""
1. What is ${x}\times 5$?
*a) ${x*5}$
b) ${x+1}$
"""))
```
``````
For code to be executed, there are a few requirements:
* The code block fences (` ``` `) must not be indented; the code block must be
at the top level of the document, not part of a question, choice, or
feedback. In contrast, a regular code block that is part of a question,
choice, or feedback must be indented as part of that quiz element.
* As a security measure, code execution is disabled by default, so executable
code blocks will trigger an error. Run `text2qti` with the option
`--run-code-blocks` to enable code execution, or set `run_code_blocks =
true` in the text2qti config file in your user or home directory.
* The text immediately after the opening fence must have the form
`{.lang .run}` or `{.lang .run executable=<executable>}`. This is inspired
by the code-block attributes in
[Pandoc Markdown](https://pandoc.org/MANUAL.html).
If the keyword argument `executable` is not provided, then `lang` must
designate an executable that can run the code once the code has been saved
to a file. In the example above, `python` is extracted from the first line
(` ```{.python .run}`), code is saved in a temporary file, and then the
file is executed via `python <file>`.
If `executable` is used to specify an executable, then `lang` is ignored by
`text2qti`, but it is still useful since some editors will use it to provide
syntax highlighting.
When `executable` is specified, the executable path must be quoted with
double quotes `"` if it contains anything other than the tilde, Unicode word
characters, numbers, forward slashes, periods, hyphens, and underscores.
When the executable path is quoted, backslashes and quotation marks are
still prohibited; forward slashes should be used under all operating systems
including Windows. A leading `~` in the executable path is expanded to the
user's home directory under all operating systems including Windows.
* **Special Python note**: When `.python` is used with an executable code
block without specifying an `executable`, code will run with `python3` if
either of these conditions is met:
- `python3` exists on the system and `python` is equivalent to `python2`.
- `python` does not exist on the system, but `python3` does exist.
To avoid ambiguity, you may want to use `.python3` and `.python2` rather
than `.python` when working with operating systems other than Windows, or
when working with a Windows installation that includes a `python3`
executable or symlink. It is also possible to be even more specific by
using something like `.python3.8`.
Each code block is executed in its own process, so data and variables are not
shared between code blocks.
If an executable code block generates multiple questions that are identical,
or multiple choices for a single question that are identical, this will be
detected by `text2qti` and an error will be reported. Questions or choices
that may be equivalent, but are not represented by exactly the same text,
cannot be detected (for example, things like `100` versus `1e2`, or `answer`
versus `Answer`).
### Additional quiz options
There are additional quiz options that can be set immediately after the quiz
title and quiz description. These all take values `true` or `false`. For
example, `shuffle answers: true` could be on the line right after the quiz
description.
* `shuffle answers` — Shuffle answer order for questions.
* `show correct answers` — Show correct answers after submission.
* `one question at a time` — Only show one question at a time.
* `can't go back` — Don't allow going back to the previous question when in
`one question at a time` mode.
## Details for writing quiz text
text2qti processes almost all text as
[Markdown](https://daringfireball.net/projects/markdown/), using
[Python-Markdown](https://python-markdown.github.io/). (The only exceptions
are the quiz title, question titles, and text region titles, which are
processed as plain text due to the QTI format, plus the acceptable answers
for short-answer questions.) For example, `*emphasized*` produces *emphasized*
text, which typically appears as italics. Text can be styled using Markdown
notation, or with HTML. Remember to preview quizzes after conversion to QTI,
especially when using any significant amount of HTML.
Python-Markdown provides several
[extensions to basic Markdown](https://python-markdown.github.io/extensions/).
Currently, the following extensions are enabled:
* `smarty`: Automatic curly quotation marks and dashes.
* `sane_lists`: List behavior is closer to what might be expected.
* `def_list`: Definition lists of this form:
```
term
: definition
* `fenced_code`: Fenced code blocks (` ``` ` or `~~~`).
* `footnotes`: Footnotes using this form:
```
Normal text [^1].
[^1]: Footnote text.
* `tables`: Tables of this form:
```
Header | Header
------ | ------
Cell | Cell
Cell | Cell
```
* `md_in_html`: Text inside HTML tags is treated as Markdown. This requires
setting the attribute `markdown="1"` in the opening tag for block-level
elements. See the
[documentation](https://python-markdown.github.io/extensions/md_in_html/)
for more details about proper usage and potential issues.
While indented Markdown code blocks are supported, fenced code blocks should
be preferred. Indented code can interfere with the preprocessor that strips
HTML comments and handles LaTeX math and siunitx notation.
### Titles
Quiz, question, and text region titles are limited to a single paragraph. If
this paragraph is wrapped over multiple lines, all lines after the first must
be indented by at least two spaces or one tab, and share the same indentation.
All tabs are expanded to 4 spaces before indentation is compared, following
the typical Markdown approach.
All titles are treated as plain text, not Markdown, due to the QTI format.
Titles are always optional, but when they are used for a given element, they
are always required to be first, before any other attributes.
### Descriptions, questions, choices, feedback, and text regions
Descriptions, questions, choices, feedback, and text regions may span multiple
paragraphs and include arbitrary Markdown content like code blocks or
quotations. Everything must be indented to at least the same level as the
start of the first paragraph on the initial line. All tabs are expanded to 4
spaces before indentation is compared, following the typical Markdown
approach. For example,
```
1. A question paragraph that is long enough to wrap onto a second line.
The second line must be indented to match up with the start of the
paragraph text on the first line.
Another paragraph.
```
Note that the acceptable answers for short-answer questions are treated as
plain text and limited to a single line, and numerical answers are also
processed specially and limited to a single line.
### Images
Images are included with the standard Markdown syntax:
```
```
It will typically be easiest to put your image files in the same folder or
directory as the quiz file, so you can use something like ``.
However, file paths are supported, including `~` user expansion under all
operating systems. All image paths not starting with `http://` or `https://`
are assumed to refer to local image files (files on your machine), and will
result in errors if these files are not found.
[Pandoc-style attributes](https://pandoc.org/MANUAL.html#images) can be used
with images:
```
{#id .class1 .class2 width=10em height=5em}
```
This allows image id, classes, and dimensions to be specified without
resorting to HTML.
### LaTeX
By default, text2qti supports LaTeX using a Canvas LaTeX rendering URL that
defaults to `/equation_images/`. This can be customized during installation,
or by editing the configuration file `.text2qti.bespon` in your home or user
directory. It is possible to convert LaTeX to MathML instead with the
`--pandoc-mathml` command-line option. This requires that
[Pandoc](https://pandoc.org/) be installed for converting LaTeX to MathML.
For example, to create a quiz you might run a command like this:
```
text2qti --pandoc-mathml quiz.txt
```
When `--pandoc-mathml` is used, a cache file `_text2qti_cache.zip` will be
created in the quiz file directory. This is used to store Pandoc MathML
output to increase performance for long quizzes with lots of math.
text2qti supports inline LaTeX math within dollar signs `$`. There must be a
non-space character immediately after the opening `$` and immediately before
the closing `$`. For example, `$F = ma$`. LaTeX math is limited to what is
supported by Canvas or whatever other educational software you are using. It
is usually a good idea to preview imported quizzes before assigning them,
because text2qti cannot detect LaTeX incompatibilities or limitations. There
is currently not support for block LaTeX math; only inline math is supported.
When using Canvas with LaTeX math, be aware that in some cases Canvas's
vertical alignment of math leaves much to be desired. Sometimes this can be
improved by including `\vphantom{fg}` or `\strut` at the beginning of an
equation. An alternative is simply to use LaTeX for all question or choice
text (via `\text`, etc.).
text2tqi supports a limited subset of LaTeX
[siunitx](https://ctan.org/pkg/siunitx) notation. You can use notation like
`\num{1.23e5}` to enter numbers in scientific notation. This would result in
`1.23×10⁵`. You can use notation like `\si{m/s}` or `\si{N.m}` to enter
units. These would result in `m/s` and `N·m`. Unit macros currently are not
supported, with these exceptions: `\degree`, `\celsius`, `\fahrenheit`,
`\ohm`, `\micro`. Finally, numbers and units can be combined with notation
like `\SI{1.23e5}{m/s}`. All of these can be used inside or outside LaTeX
math.
Technical note: LaTeX and siunitx support are currently implemented as
preprocessors that are used separately from Python-Markdown. In rare cases,
this may lead to conflicts with Markdown syntax. These features may be
reimplemented as Python-Markdown extensions in the future.
### Comments
There are multiple ways to add comments within a quiz file. In all cases,
comments are completely removed during quiz creation and do not appear in the
final quiz in any form.
At the top level of a quiz document (outside of questions, choices, or
feedback) there are two types of comments. These comments cannot be indented.
* Line comments: Any line that starts with a percent sign `%` is discarded.
* Multiline comments: If a line starts with `COMMENT`, that line and all
subsequent lines are discarded through a line that starts with
`END_COMMENT`. The `COMMENT` and `END_COMMENT` delimiters must be on lines
by themselves; otherwise, an error is raised.
Within Markdown text, standard HTML comments of the form `<!--comment-->` may
be used. These are stripped out during processing and do not appear in the
final QTI file. HTML comments are not supported within LaTeX math.
Technical note: HTML comments are currently stripped in a preprocessing step
separate from Python-Markdown. In rare cases, this may conflict with raw HTML
embedded in Markdown. This feature may be reimplemented as a Python-Markdown
extension in the future.
## Export solutions to PDF and HTML
There is basic support for exporting quiz solutions in Pandoc Markdown, PDF,
and HTML formats. This is currently only available in the command-line
application. Solutions exported as Pandoc Markdown are only suitable for use
with LaTeX and HTML. Exporting solutions as PDF requires
[Pandoc](https://pandoc.org/) and a LaTeX installation (such as [TeX
Live](https://www.tug.org/texlive/) or [MiKTeX](https://miktex.org/)). There
is currently no built-in support for customizing export, although you can edit
the Pandoc Markdown output before processing it via Pandoc.
To save solutions and also create a QTI file, use
`--solutions <solutions_file>`. To save solutions without creating a QTI
file, use `--only-solutions <solutions_file>`. `<solutions_file>` must have
an `.md` or `.markdown` extension for Pandoc Markdown export, `.pdf` for PDF
export, or `.html` for HTML export. `--solutions` and `--only-solutions` can
be used multiple times to generate solutions in multiple formats.
When using `--only-solutions`, be aware that solutions and QTI may differ if
executable code blocks generate problems using random numbers. Consider
creating solutions and QTI at the same time (`--solutions`), or setting a seed
for the random number generator so it is reproducible.
### Customizing questions for solutions
Each question can provide a solution or other important information that is
*only* included in the solutions, *never* in the QTI. This is particularly
useful for essay and upload questions, since they are defined without
specifying an answer and require manual grading. For example,
```
1. Write an essay about text2qti.
! This is important information about what the essay should cover.
This will only appear in the solutions, and can be as long or short as
you wish.
____
```
The syntax for a question solution is the same as that for question feedback,
except that an exclamation point `!` is used instead of `...` or `+` or `-`.
### Quiz options
At the beginning of a quiz, there are some quiz-level options that can be set
to customize solutions. These all take `true`/`false` values, and are `false`
by default. For example, add `solutions sample groups: true` at the beginning
of a quiz.
* `feedback is solution` — This disables the special question solution syntax
involving `!`, and treats general question feedback (`...`) as both feedback
and solution. This is useful when you want to give students solution
information as part of the QTI feedback and also include this same
information in solutions.
* `solutions sample groups` — By default, *all* questions in a question group
are included in solutions, with a notice about the number that are randomly
selected when the quiz is taken, unless the question group has `solutions
pick` set to use a different value.
This option causes only a sample of the questions in a group to be included
in the solutions. This option displays the first N questions in a group
sequentially, where N is the group `solutions pick` value if it has been
set, and otherwise the `pick` value if it has been set, and otherwise 1. It
is possible for solutions to include N random questions from a group instead
of the first N questions; see `solutions randomize groups`.
* `solutions randomize groups` — For each question group, randomize the order
in which questions are displayed in solutions. If only some questions from
a group are included in solutions (`solutions sample groups` is `true` or
`solutions pick` is set), also randomize which questions are displayed
instead of taking all displayed questions sequentially from the beginning of
the group.
Randomization is not used by default for two reasons that relate to quizzes
using `solutions pick` or `solutions sample groups`. First, including group
questions sequentially allows specially chosen, representative questions to
be placed at the beginning of the group so that they will appear in
solutions. If a group contains many questions that are generated by an
executable code block, a random selection might not provide a sample that is
representative. Second, if a quiz is used several semesters or years in a
row with only minor modifications, and new randomized solutions are
distributed each time, this means that eventually all questions would be
distributed in solutions, rather than only a fixed subset.
### Customizing groups for solutions
When a quiz is taken, the number of questions randomly selected from a
question group is the value of `pick` if `pick` is set for the group and
otherwise 1. However, by default solutions will include *all* questions from
a group. There are two ways to modify this.
It is possible to modify the number of questions displayed in solutions for a
specific group by setting `solutions pick` for the group. This causes only
the specified number of questions from the group to be displayed in solutions.
The questions that are displayed are taken sequentially from the beginning of
the group by default, with no randomization. For randomization, see the
quiz-level option `solutions randomize groups`.
It is also possible to modify the number of questions displayed in solutions
for *all* groups in a quiz by setting the quiz-level option `solutions sample
groups` to `true`. This option displays the first N questions in a group
sequentially, where N is the group `solutions pick` value if it has been set,
and otherwise the `pick` value if it has been set, and otherwise 1. It is
possible for solutions to include N random questions from a group instead of
the first N questions; see `solutions randomize groups`.
In the example below, the solutions would include 2 questions from the group,
even though only 1 is displayed when the quiz is taken. The first 2 questions
would be included in solutions, unless `solutions randomize groups: true` is
included at the beginning of the quiz.
```
GROUP
pick: 1
solutions pick: 2
1. A question.
*a) true
b) false
2. Another question.
*a) true
b) false
3. Yet another question.
*a) true
b) false
END_GROUP
```
Raw data
{
"_id": null,
"home_page": "",
"name": "text2qti",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "QTI,IMS Question & Test Interoperability,quiz,test,exam,assessment,markdown,LaTeX,plain text",
"author": "",
"author_email": "\"Geoffrey M. Poore\" <gpoore@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/39/d7/0b492f9c2466b66abfe36cbd751a04fa54c93ea72ee40cf0c1e1643bfd93/text2qti-0.7.1.tar.gz",
"platform": null,
"description": "# text2qti \u2013 Create quizzes in QTI format from Markdown-based plain text\r\n\r\ntext2qti converts\r\n[Markdown](https://daringfireball.net/projects/markdown/)-based plain text\r\nfiles into quizzes in QTI format (version 1.2), which can be imported by\r\n[Canvas](https://www.instructure.com/canvas/) and other educational software.\r\nIt supports multiple-choice, true/false, multiple-answers, numerical,\r\nshort-answer (fill-in-the-blank), essay, and file-upload questions. It\r\nincludes basic support for LaTeX math within Markdown, and allows a limited\r\nsubset of [siunitx](https://ctan.org/pkg/siunitx) notation for units and for\r\nnumbers in scientific notation.\r\n\r\n\r\n\r\n## Examples\r\n\r\ntext2qti allows quick and efficient quiz creation. Example\r\n**multiple-choice** plain-text quiz question that can be converted to QTI and\r\nthen imported by Canvas:\r\n\r\n```\r\n1. What is 2+3?\r\na) 6\r\nb) 1\r\n*c) 5\r\n```\r\n\r\nA **question** is created by a line that starts with a number followed by a\r\nperiod and one or more spaces or tabs (\"`1. `\"). Possible **choices** are\r\ncreated by lines that start with a letter followed by a closing parenthesis\r\nand one or more spaces or tabs (\"`a) `\"). Numbers and letters do not have to\r\nbe ordered or unique. The **correct** choice is designated with an asterisk\r\n(\"`*c) `\"). All question and choice text is processed as\r\n[Markdown](https://daringfireball.net/projects/markdown/).\r\n\r\nThere is also support for a quiz title and description, as well as question\r\ntitles, point values, and feedback. Note that unlike most other text, titles\r\nlike quiz and question titles are treated as plain text, not Markdown, due to\r\nthe QTI format. **Also note that Canvas correctly shows question titles\r\nwithin its quiz editor for instructors, but always replaces them with titles\r\nlike \"Question 1\" in the student view.** Question point values must be\r\npositive integers or half-integers.\r\n\r\n```\r\nQuiz title: Addition\r\nQuiz description: Checking addition.\r\n\r\nTitle: An addition question\r\nPoints: 2\r\n1. What is 2+3?\r\n... General question feedback.\r\n+ Feedback for correct answer.\r\n- Feedback for incorrect answer.\r\na) 6\r\n... Feedback for this particular answer.\r\nb) 1\r\n... Feedback for this particular answer.\r\n*c) 5\r\n... Feedback for this particular answer.\r\n```\r\n\r\n**Multiple-answers questions** use `[]` or `[ ]` for incorrect answers and\r\n`[*]` for correct answers.\r\n\r\n```\r\n1. Which of the following are dinosaurs?\r\n[ ] Woolly mammoth\r\n[*] Tyrannosaurus rex\r\n[*] Triceratops\r\n[ ] Smilodon fatalis\r\n```\r\n\r\n**Numerical questions** use an equals sign followed by one or\r\nmore spaces or tabs followed by the numerical answer. Acceptable answers can\r\nbe designated as a range of the form `[<min>, <max>]` or as a correct answer\r\nwith a specified acceptable margin of error `<ans> +- <margin>`. When the\r\nlatter form is used, `<margin>` can be either a number or a percentage.\r\n`<margin>` can be omitted when the answer is an integer and an exact answer is\r\nrequired. In this case, scientific notation is not permitted, but the\r\nunderscore can be used as a digit separator; for example, `1000` and `1_000`\r\nare both valid, but `1e3` is not. An exact answer can be required for\r\nfloating-point numbers, but this requires an explicit `+- 0`, since a range is\r\ntypically more appropriate for floating-point values. Numerical questions\r\nhave the limitation that the absolute value of the smallest acceptable answer\r\nmust be greater than or equal to 0.0001 (1e-4).\r\n\r\n```\r\n1. What is the square root of 2?\r\n= 1.4142 +- 0.0001\r\n\r\n2. What is the cube root of 2?\r\n= [1.2598, 1.2600]\r\n\r\n3. What is 2+3?\r\n= 5\r\n```\r\n\r\n**Short-answer (fill-in-the-blank) questions** use an asterisk followed by one\r\nor more spaces or tabs followed by an answer. Multiple acceptable answers can\r\nbe given. Answers are restricted to a single line each and are treated as\r\nplain text, not Markdown.\r\n```\r\n1. Who lives at the North Pole?\r\n* Santa\r\n* Santa Claus\r\n* Father Christmas\r\n* Saint Nicholas\r\n* Saint Nick\r\n```\r\n\r\n**Essay questions** are indicated by a sequence of three or more underscores.\r\nThey only support general question feedback.\r\n\r\n```\r\n1. Write an essay.\r\n... General question feedback.\r\n____\r\n```\r\n\r\n**File-upload questions** are indicated by a sequence of three or more\r\ncircumflex accents. They only support general question feedback.\r\n```\r\n1. Upload a file.\r\n... General question feedback.\r\n^^^^\r\n```\r\n\r\n**Text regions** outside of questions are supported. Note that unlike most\r\nother text, titles like text region titles are treated as plain text, not\r\nMarkdown, due to the QTI format. Also note that Canvas apparently ignores the\r\ntext region title and only displays the text itself. Text regions are not\r\nrequired to have both a title and text; either may be used alone, but the\r\ntitle must come first when both are present.\r\n```\r\nText title: Instructions about the next questions\r\nText: General comments about the next questions.\r\n```\r\n\r\n\r\n## File format\r\n\r\nThe text2qti file format is a plain-text file format that serves as a wrapper\r\naround Markdown. Each individual chunk of text (question, answer, feedback,\r\netc.) is Markdown. But the outermost level of text (no indentation) is the\r\ntext2qti plain-text quiz format. The fact that the Markdown is indented\r\nwithin the text2qti format is only really visible when multiple lines of\r\nMarkdown are involved. The indentation for each chunk of Markdown text doesn't\r\nhave to be 4 spaces; it just has to be the same for the whole chunk of text\r\nthat makes up each element of a question.\r\n\r\n```\r\n**No indentation: text2qti wrapper syntax for Markdown**\r\n|\r\n| **Indentation: Now using Markdown**\r\n| **Everything below this must have at least this indentation**\r\n| |\r\n1. Question.\r\n| |\r\n| Question continued, so indentation.\r\n| |\r\n*a) Correct answer.\r\n| |\r\n| Correct answer continued, so indentation.\r\n| |\r\nb) Another answer.\r\n| |\r\n```\r\n\r\n\r\n## Installation\r\n\r\nInstall **Python 3.8+** if it is not already available on your machine. See\r\nhttps://www.python.org/, or use the package manager or app store for your\r\noperating system. Depending on your use case, you may want to consider a\r\nPython distribution like [Anaconda](https://www.anaconda.com/distribution/)\r\ninstead.\r\n\r\nInstall\r\n[setuptools](https://packaging.python.org/tutorials/installing-packages/)\r\nfor Python if it is not already installed. This can be accomplished by\r\nrunning\r\n```\r\npython -m pip install setuptools\r\n```\r\non the command line. Depending on your system, you may need to use `python3`\r\ninstead of `python`. This will often be the case for Linux and OS X.\r\n\r\nInstall text2qti by running this on the command line:\r\n```\r\npython -m pip install text2qti\r\n```\r\nDepending on your system, you may need to use `python3` instead of `python`.\r\nThis will often be the case for Linux and OS X.\r\n\r\n\r\n### Upgrading\r\n\r\n```\r\npython -m pip install text2qti --upgrade\r\n```\r\nDepending on your system, you may need to use `python3` instead of `python`.\r\nThis will often be the case for Linux and OS X.\r\n\r\n\r\n### Installing the development version\r\n\r\nIf you want to install the development version to use the latest features,\r\ndownload `text2qti` from [GitHub](https://github.com/gpoore/text2qti) and\r\nextract the files. A few different ways to install the development version\r\nare listed below. Depending on your system, you may need to use `python3`\r\ninstead of `python` in the commands below. This will often be the case for\r\nLinux and OS X.\r\n\r\n* You can install using the included `setup.py` by running\r\n ```\r\n python setup.py install\r\n ```\r\n Depending on your system configuration, especially if you do not have root\r\n or administrator privileges, you may want to\r\n [customize the installation location](https://docs.python.org/3.8/install/#alternate-installation-the-user-scheme).\r\n For example, you can add `--user` to install under `%APPDATA%\\Python` (Windows), `~/.local` (UNIX, and Mac OS X non-framework builds), or\r\n `~/Library/Python/<VERSION>` (Mac framework builds):\r\n ```\r\n python setup.py install --user\r\n ```\r\n* You can install using `pip`. For example, in the directory with `setup.py`,\r\n run this:\r\n ```\r\n python -m pip install .\r\n ```\r\n\r\n\r\n\r\n\r\n## Usage\r\n\r\ntext2qti has been designed to create QTI files for use with\r\n[Canvas](https://www.instructure.com/canvas/). Some features may not be\r\nsupported by other educational software. You should **always preview**\r\nquizzes or assessments after converting them to QTI and importing them.\r\n\r\nWrite your quiz or assessment in a plain text file. You can use a basic\r\neditor like Notepad or gedit, or a code editor like\r\n[VS Code](https://code.visualstudio.com/). You can even use Microsoft Word,\r\nas long as you save your file as plain text (*.txt).\r\n\r\ntext2qti includes a graphical application and a command-line application.\r\n\r\n* To use the graphical application, open a command line and run `text2qti_tk`.\r\n\r\n* To use the command-line application, open a command line in the same folder\r\n or directory as your quiz file. Under Windows, you can hold the SHIFT\r\n button down on the keyboard, then right click next to your file, and select\r\n \"Open PowerShell window here\" or \"Open command window here\". You can also\r\n launch \"Command Prompt\" or \"PowerShell\" through the Start menu, and then\r\n navigate to your file using `cd`.\r\n\r\n Run the `text2qti` application using a command like this:\r\n ```\r\n text2qti quiz.txt\r\n ```\r\n Replace \"quiz.txt\" with the name of your file. This will create a file like\r\n `quiz.zip` (with \"quiz\" replaced by the name of your file) which is the\r\n converted quiz in QTI format.\r\n\r\nInstructions for using the QTI file with Canvas:\r\n * Go to the course in which you want to use the quiz.\r\n * Go to Settings, click on \"Import Course Content\", select \"QTI .zip file\",\r\n choose your file, and click \"Import\". Typically you should not need to\r\n select a question bank; that should be managed automatically.\r\n * While the quiz upload will often be very fast, there is an additional\r\n processing step that can take up to several minutes. The status will\r\n probably appear under \"Current Jobs\" after upload.\r\n * Once the quiz import is marked as \"Completed\", the imported quiz should be\r\n available under Quizzes. If the imported quiz does not appear after\r\n several minutes, there may be an error in your quiz file or a bug in\r\n `text2qti`. When Canvas encounters an invalid quiz file, it tends to fail\r\n silently; instead of reporting an error in the quiz file, it just never\r\n creates a quiz based on the invalid file.\r\n * You should **always preview the quiz before use**. text2qti can detect a\r\n number of potential issues, but not everything.\r\n\r\nTypically, you should start your quizzes with a title, like this:\r\n```\r\nQuiz title: Title here\r\n```\r\nOtherwise, all quizzes will have the default title \"Quiz\", so it will be\r\ndifficult to tell them apart. Another option is to rename quizzes after\r\nimporting them. Note that unlike most other text, the title is treated as\r\nplain text, not Markdown, due to the QTI format.\r\n\r\nWhen you run `text2qti` for the first time, it will attempt to create a\r\nconfiguration file called `.text2qti.bespon` in your home or user directory.\r\nIt will also ask for an institutional LaTeX rendering URL. This is only\r\nneeded if you plan to use LaTeX math and if the default URL\r\n`/equation_images/` will not work with your system. In typical cases, you can\r\nsimply press ENTER to continue with the default value.\r\n * If you use Canvas, log into your account and look in the browser address\r\n bar. You will typically see an address that starts with something like\r\n `institution.instructure.com/` or `canvas.institution.edu/`, with\r\n `institution` replaced by the name of your school or an abbreviation for\r\n it. The LateX rendering URL that you want to use will then be something\r\n like `https://institution.instructure.com/equation_images/` or\r\n `https://canvas.institution.edu/equation_images/`, with `institution`\r\n replaced by the appropriate value for your school. If the URL is like the\r\n second form, you may need to replace the `.edu` domain with the appropriate\r\n value for your institution.\r\n * If you use other educational software that handles LaTeX in a manner\r\n compatible with Canvas, consult the documentation for your software. Or\r\n perhaps create a simple quiz within the software using its built-in tools,\r\n then export the quiz to QTI and look through the resulting output to find\r\n the URL.\r\n * If you are using educational software that does not handle LaTeX in a\r\n manner compatible with Canvas, try the `--pandoc-mathml` command-line\r\n option when creating QTI files (note that this requires that\r\n [Pandoc](https://pandoc.org/) be installed). If that does not work, please\r\n open an issue requesting support for that software, and include as much\r\n information as possible about how that software processes LaTeX.\r\n\r\n\r\n\r\n## Additional features\r\n\r\n### Question groups\r\n\r\nA question group contains multiple questions, and only a specified number of\r\nthese are randomly selected and used each time a quiz is taken.\r\n\r\n```\r\nGROUP\r\npick: 1\r\npoints per question: 1\r\n\r\n1. A question.\r\n*a) true\r\nb) false\r\n\r\n2. Another question.\r\n*a) true\r\nb) false\r\n\r\nEND_GROUP\r\n```\r\n\r\nThe number of questions from the group that are used is specified with\r\n\"`pick:`\". If this is omitted, it defaults to `1`. The points assigned per\r\nquestion is specified with \"`points per question:`\". If this is omitted, it\r\ndefaults to `1`. All questions within a group must be worth the same number\r\nof points.\r\n\r\n\r\n### Executable code blocks\r\n\r\ntext2qti can execute the code in Markdown-style fenced code blocks. Code can\r\nbe used to generate questions within a quiz. Everything written to stdout by\r\nthe executed code is included in the quiz file; the code block is replaced by\r\nstdout.\r\n\r\n``````\r\n```{.python .run}\r\nimport textwrap\r\nfor x in [2, 3]:\r\n print(textwrap.dedent(rf\"\"\"\r\n 1. What is ${x}\\times 5$?\r\n *a) ${x*5}$\r\n b) ${x+1}$\r\n \"\"\"))\r\n```\r\n``````\r\n\r\n\r\nFor code to be executed, there are a few requirements:\r\n\r\n* The code block fences (` ``` `) must not be indented; the code block must be\r\n at the top level of the document, not part of a question, choice, or\r\n feedback. In contrast, a regular code block that is part of a question,\r\n choice, or feedback must be indented as part of that quiz element.\r\n\r\n* As a security measure, code execution is disabled by default, so executable\r\n code blocks will trigger an error. Run `text2qti` with the option\r\n `--run-code-blocks` to enable code execution, or set `run_code_blocks =\r\n true` in the text2qti config file in your user or home directory.\r\n\r\n* The text immediately after the opening fence must have the form\r\n `{.lang .run}` or `{.lang .run executable=<executable>}`. This is inspired\r\n by the code-block attributes in\r\n [Pandoc Markdown](https://pandoc.org/MANUAL.html).\r\n\r\n If the keyword argument `executable` is not provided, then `lang` must\r\n designate an executable that can run the code once the code has been saved\r\n to a file. In the example above, `python` is extracted from the first line\r\n (` ```{.python .run}`), code is saved in a temporary file, and then the\r\n file is executed via `python <file>`.\r\n\r\n If `executable` is used to specify an executable, then `lang` is ignored by\r\n `text2qti`, but it is still useful since some editors will use it to provide\r\n syntax highlighting.\r\n\r\n When `executable` is specified, the executable path must be quoted with\r\n double quotes `\"` if it contains anything other than the tilde, Unicode word\r\n characters, numbers, forward slashes, periods, hyphens, and underscores.\r\n When the executable path is quoted, backslashes and quotation marks are\r\n still prohibited; forward slashes should be used under all operating systems\r\n including Windows. A leading `~` in the executable path is expanded to the\r\n user's home directory under all operating systems including Windows.\r\n\r\n* **Special Python note**: When `.python` is used with an executable code\r\n block without specifying an `executable`, code will run with `python3` if\r\n either of these conditions is met:\r\n\r\n - `python3` exists on the system and `python` is equivalent to `python2`.\r\n\r\n - `python` does not exist on the system, but `python3` does exist.\r\n\r\n To avoid ambiguity, you may want to use `.python3` and `.python2` rather\r\n than `.python` when working with operating systems other than Windows, or\r\n when working with a Windows installation that includes a `python3`\r\n executable or symlink. It is also possible to be even more specific by\r\n using something like `.python3.8`.\r\n\r\nEach code block is executed in its own process, so data and variables are not\r\nshared between code blocks.\r\n\r\nIf an executable code block generates multiple questions that are identical,\r\nor multiple choices for a single question that are identical, this will be\r\ndetected by `text2qti` and an error will be reported. Questions or choices\r\nthat may be equivalent, but are not represented by exactly the same text,\r\ncannot be detected (for example, things like `100` versus `1e2`, or `answer`\r\nversus `Answer`).\r\n\r\n\r\n### Additional quiz options\r\n\r\nThere are additional quiz options that can be set immediately after the quiz\r\ntitle and quiz description. These all take values `true` or `false`. For\r\nexample, `shuffle answers: true` could be on the line right after the quiz\r\ndescription.\r\n\r\n* `shuffle answers` \u2014 Shuffle answer order for questions.\r\n* `show correct answers` \u2014 Show correct answers after submission.\r\n* `one question at a time` \u2014 Only show one question at a time.\r\n* `can't go back` \u2014 Don't allow going back to the previous question when in\r\n `one question at a time` mode.\r\n\r\n\r\n\r\n\r\n## Details for writing quiz text\r\n\r\ntext2qti processes almost all text as\r\n[Markdown](https://daringfireball.net/projects/markdown/), using\r\n[Python-Markdown](https://python-markdown.github.io/). (The only exceptions\r\nare the quiz title, question titles, and text region titles, which are\r\nprocessed as plain text due to the QTI format, plus the acceptable answers\r\nfor short-answer questions.) For example, `*emphasized*` produces *emphasized*\r\ntext, which typically appears as italics. Text can be styled using Markdown\r\nnotation, or with HTML. Remember to preview quizzes after conversion to QTI,\r\nespecially when using any significant amount of HTML.\r\n\r\nPython-Markdown provides several\r\n[extensions to basic Markdown](https://python-markdown.github.io/extensions/).\r\nCurrently, the following extensions are enabled:\r\n* `smarty`: Automatic curly quotation marks and dashes.\r\n* `sane_lists`: List behavior is closer to what might be expected.\r\n* `def_list`: Definition lists of this form:\r\n ```\r\n term\r\n : definition\r\n* `fenced_code`: Fenced code blocks (` ``` ` or `~~~`).\r\n* `footnotes`: Footnotes using this form:\r\n ```\r\n Normal text [^1].\r\n\r\n [^1]: Footnote text.\r\n* `tables`: Tables of this form:\r\n ```\r\n Header | Header\r\n ------ | ------\r\n Cell | Cell\r\n Cell | Cell\r\n ```\r\n* `md_in_html`: Text inside HTML tags is treated as Markdown. This requires\r\n setting the attribute `markdown=\"1\"` in the opening tag for block-level\r\n elements. See the\r\n [documentation](https://python-markdown.github.io/extensions/md_in_html/)\r\n for more details about proper usage and potential issues.\r\n\r\nWhile indented Markdown code blocks are supported, fenced code blocks should\r\nbe preferred. Indented code can interfere with the preprocessor that strips\r\nHTML comments and handles LaTeX math and siunitx notation.\r\n\r\n\r\n### Titles\r\n\r\nQuiz, question, and text region titles are limited to a single paragraph. If\r\nthis paragraph is wrapped over multiple lines, all lines after the first must\r\nbe indented by at least two spaces or one tab, and share the same indentation.\r\nAll tabs are expanded to 4 spaces before indentation is compared, following\r\nthe typical Markdown approach.\r\n\r\nAll titles are treated as plain text, not Markdown, due to the QTI format.\r\n\r\nTitles are always optional, but when they are used for a given element, they\r\nare always required to be first, before any other attributes.\r\n\r\n\r\n### Descriptions, questions, choices, feedback, and text regions\r\n\r\nDescriptions, questions, choices, feedback, and text regions may span multiple\r\nparagraphs and include arbitrary Markdown content like code blocks or\r\nquotations. Everything must be indented to at least the same level as the\r\nstart of the first paragraph on the initial line. All tabs are expanded to 4\r\nspaces before indentation is compared, following the typical Markdown\r\napproach. For example,\r\n```\r\n1. A question paragraph that is long enough to wrap onto a second line.\r\n The second line must be indented to match up with the start of the\r\n paragraph text on the first line.\r\n\r\n Another paragraph.\r\n```\r\nNote that the acceptable answers for short-answer questions are treated as\r\nplain text and limited to a single line, and numerical answers are also\r\nprocessed specially and limited to a single line.\r\n\r\n\r\n### Images\r\n\r\nImages are included with the standard Markdown syntax:\r\n```\r\n\r\n```\r\nIt will typically be easiest to put your image files in the same folder or\r\ndirectory as the quiz file, so you can use something like ``.\r\nHowever, file paths are supported, including `~` user expansion under all\r\noperating systems. All image paths not starting with `http://` or `https://`\r\nare assumed to refer to local image files (files on your machine), and will\r\nresult in errors if these files are not found.\r\n\r\n[Pandoc-style attributes](https://pandoc.org/MANUAL.html#images) can be used\r\nwith images:\r\n```\r\n{#id .class1 .class2 width=10em height=5em}\r\n```\r\nThis allows image id, classes, and dimensions to be specified without\r\nresorting to HTML.\r\n\r\n\r\n### LaTeX\r\n\r\nBy default, text2qti supports LaTeX using a Canvas LaTeX rendering URL that\r\ndefaults to `/equation_images/`. This can be customized during installation,\r\nor by editing the configuration file `.text2qti.bespon` in your home or user\r\ndirectory. It is possible to convert LaTeX to MathML instead with the\r\n`--pandoc-mathml` command-line option. This requires that\r\n[Pandoc](https://pandoc.org/) be installed for converting LaTeX to MathML.\r\nFor example, to create a quiz you might run a command like this:\r\n```\r\ntext2qti --pandoc-mathml quiz.txt\r\n```\r\nWhen `--pandoc-mathml` is used, a cache file `_text2qti_cache.zip` will be\r\ncreated in the quiz file directory. This is used to store Pandoc MathML\r\noutput to increase performance for long quizzes with lots of math.\r\n\r\ntext2qti supports inline LaTeX math within dollar signs `$`. There must be a\r\nnon-space character immediately after the opening `$` and immediately before\r\nthe closing `$`. For example, `$F = ma$`. LaTeX math is limited to what is\r\nsupported by Canvas or whatever other educational software you are using. It\r\nis usually a good idea to preview imported quizzes before assigning them,\r\nbecause text2qti cannot detect LaTeX incompatibilities or limitations. There\r\nis currently not support for block LaTeX math; only inline math is supported.\r\n\r\nWhen using Canvas with LaTeX math, be aware that in some cases Canvas's\r\nvertical alignment of math leaves much to be desired. Sometimes this can be\r\nimproved by including `\\vphantom{fg}` or `\\strut` at the beginning of an\r\nequation. An alternative is simply to use LaTeX for all question or choice\r\ntext (via `\\text`, etc.).\r\n\r\ntext2tqi supports a limited subset of LaTeX\r\n[siunitx](https://ctan.org/pkg/siunitx) notation. You can use notation like\r\n`\\num{1.23e5}` to enter numbers in scientific notation. This would result in\r\n`1.23\u00d710\u2075`. You can use notation like `\\si{m/s}` or `\\si{N.m}` to enter\r\nunits. These would result in `m/s` and `N\u00b7m`. Unit macros currently are not\r\nsupported, with these exceptions: `\\degree`, `\\celsius`, `\\fahrenheit`,\r\n`\\ohm`, `\\micro`. Finally, numbers and units can be combined with notation\r\nlike `\\SI{1.23e5}{m/s}`. All of these can be used inside or outside LaTeX\r\nmath.\r\n\r\nTechnical note: LaTeX and siunitx support are currently implemented as\r\npreprocessors that are used separately from Python-Markdown. In rare cases,\r\nthis may lead to conflicts with Markdown syntax. These features may be\r\nreimplemented as Python-Markdown extensions in the future.\r\n\r\n\r\n### Comments\r\n\r\nThere are multiple ways to add comments within a quiz file. In all cases,\r\ncomments are completely removed during quiz creation and do not appear in the\r\nfinal quiz in any form.\r\n\r\nAt the top level of a quiz document (outside of questions, choices, or\r\nfeedback) there are two types of comments. These comments cannot be indented.\r\n* Line comments: Any line that starts with a percent sign `%` is discarded.\r\n* Multiline comments: If a line starts with `COMMENT`, that line and all\r\n subsequent lines are discarded through a line that starts with\r\n `END_COMMENT`. The `COMMENT` and `END_COMMENT` delimiters must be on lines\r\n by themselves; otherwise, an error is raised.\r\n\r\nWithin Markdown text, standard HTML comments of the form `<!--comment-->` may\r\nbe used. These are stripped out during processing and do not appear in the\r\nfinal QTI file. HTML comments are not supported within LaTeX math.\r\n\r\nTechnical note: HTML comments are currently stripped in a preprocessing step\r\nseparate from Python-Markdown. In rare cases, this may conflict with raw HTML\r\nembedded in Markdown. This feature may be reimplemented as a Python-Markdown\r\nextension in the future.\r\n\r\n\r\n\r\n## Export solutions to PDF and HTML\r\n\r\nThere is basic support for exporting quiz solutions in Pandoc Markdown, PDF,\r\nand HTML formats. This is currently only available in the command-line\r\napplication. Solutions exported as Pandoc Markdown are only suitable for use\r\nwith LaTeX and HTML. Exporting solutions as PDF requires\r\n[Pandoc](https://pandoc.org/) and a LaTeX installation (such as [TeX\r\nLive](https://www.tug.org/texlive/) or [MiKTeX](https://miktex.org/)). There\r\nis currently no built-in support for customizing export, although you can edit\r\nthe Pandoc Markdown output before processing it via Pandoc.\r\n\r\nTo save solutions and also create a QTI file, use\r\n`--solutions <solutions_file>`. To save solutions without creating a QTI\r\nfile, use `--only-solutions <solutions_file>`. `<solutions_file>` must have\r\nan `.md` or `.markdown` extension for Pandoc Markdown export, `.pdf` for PDF\r\nexport, or `.html` for HTML export. `--solutions` and `--only-solutions` can\r\nbe used multiple times to generate solutions in multiple formats.\r\n\r\nWhen using `--only-solutions`, be aware that solutions and QTI may differ if\r\nexecutable code blocks generate problems using random numbers. Consider\r\ncreating solutions and QTI at the same time (`--solutions`), or setting a seed\r\nfor the random number generator so it is reproducible.\r\n\r\n\r\n### Customizing questions for solutions\r\n\r\nEach question can provide a solution or other important information that is\r\n*only* included in the solutions, *never* in the QTI. This is particularly\r\nuseful for essay and upload questions, since they are defined without\r\nspecifying an answer and require manual grading. For example,\r\n```\r\n1. Write an essay about text2qti.\r\n\r\n! This is important information about what the essay should cover.\r\n\r\n This will only appear in the solutions, and can be as long or short as\r\n you wish.\r\n\r\n____\r\n```\r\nThe syntax for a question solution is the same as that for question feedback,\r\nexcept that an exclamation point `!` is used instead of `...` or `+` or `-`.\r\n\r\n\r\n### Quiz options\r\n\r\nAt the beginning of a quiz, there are some quiz-level options that can be set\r\nto customize solutions. These all take `true`/`false` values, and are `false`\r\nby default. For example, add `solutions sample groups: true` at the beginning\r\nof a quiz.\r\n\r\n* `feedback is solution` \u2014 This disables the special question solution syntax\r\n involving `!`, and treats general question feedback (`...`) as both feedback\r\n and solution. This is useful when you want to give students solution\r\n information as part of the QTI feedback and also include this same\r\n information in solutions.\r\n\r\n* `solutions sample groups` \u2014 By default, *all* questions in a question group\r\n are included in solutions, with a notice about the number that are randomly\r\n selected when the quiz is taken, unless the question group has `solutions\r\n pick` set to use a different value.\r\n\r\n This option causes only a sample of the questions in a group to be included\r\n in the solutions. This option displays the first N questions in a group\r\n sequentially, where N is the group `solutions pick` value if it has been\r\n set, and otherwise the `pick` value if it has been set, and otherwise 1. It\r\n is possible for solutions to include N random questions from a group instead\r\n of the first N questions; see `solutions randomize groups`.\r\n\r\n* `solutions randomize groups` \u2014 For each question group, randomize the order\r\n in which questions are displayed in solutions. If only some questions from\r\n a group are included in solutions (`solutions sample groups` is `true` or\r\n `solutions pick` is set), also randomize which questions are displayed\r\n instead of taking all displayed questions sequentially from the beginning of\r\n the group.\r\n\r\n Randomization is not used by default for two reasons that relate to quizzes\r\n using `solutions pick` or `solutions sample groups`. First, including group\r\n questions sequentially allows specially chosen, representative questions to\r\n be placed at the beginning of the group so that they will appear in\r\n solutions. If a group contains many questions that are generated by an\r\n executable code block, a random selection might not provide a sample that is\r\n representative. Second, if a quiz is used several semesters or years in a\r\n row with only minor modifications, and new randomized solutions are\r\n distributed each time, this means that eventually all questions would be\r\n distributed in solutions, rather than only a fixed subset.\r\n\r\n\r\n### Customizing groups for solutions\r\n\r\nWhen a quiz is taken, the number of questions randomly selected from a\r\nquestion group is the value of `pick` if `pick` is set for the group and\r\notherwise 1. However, by default solutions will include *all* questions from\r\na group. There are two ways to modify this.\r\n\r\nIt is possible to modify the number of questions displayed in solutions for a\r\nspecific group by setting `solutions pick` for the group. This causes only\r\nthe specified number of questions from the group to be displayed in solutions.\r\nThe questions that are displayed are taken sequentially from the beginning of\r\nthe group by default, with no randomization. For randomization, see the\r\nquiz-level option `solutions randomize groups`.\r\n\r\nIt is also possible to modify the number of questions displayed in solutions\r\nfor *all* groups in a quiz by setting the quiz-level option `solutions sample\r\ngroups` to `true`. This option displays the first N questions in a group\r\nsequentially, where N is the group `solutions pick` value if it has been set,\r\nand otherwise the `pick` value if it has been set, and otherwise 1. It is\r\npossible for solutions to include N random questions from a group instead of\r\nthe first N questions; see `solutions randomize groups`.\r\n\r\nIn the example below, the solutions would include 2 questions from the group,\r\neven though only 1 is displayed when the quiz is taken. The first 2 questions\r\nwould be included in solutions, unless `solutions randomize groups: true` is\r\nincluded at the beginning of the quiz.\r\n\r\n```\r\nGROUP\r\npick: 1\r\nsolutions pick: 2\r\n\r\n1. A question.\r\n*a) true\r\nb) false\r\n\r\n2. Another question.\r\n*a) true\r\nb) false\r\n\r\n3. Yet another question.\r\n*a) true\r\nb) false\r\n\r\nEND_GROUP\r\n```\r\n\r\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2020, Geoffrey M. Poore All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Create quizzes in QTI format from Markdown-based plain text",
"version": "0.7.1",
"project_urls": {
"changelog": "http://github.com/gpoore/text2qti/blob/master/CHANGELOG.md",
"repository": "http://github.com/gpoore/text2qti"
},
"split_keywords": [
"qti",
"ims question & test interoperability",
"quiz",
"test",
"exam",
"assessment",
"markdown",
"latex",
"plain text"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d049ede6672356c383f6b25e67f26c199eaac05fe2b57ede1cf46a2dbd69560c",
"md5": "73063dddeb35d236dc44ac4ed1f54f8a",
"sha256": "319ca23dbd3a1117c42c8b2efcb4834b4c5eede3b83b0913168859dbc8ebdaba"
},
"downloads": -1,
"filename": "text2qti-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73063dddeb35d236dc44ac4ed1f54f8a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 55954,
"upload_time": "2023-10-29T20:17:05",
"upload_time_iso_8601": "2023-10-29T20:17:05.733605Z",
"url": "https://files.pythonhosted.org/packages/d0/49/ede6672356c383f6b25e67f26c199eaac05fe2b57ede1cf46a2dbd69560c/text2qti-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "39d70b492f9c2466b66abfe36cbd751a04fa54c93ea72ee40cf0c1e1643bfd93",
"md5": "fd208dc8e7b766f4c65be423ea959d04",
"sha256": "05ede70e7db2b2650efab57f284b165b545416052b57a4aee8f5b14d9b2a990b"
},
"downloads": -1,
"filename": "text2qti-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "fd208dc8e7b766f4c65be423ea959d04",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 70535,
"upload_time": "2023-10-29T20:17:11",
"upload_time_iso_8601": "2023-10-29T20:17:11.260057Z",
"url": "https://files.pythonhosted.org/packages/39/d7/0b492f9c2466b66abfe36cbd751a04fa54c93ea72ee40cf0c1e1643bfd93/text2qti-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-29 20:17:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gpoore",
"github_project": "text2qti",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "text2qti"
}
