qtools3 0.3.5

Convert ODK files from XlsForm to Xform.

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}", 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

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.