# gift-wrapper
This is Python software to easily build [GIFT](https://docs.moodle.org/en/GIFT_format) -based [question banks](https://docs.moodle.org/en/Question_bank) in [Moodle](https://moodle.org/). Other similar tools are available (you can search for *Tools that create or process GIFTs* in [Moodle's GIFT page](https://docs.moodle.org/en/GIFT_format)) but none of them fitted well my workflow. What I need is (the goals of `gift-wrapper` are):
* to write questions in plain text, and as many as I like in a single file
* to write latex formulas directly
* to easily/seamlessly include images
The most interesting point is probably the last one.
## Requirements
Python requirements are:
- Python ≥ 3.10
- [paramiko](http://www.paramiko.org/)
- [colorama](https://pypi.org/project/colorama/)
- [pyyaml](https://pypi.org/project/PyYAML/)
- [tqdm](https://github.com/tqdm/tqdm)
Now, if you want to make the most of the software you also need:
* [pdflatex](https://en.wikipedia.org/wiki/PdfTeX) (i.e. a [TeX](https://en.wikipedia.org/wiki/TeX) distribution)
* [pdf2svg](https://github.com/dawbarton/pdf2svg/)
* disk space in a remote server that can host your images
## Install
```
pip install gift-wrapper
```
should suffice.
### Manual setup
If you rather clone this repository, (in order to, potentially, get the latest additions/modifications)
```
pip install pyyaml paramiko tqdm colorama
```
should install all the additional requirements. If you use [Anaconda](https://anaconda.org/), the [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) script `make_conda_environment.sh` will make a proper environment (named `gift`).
After that, you should be able to run the program.
## Usage
The main program is `wrap.py` and you can check the available command-line options with
```
wrap.py -h
```
or
```
python wrap.py -h
```
if you did a manual installation and `wrap.py` doesn't have execution permissions.
If you don't pass any argument, `parameters.yaml` and `bank.yaml` files are expected. The former is a settings file whereas the latter is the actual *input file* in which you must write the questions.
The output will be a text file in GIFT format with the same name as the input (the file with the questions) but `.gift.txt` extension (thus, `bank.gift.txt`, by default). It seems that *sometimes* Moodle has troubles importing (recognizing) a text file if the extension is not `.txt`.
### Parameters
`parameters.yaml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file intended to hold settings that you only need to specify once. Right now, it only contains parameters related to `images hosting` (needed to copy your images to a remote server). All the options are either self-explanatory or explained through comments. It should be fairly easy to tweak the [included example](parameters.yaml) for your own setup.
### Questions
Questions are specified through another *YAML* file. The first parameter, `pictures base directory`, refers to the base directory that will be created in the remote host to accommodate your images (only meaningful if images are **not** embedded in the questions, i.e., if not passing `-e`). It is meant to separate different question banks (so that you can have, e.g., directories `quiz 1` and `quiz 2`). The rest of the file is a **list of categories**, and inside each one there is a **list of questions**. Hopefully, the format is clear from either the name of the settings and/or its companion comments. You are probably better off taking a look at the [provided example](bank.yaml).
### Example
If you run the program inside the `gift-wrapper` directory as is, it will process the sample `bank.yaml` which includes a `.tex`, a `.svg` and some mathematical formulas, and will generate a `bank.gift.txt` file which you can import from Moodle (choosing the GIFT format when asked). If the parameters file (by default, `parameters.yaml`) is not found, images are embedded into the corresponding questions (tantamount to passing `-e`).
## Including images
`gift-wrapper` has been designed to work with [svg](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) images. Then, in order to include any image in a question, two scenarios are contemplated:
* you already have an svg
* you have a TeX file **that can be compiled with *pdflatex***
In any case, you just need to write the path to the file inside the text of the question (whether in the `statement`, the `answer` or the `feedbak`). If in the second scenario, i.e., you are including a *TeX* file, this will be compiled into a pdf with *pdflatex*, and then converted to an svg with *pdf2svg*. Hence, a *svg* file will be, in the end, available for every image.
Images (*svg*s) are either copied to a remote host (and properly linked in the output GIFT file), or directly embedded into their corresponding questions.
Characters allowed in a path (to either a `.tex` or a `.svg`) are:
* alphanumeric (A-Z, a-z, 0-9)
* underscore, '_', and dash, '-'
* '/' and '\\' (path separators).
### Browser compatibility
It seems (it has been reported) not every browser properly handles svg images (maybe other types too) embedded in a question as an URL. My experience so far is both [Firefox](https://www.mozilla.org/en-US/firefox) and [Chromium](https://www.chromium.org/Home) (at the time of writing this) work just fine.
### Do I really need pdf2svg?
Only if you want automatic conversion from `.tex` (passing through `.pdf`) to `.svg`, i.e., only if you embed a `.tex` somewhere.
Also, there is (probably) nothing special about *pdf2svg* and, in principle, you can use any command-line program that takes as arguments the input pdf and the output svg. However, I've only tested the program with *pdf2svg* since it's the one included in [Gentoo Linux](https://www.gentoo.org/).
## Remote access
If a parameters file (e.g., `parameters.yaml`) is found, images are by default copied to the specified remote host (within a publicly visible directory) so that they can be accessed by Moodle. This is done automatically for every embedded image (svg or tex). For this to work, in the `parameters.yaml` file, within `ssh` either
* user and password, or
* user and path to a public key file
(but **not both**) should be specified.
You can inhibit this behavior and run the program locally (omitting the transferring of the images to a remote host) by using `-l` command line argument. This is especially meaningful if you don't have any embedded image in your questions (and hence nothing needs to be copied to a remote host).
## Latex support
Formulas inside `$`s are processed and, within them, these are the commands/symbols that have been tested so far
- greek letters
- subindexes
- calligraphic symbols, i.e., prefixed by `\cal`
- fractions with `\frac{}{}`
- `\underline`
- `\left(` and `\right)`
- `\left[` and `\right]`
- `\begin{bmatrix}` and `\end{bmatrix}`
- symbols `\sim`, `\approx`
More things are probably OK, but I have not tested them yet.
Inside text, only commands `\textit` and `\textbf` are supported for the time being.
### Safety checks
By default, `wrap.py` checks whether or not the formulas you wrote between `$`'s can actually be compiled. Right now this involves a call to `pdflatex` *for every formula*, meaning that it can significantly slow down the process. It can be disabled by passing ` --no-checks` (or simply `-n`). It is probably a good idea to actually check the formulas every once in a while (e.g., every time you add a new one), though, since *bad* latex formulas will be (silently) imported by Moodle anyway, and not only will they be incorrectly rendered but they may also mess up subsequent content.
## Current limitations
- only *numerical* and *multiple-choice* questions are supported (notice that the GIFT format itself doesn't support every type of question available in Moodle)
- the latex support is very basic
- one is in for troubles if embedding remote URLs pointing to `.svg` or `.tex` files since the file part will, most likely, be parsed and replaced
## See also
If you are comfortable with Python and [Jupyter](https://jupyter.org/) notebooks, you might also be interested in [py2gift](https://github.com/manuvazquez/py2gift).
Raw data
{
"_id": null,
"home_page": "https://github.com/manuvazquez/gift-wrapper",
"name": "gift-wrapper",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "",
"author": "Manuel A. V\u00e1zquez",
"author_email": "manuavazquez@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/32/a6/21140fefef6a7bed041ff260f1cc37ee9ebb587af4c9176286d125431246/gift-wrapper-1.8.0.tar.gz",
"platform": null,
"description": "# gift-wrapper\n\nThis is Python software to easily build [GIFT](https://docs.moodle.org/en/GIFT_format) -based [question banks](https://docs.moodle.org/en/Question_bank) in [Moodle](https://moodle.org/). Other similar tools are available (you can search for *Tools that create or process GIFTs* in [Moodle's GIFT page](https://docs.moodle.org/en/GIFT_format)) but none of them fitted well my workflow. What I need is (the goals of `gift-wrapper` are):\n\n* to write questions in plain text, and as many as I like in a single file\n* to write latex formulas directly\n* to easily/seamlessly include images\n\nThe most interesting point is probably the last one.\n\n## Requirements\n\nPython requirements are:\n\n- Python ≥ 3.10\n- [paramiko](http://www.paramiko.org/)\n- [colorama](https://pypi.org/project/colorama/)\n- [pyyaml](https://pypi.org/project/PyYAML/)\n- [tqdm](https://github.com/tqdm/tqdm)\n\nNow, if you want to make the most of the software you also need:\n\n* [pdflatex](https://en.wikipedia.org/wiki/PdfTeX) (i.e. a [TeX](https://en.wikipedia.org/wiki/TeX) distribution)\n* [pdf2svg](https://github.com/dawbarton/pdf2svg/)\n* disk space in a remote server that can host your images\n\n## Install\n\n```\npip install gift-wrapper\n```\n\nshould suffice.\n\n### Manual setup\n\nIf you rather clone this repository, (in order to, potentially, get the latest additions/modifications) \n\n```\npip install pyyaml paramiko tqdm colorama\n```\n\nshould install all the additional requirements. If you use [Anaconda](https://anaconda.org/), the [bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) script `make_conda_environment.sh` will make a proper environment (named `gift`).\n\nAfter that, you should be able to run the program.\n\n## Usage\n\nThe main program is `wrap.py` and you can check the available command-line options with\n```\nwrap.py -h\n```\nor\n```\npython wrap.py -h\n```\nif you did a manual installation and `wrap.py` doesn't have execution permissions. \n\nIf you don't pass any argument, `parameters.yaml` and `bank.yaml` files are expected. The former is a settings file whereas the latter is the actual *input file* in which you must write the questions.\n\nThe output will be a text file in GIFT format with the same name as the input (the file with the questions) but `.gift.txt` extension (thus, `bank.gift.txt`, by default). It seems that *sometimes* Moodle has troubles importing (recognizing) a text file if the extension is not `.txt`. \n\n### Parameters\n\n`parameters.yaml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file intended to hold settings that you only need to specify once. Right now, it only contains parameters related to `images hosting` (needed to copy your images to a remote server). All the options are either self-explanatory or explained through comments. It should be fairly easy to tweak the [included example](parameters.yaml) for your own setup.\n\n### Questions\n\nQuestions are specified through another *YAML* file. The first parameter, `pictures base directory`, refers to the base directory that will be created in the remote host to accommodate your images (only meaningful if images are **not** embedded in the questions, i.e., if not passing `-e`). It is meant to separate different question banks (so that you can have, e.g., directories `quiz 1` and `quiz 2`). The rest of the file is a **list of categories**, and inside each one there is a **list of questions**. Hopefully, the format is clear from either the name of the settings and/or its companion comments. You are probably better off taking a look at the [provided example](bank.yaml).\n\n### Example\n\nIf you run the program inside the `gift-wrapper` directory as is, it will process the sample `bank.yaml` which includes a `.tex`, a `.svg` and some mathematical formulas, and will generate a `bank.gift.txt` file which you can import from Moodle (choosing the GIFT format when asked). If the parameters file (by default, `parameters.yaml`) is not found, images are embedded into the corresponding questions (tantamount to passing `-e`).\n\n## Including images\n\n`gift-wrapper` has been designed to work with [svg](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) images. Then, in order to include any image in a question, two scenarios are contemplated:\n\n* you already have an svg\n* you have a TeX file **that can be compiled with *pdflatex***\n\nIn any case, you just need to write the path to the file inside the text of the question (whether in the `statement`, the `answer` or the `feedbak`). If in the second scenario, i.e., you are including a *TeX* file, this will be compiled into a pdf with *pdflatex*, and then converted to an svg with *pdf2svg*. Hence, a *svg* file will be, in the end, available for every image.\n\nImages (*svg*s) are either copied to a remote host (and properly linked in the output GIFT file), or directly embedded into their corresponding questions.\n\nCharacters allowed in a path (to either a `.tex` or a `.svg`) are:\n* alphanumeric (A-Z, a-z, 0-9)\n* underscore, '_', and dash, '-'\n* '/' and '\\\\' (path separators).\n\n### Browser compatibility\n\nIt seems (it has been reported) not every browser properly handles svg images (maybe other types too) embedded in a question as an URL. My experience so far is both [Firefox](https://www.mozilla.org/en-US/firefox) and [Chromium](https://www.chromium.org/Home) (at the time of writing this) work just fine. \n\n### Do I really need pdf2svg?\n\nOnly if you want automatic conversion from `.tex` (passing through `.pdf`) to `.svg`, i.e., only if you embed a `.tex` somewhere.\nAlso, there is (probably) nothing special about *pdf2svg* and, in principle, you can use any command-line program that takes as arguments the input pdf and the output svg. However, I've only tested the program with *pdf2svg* since it's the one included in [Gentoo Linux](https://www.gentoo.org/).\n\n## Remote access\n\nIf a parameters file (e.g., `parameters.yaml`) is found, images are by default copied to the specified remote host (within a publicly visible directory) so that they can be accessed by Moodle. This is done automatically for every embedded image (svg or tex). For this to work, in the `parameters.yaml` file, within `ssh` either\n\n* user and password, or\n* user and path to a public key file\n\n(but **not both**) should be specified.\n\nYou can inhibit this behavior and run the program locally (omitting the transferring of the images to a remote host) by using `-l` command line argument. This is especially meaningful if you don't have any embedded image in your questions (and hence nothing needs to be copied to a remote host).\n\n## Latex support\n\nFormulas inside `$`s are processed and, within them, these are the commands/symbols that have been tested so far\n\n- greek letters\n- subindexes\n- calligraphic symbols, i.e., prefixed by `\\cal`\n- fractions with `\\frac{}{}`\n- `\\underline`\n- `\\left(` and `\\right)`\n- `\\left[` and `\\right]`\n- `\\begin{bmatrix}` and `\\end{bmatrix}`\n- symbols `\\sim`, `\\approx`\n\nMore things are probably OK, but I have not tested them yet.\n\nInside text, only commands `\\textit` and `\\textbf` are supported for the time being.\n\n### Safety checks\n\nBy default, `wrap.py` checks whether or not the formulas you wrote between `$`'s can actually be compiled. Right now this involves a call to `pdflatex` *for every formula*, meaning that it can significantly slow down the process. It can be disabled by passing ` --no-checks` (or simply `-n`). It is probably a good idea to actually check the formulas every once in a while (e.g., every time you add a new one), though, since *bad* latex formulas will be (silently) imported by Moodle anyway, and not only will they be incorrectly rendered but they may also mess up subsequent content. \n\n## Current limitations\n\n- only *numerical* and *multiple-choice* questions are supported (notice that the GIFT format itself doesn't support every type of question available in Moodle)\n\n- the latex support is very basic\n\n- one is in for troubles if embedding remote URLs pointing to `.svg` or `.tex` files since the file part will, most likely, be parsed and replaced\n\n## See also\n\nIf you are comfortable with Python and [Jupyter](https://jupyter.org/) notebooks, you might also be interested in [py2gift](https://github.com/manuvazquez/py2gift).\n",
"bugtrack_url": null,
"license": "",
"summary": "Build GIFT (Moodle compatible) files easily",
"version": "1.8.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1f36c09fd9183b5533117f4153f8f8e490462b94a48a520cfdfb2f472a5f5da",
"md5": "df755dd8caeaaa6b3a5a10a28cdf9607",
"sha256": "ffa75281d8e637fa0b37114cb39314db865cda456a0c51d2e6635fead2b9dfcb"
},
"downloads": -1,
"filename": "gift_wrapper-1.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df755dd8caeaaa6b3a5a10a28cdf9607",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23189,
"upload_time": "2023-04-07T08:16:02",
"upload_time_iso_8601": "2023-04-07T08:16:02.813589Z",
"url": "https://files.pythonhosted.org/packages/b1/f3/6c09fd9183b5533117f4153f8f8e490462b94a48a520cfdfb2f472a5f5da/gift_wrapper-1.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "32a621140fefef6a7bed041ff260f1cc37ee9ebb587af4c9176286d125431246",
"md5": "e888fd8102fd9103cfafc0206b6da912",
"sha256": "398e2b9b6bf61abe81822456cb5d5cb1c0aa244ca613cdf526fe7046d69a670a"
},
"downloads": -1,
"filename": "gift-wrapper-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "e888fd8102fd9103cfafc0206b6da912",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 23279,
"upload_time": "2023-04-07T08:16:04",
"upload_time_iso_8601": "2023-04-07T08:16:04.196251Z",
"url": "https://files.pythonhosted.org/packages/32/a6/21140fefef6a7bed041ff260f1cc37ee9ebb587af4c9176286d125431246/gift-wrapper-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-07 08:16:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "manuvazquez",
"github_project": "gift-wrapper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gift-wrapper"
}
JSON
