Package: gift-wrapper
gift-wrapperThis is Python software to easily buildGIFT-basedquestion banksinMoodle. Other similar tools are available (you can search forTools that create or process GIFTsinMoodle's GIFT page) but none of them fitted well my workflow. What I need is (the goals ofgift-wrapperare):to write questions in plain text, and as many as I like in a single fileto write latex formulas directlyto easily/seamlessly include imagesThe most interesting point is probably the last one.RequirementsPython requirements are:Python ≥ 3.10paramikocoloramapyyamltqdmNow, if you want to make the most of the software you also need:pdflatex(i.e. aTeXdistribution)pdf2svgdisk space in a remote server that can host your imagesInstallpip install gift-wrappershould suffice.Manual setupIf you rather clone this repository, (in order to, potentially, get the latest additions/modifications)pip install pyyaml paramiko tqdm coloramashould install all the additional requirements. If you useAnaconda, thebashscriptmake_conda_environment.shwill make a proper environment (namedgift).After that, you should be able to run the program.UsageThe main program iswrap.pyand you can check the available command-line options withwrap.py -horpython wrap.py -hif you did a manual installation andwrap.pydoesn't have execution permissions.If you don't pass any argument,parameters.yamlandbank.yamlfiles are expected. The former is a settings file whereas the latter is the actualinput filein 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.txtextension (thus,bank.gift.txt, by default). It seems thatsometimesMoodle has troubles importing (recognizing) a text file if the extension is not.txt.Parametersparameters.yamlis aYAMLfile intended to hold settings that you only need to specify once. Right now, it only contains parameters related toimages 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 theincluded examplefor your own setup.QuestionsQuestions are specified through anotherYAMLfile. 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 arenotembedded in the questions, i.e., if not passing-e). It is meant to separate different question banks (so that you can have, e.g., directoriesquiz 1andquiz 2). The rest of the file is alist of categories, and inside each one there is alist 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 theprovided example.ExampleIf you run the program inside thegift-wrapperdirectory as is, it will process the samplebank.yamlwhich includes a.tex, a.svgand some mathematical formulas, and will generate abank.gift.txtfile 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 imagesgift-wrapperhas been designed to work withsvgimages. Then, in order to include any image in a question, two scenarios are contemplated:you already have an svgyou have a TeX filethat can be compiled withpdflatexIn any case, you just need to write the path to the file inside the text of the question (whether in thestatement, theansweror thefeedbak). If in the second scenario, i.e., you are including aTeXfile, this will be compiled into a pdf withpdflatex, and then converted to an svg withpdf2svg. Hence, asvgfile will be, in the end, available for every image.Images (svgs) 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.texor a.svg) are:alphanumeric (A-Z, a-z, 0-9)underscore, '_', and dash, '-''/' and '\' (path separators).Browser compatibilityIt 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 bothFirefoxandChromium(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.texsomewhere.
Also, there is (probably) nothing special aboutpdf2svgand, 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 withpdf2svgsince it's the one included inGentoo Linux.Remote accessIf 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 theparameters.yamlfile, withinssheitheruser and password, oruser and path to a public key file(butnot 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-lcommand 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 supportFormulas inside$s are processed and, within them, these are the commands/symbols that have been tested so fargreek letterssubindexescalligraphic symbols, i.e., prefixed by\calfractions with\frac{}{}\underline\left(and\right)\left[and\right]\begin{bmatrix}and\end{bmatrix}symbols\sim,\approxMore things are probably OK, but I have not tested them yet.Inside text, only commands\textitand\textbfare supported for the time being.Safety checksBy default,wrap.pychecks whether or not the formulas you wrote between$'s can actually be compiled. Right now this involves a call topdflatexfor 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, sincebadlatex 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 limitationsonlynumericalandmultiple-choicequestions are supported (notice that the GIFT format itself doesn't support every type of question available in Moodle)the latex support is very basicone is in for troubles if embedding remote URLs pointing to.svgor.texfiles since the file part will, most likely, be parsed and replacedSee alsoIf you are comfortable with Python andJupyternotebooks, you might also be interested inpy2gift.