qtools3 0.3.6

Description:

qtools3 0.3.6

qtools3 - Questionnaire Tools for ODK
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.
Pre-requisites
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.
Windows-specific steps
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...
Installation
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

Command-line usage
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

Quick-start guide



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 ...]



Options



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 ("-").



Extras
Translation Regex Mismatches
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",alllanguagetranslationsshouldalsoshow"{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

Updates
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

Suggestions and Gotchas

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 pip is pip3.
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 pmaxform is lxml, which can cause problems on Mac. If there are problems, the best guide is on StackOverflow.
During installation of pmaxform on Mac, the user may be prompted to install Xcode's Command Line Tools. This should be enough for lxml.
qtools3 may 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: Outils de questionnaire pour ODK
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é.
Conditions préalables
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.
Windows-specific steps
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...
Installation
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.
étapes spécifiques à Windows
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 ...
Installation
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».
Usage
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.
Meilleure manière d'utiliser qtools2 pour les formulaires PMA2020
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.
Alternative
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é.
Utilisation de la ligne de commande
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

Guide de démarrage rapide



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 ...]



Options



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 ("-").



Interface utilisateur graphique
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.
Mises à jour
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».
Suggestions et pièges

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 pip est pip2.
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 pmaxform est lxml, 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 pmaxform sur Mac, l'utilisateur peut être invité à installer les outils de ligne de commande de Xcode. Cela devrait suffire pour lxml.
Qtools2 peut fonctionner sans Java. Java n’est nécessaire que pour ODK Validate, qui peut être contourné en utilisant l’option "No validate".

Bugs
Soumettez les rapports de bugs à James Pringle à l'adresse jpringleBEAR @ jhu.edu.