This software qtools3 provides tools and utilities for dealing with PMA
questionnaires. It converts the XLSForms to XML and then does all appropriate
edits. It also can be used as a simple XLSForm Offline converter.
The software qtools3 is an upgrade from
qtools2. The primary purpose for this
upgrade is to port the software from Python 2 to Python 3. This was made
possible because the community's PyXForm
added Python 3 support in 2018.
The software qtools3 relies on Python 3 for core functionality and Java for
ODKValidate. The steps to install are
- Install the most recent version of the Java JRE.
- Install Python 3.6 or higher.
Note: the author uses Homebrew for Python installation on Mac.
Some difficulties arise if python and pip are not be added automatically
to the PATH upon installation. For instructions on how to do this, consult
this document.
Open CMD (click start menu, type CMD, press enter).
cd C:\Python36\Scripts
Continue with installation or upgrade...
NOTE: Windows users start with the Windows-specifc steps section.
On a terminal or CMD, run
python3 -m pip install qtools3
For the latest and greatest, install directly from github
python3 -m pip install https://github.com/PMA-2020/qtools3/zipball/master
Besides being the workhorse of qtools3, the module qtools3.convert also provides a command-line utility. New-style linking (with all instructions contained inside the XLSForm) is now the default. Old-style linking (line-by-line manual XML editing instructions) is removed. To see help files and usage, run in the terminal
python -m qtools3.convert --help
| Type of conversion | Command |
|---|---|
| PMA form conversion | python -m qtools3.convert FILENAME [FILENAME ...] |
| XLSForm-Offline equivalent, convert and validate | python -m qtools3.convert -ril FILENAME [FILENAME ...] |
| Short Flag | Long Flag | Description |
|---|---|---|
| -r | --regular | This flag indicates the program should convert to XForm and not try to enforce PMA-specific naming conventions or make linking checks for HQ and FQ. |
| -p | --preexisting | Include this flag to prevent overwriting pre-existing files. |
| -n | --novalidate | Do not validate XML output with ODK Validate. Do not perform extra checks on (1) data in undefined columns, (2) out of order variable references. |
| -i | --ignore_version | Ignore versioning in filename, form_id, form_title, and save_form. In other words, the default (without this flag) is to ensure version consistency. |
| -l | --linking_warn | Produce warnings for incorrect linking directives. Default is to raise an exception and halt the program. |
| -d | --debug | Show debug information. Helpful for squashing bugs. |
| -e | --extras | Perform extra checks on (1) data in undefined columns and (2) out of order variable references. |
| -s | --suffix | A suffix to add to the base file name. Cannot start with a hyphen ("-"). |
These qtools3 conversion warning messages appear whenever there is a discrepancy between translations with respect to numbering, i.e. '[0-9]+', and/or variables, i.e. '${...}'.
Example - Numbering Mismatch
In this example, the warning '[0-9]+' will appear, because "0" is not the same things as "zero". To fix this, please ensure that ALL languages use only arabic numerals (e.g. 1, 2, 3...), or only word-based numbering (e.g. one, two, three...).
- English: Please enter 0.
- Bad Pidgin English: Please enter zero.
Example - Variable Mismatch
ODK variables should never be translated. If the main language shows "${months}", all language translations should also show "${months}". Of course, what the user sees on the phone will still be translated.
- English: Enter ${months}.
- Bad French: Entrez ${mois}.
Example - Variable Mismatch
Translations should use all variables that the English uses.
- English: There are ${hh_count} people in the household
- Bad Pidgin English: There are (ODK will fill in a count) people in the household
NOTE: Windows users start with the Windows-specifc steps section. To install qtools3 updates, use
python3 -m pip install qtools3 --upgrade
For the latest and greatest, replace master in the URLs above with develop.
Every once in a while, it will be necessary to update pmaxform3. To do this, use
python3 -m pip install pmaxform3 --upgrade
- Check the version in the terminal to see if a program is installed.
- Check Java version with
javac -version - Check Python version with
python -V. - Check pip version with
pip -V. - Another executable for Python is
python3. - Another executable for
pipispip3. - The most recent Java is not required, but successful tests have only been run with Java 1.6 through Java 1.8.
- A dependency of
pmaxformislxml, which can cause problems on Mac. If there are problems, the best guide is on StackOverflow. - During installation of
pmaxformon Mac, the user may be prompted to install Xcode's Command Line Tools. This should be enough forlxml. qtools3may run without Java. Java is only needed for ODK Validate, which can be bypassed by using the "No validate" option.- Xcode 9 presents issues with missing header files. If at all possible, install Xcode 8.
Qtools2 fournit des outils et des utilitaires permettant de traiter les questionnaires PMA2020. Il convertit les XLSForms en XML, puis effectue toutes les modifications appropriées. Il peut également être utilisé comme un convertisseur XLSForm Offline simple.
Le code est nécessairement écrit pour Python 2 car il dépend d'un embranchement du [PyXForm de la communauté] 1a (l’embranchement s'appelle [pmaxform] 1b) pour convertir les documents MS-Excel en XML. Nous devons juste apprendre à vivre avec cette contrariété.
QTools2 repose sur Python 2 pour les fonctionnalités principales et Java pour ODKValidate. Les étapes pour installer sont
- Installez la version la plus récente de [Java] 2 (actuellement 1.8). ~~ Le JRE ou le JDK devrait fonctionner. ~ Seul le JDK fonctionnait lors du dernier test sur Mac (mars 2017).
- Installez [Python 2.7] 3.
Remarque: l'auteur utilise [Homebrew] 4 pour l'installation de Python sur Mac.
Some difficulties arise if python and pip are not be added automatically to the PATH upon installation. Open CMD (click start menu, type CMD, press enter). Naviagate to your pip executable, probably here:
cd C:\Python27\Scripts
Continue with installation or upgrade...
NOTE: Windows users start with the Windows-specifc steps section. This package uses a modified version of pyxform called pmaxform because the PyXForm project thus far has refused to accept this author's pull requests for some simple improvements. Therefore, installation requires two commands instead of one. Open CMD or Terminal and install relevant packages separately, and in order
First,
pip install https://github.com/jkpr/pmaxform/zipball/master
Second,
pip install https://github.com/jkpr/QTools2/zipball/master
For the latest and greatest, replace master in the URLs above with develop.
Certaines difficultés surviennent si python et pip ne sont pas ajoutés automatiquement au PATH lors de l'installation. Ouvrez CMD (cliquez sur le menu de démarrage, tapez CMD, appuyez sur Entrée).
Accédez à votre exécutable pip, probablement ici:
cd C: \ Python27 \ Scripts
Continuer l'installation ou la mise à niveau ...
REMARQUE: les utilisateurs de Windows commencent par la section Etapes Spécifiques Windows. Ce package utilise une version modifiée de pyxform appelée pmaxform car le projet PyXForm a jusqu'à présent refusé d'accepter les demandes d'extraction de cet auteur pour certaines améliorations simples. Par conséquent, l'installation nécessite deux commandes au lieu d’ une. Ouvrez CMD ou Terminal et installez les packages pertinents séparément et dans l'ordre
Premièrement
pip installer https://github.com/jkpr/pmaxform/zipball/master
Deuxièmement
pip installer https://github.com/jkpr/QTools2/zipball/master
Pour les plus récents et les meilleurs, remplacez «master» dans les URL ci-dessus par «developer».
Après l'installation, le code capable de convertir des XLSForms est enregistré dans la bibliothèque de codes de Python. Cela signifie que n'importe où on peut accéder à Python, ains qu’a qtools2.
Pour utiliser qtools2, il y a deux manières principales. La méthode la plus simple consiste à pointer et à cliquer sur un fichier spécifique ([exemple de fichier spécifique] 5) enregistré dans n’importe quel dossier, tel que Downloads, pour que Python puisse l’exécuter. L'autre façon consiste à utiliser la ligne de commande.
Le moyen le plus simple d'utiliser qtools2 est d'utiliser un fichier du dossier scripts [de ce référentiel] 6. Pour télécharger un script, cliquez sur son lien, puis sur "Raw", puis enregistrez le contenu (dans le navigateur, File> Save). Le tableau ci-dessous explique ce qui est disponible.
| Nom du script | But |
|---|---|
xlsform-convert.py |
Convertir un ou plusieurs types de XLSForm avec une interface graphique. |
Windows associe généralement les fichiers .py à l'exécutable Python. Ainsi, un utilisateur Windows ne devrait avoir besoin que de double-clic sur l'icône du fichier de script. Cela démarre l’interprétre Python et lance le code.
Sur un Mac, faire un double-clic sur un fichier .py ouvre généralement un correcteur de texte. Pour exécuter le fichier en tant que code, faire un clic droit sur l'icône du fichier de script, puis sélectionnez "Ouvrir avec> Python Launcher (2.7.12)". Le numéro de version Python peut être différent.
Si ce qui précède est trop difficile, il est possible d’obtenir la même fonctionnalité d’une manière différente. Ouvrez une session interactive Python (peut-être ouvrir IDLE, peut-être ouvrir Terminal et taper python). Ensuite, copiez et collez le même texte qui se trouve dans le script souhaité dans l'interprète, appuyez sur "Enter", et le tour est joué.
En plus d'être le bourreau du travail de qtools2, le module qtools2.convert fournit également un utilitaire de ligne de commande. La liaison de style nouveau (avec toutes les instructions contenues dans le XLSForm) est maintenant la valeur par défaut. La liaison de type ancien (instructions d’édition XML manuelle, ligne par ligne) est supprimée. Pour voir les fichiers d’aide et leur utilisation, exécutez-le dans le terminal.
python -m qtools2.convert --help
| Type de conversion | Commande |
|---|---|
| Conversion de formulaire PMA | python -m qtools2.convert FILENAME [FILENAME ...] |
| convertir et valider des équivalents de XLSForm-Offline, | python -m qtools2.convert -ril FILENAME [FILENAME ...] |
| Drapeau court | Drapeau long | Description |
|---|---|---|
| -r | --regular | Cet indicateur indique que le programme doit convertir en XForm et ne pas essayer d’apporter des modifications spécifiques à PMA2020. |
| -p | --preexisting | Incluez cet indicateur (drapeau) pour empêcher le remplacement de fichiers préexistants. |
| -n | --novalidate | Ne validez pas la sortie XML avec ODK Validate. N'effectuez pas de contrôles supplémentaires sur (1) les données de colonnes indéfinies, (2) les références de variables en désordre. |
| -i | --ignore_version | Ignorez le versioning dans filename, form_id, form_title et save_form. En d'autres termes, ceci permet par défaut d'assurer la cohérence de la version. |
| -l | --linking_warn | Produire des avertissements pour les directives de liaison incorrectes. Par défaut, une exception est déclenchée et le programme est arrêté. |
| -d | --debug | Afficher les informations de déboggage. Utiliser pour écraser les bugs. |
| -e | --extras | Effectuez des vérifications supplémentaires sur (1) les données dans des colonnes non définies et (2) les références de variables en désordre. |
| -s | --suffix | Un suffixe à ajouter au nom du fichier de base. Impossible de commencer par un trait d'union ("-"). |
Pour ceux qui souhaitent utiliser une interface graphique lancée à partir de la ligne de commande., Le pipeline QTools2 commence ainsi
python -m qtools2
et vérifiez l’utilisation en ajoutant l’indicateur --help à la commande ci-dessus.
NOTE: l'option -v2 a été supprimée à partir de la version 0.2.3.
REMARQUE: les utilisateurs de Windows commencent par la section _ ** Etapes spécifiques Windows ** _. Pour installer les mises à jour qtools2, utilisez
pip installer https://github.com/jkpr/QTools2/zipball/master --upgrade
Pour les plus récentes et les meilleures, remplacez «master dans les URL ci-dessus par «developer».
- Vérifiez la version dans le terminal pour voir si un programme est installé.
- Vérifier la version de Java avec
javac -version - Vérifiez la version de Python avec
python -V. - Vérifiez la version de pip avec
pip -V. - Un autre exécutable pour Python est
python2. - Un autre exécutable pour
pipestpip2. - La version la plus récente de Java n'est pas requise, mais les tests réussis ont uniquement été exécutés avec Java 1.6 à Java 1.8.
- Une dépendance de
pmaxformestlxml, ce qui peut poser problème sur Mac. S'il y a des problèmes, le meilleur guide est sur [StackOverflow] 8. - Lors de l'installation de
pmaxformsur Mac, l'utilisateur peut être invité à installer les outils de ligne de commande de Xcode. Cela devrait suffire pourlxml. - Qtools2 peut fonctionner sans Java. Java n’est nécessaire que pour ODK Validate, qui peut être contourné en utilisant l’option "No validate".
Soumettez les rapports de bugs à James Pringle à l'adresse jpringleBEAR @ jhu.edu.