Package: qtools3
qtools3- Questionnaire Tools for ODKThis softwareqtools3provides 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 softwareqtools3is an upgrade fromqtools2. The primary purpose for this
upgrade is to port the software from Python 2 to Python 3. This was made
possible because thecommunity's PyXFormadded Python 3 support in 2018.Pre-requisitesThe softwareqtools3relies on Python 3 for core functionality and Java for
ODKValidate. The steps to install areInstall the most recent version of theJava JRE.InstallPython 3.6or higher.Note: the author usesHomebrewfor Python installation on Mac.Windows-specific stepsSome difficulties arise ifpythonandpipare not be added automatically
to thePATHupon installation. For instructions on how to do this, consultthis document.OpenCMD(click start menu, typeCMD, press enter).cd C:\Python36\ScriptsContinue with installation or upgrade...InstallationNOTE: Windows users start with theWindows-specifc stepssection.On a terminal or CMD, runpython3 -m pip install qtools3For the latest and greatest, install directly from githubpython3 -m pip install https://github.com/PMA-2020/qtools3/zipball/masterCommand-line usageBesides being the workhorse ofqtools3, the moduleqtools3.convertalso 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 terminalpython -m qtools3.convert --helpQuick-start guideType of conversionCommandPMA form conversionpython -m qtools3.convert FILENAME [FILENAME ...]XLSForm-Offline equivalent, convert and validatepython -m qtools3.convert -ril FILENAME [FILENAME ...]OptionsShort FlagLong FlagDescription-r--regularThis 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--preexistingInclude this flag to prevent overwriting pre-existing files.-n--novalidateDo 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_versionIgnore 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_warnProduce warnings for incorrect linking directives. Default is to raise an exception and halt the program.-d--debugShow debug information. Helpful for squashing bugs.-e--extrasPerform extra checks on (1) data in undefined columns and (2) out of order variable references.-s--suffixA suffix to add to the base file name. Cannot start with a hyphen ("-").ExtrasTranslation Regex MismatchesTheseqtools3conversion 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 MismatchIn 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 MismatchODK 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 MismatchTranslations should use all variables that the English uses.English: There are ${hh_count} people in the householdBad Pidgin English: There are (ODK will fill in a count) people in the householdUpdatesNOTE: Windows users start with theWindows-specifc stepssection. To installqtools3updates, usepython3 -m pip install qtools3 --upgradeFor the latest and greatest, replacemasterin the URLs above withdevelop.Every once in a while, it will be necessary to updatepmaxform3. To do this, usepython3 -m pip install pmaxform3 --upgradeSuggestions and GotchasCheck the version in the terminal to see if a program is installed.Check Java version withjavac -versionCheck Python version withpython -V.Check pip version withpip -V.Another executable for Python ispython3.Another executable forpipispip3.The most recent Java is not required, but successful tests have only been run with Java 1.6 through Java 1.8.A dependency ofpmaxformislxml, which can cause problems on Mac. If there are problems, the best guide is onStackOverflow.During installation ofpmaxformon 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: Outils de questionnaire pour ODKQtools2 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éalablesQTools2 repose sur Python 2 pour les fonctionnalités principales et Java pour ODKValidate. Les étapes pour installer sontInstallez 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]4pour l'installation de Python sur Mac.Windows-specific stepsSome difficulties arise ifpythonandpipare not be added automatically to thePATHupon installation. OpenCMD(click start menu, typeCMD, press enter). Naviagate to yourpipexecutable, probably here:cd C:\Python27\ScriptsContinue with installation or upgrade...InstallationNOTE: Windows users start with theWindows-specifc stepssection. This package uses a modified version ofpyxformcalledpmaxformbecause the PyXForm project thus far has refused to accept this author's pull requests for some simple improvements. Therefore, installation requirestwocommands instead ofone. Open CMD or Terminal and install relevant packagesseparately, andin orderFirst,pip install https://github.com/jkpr/pmaxform/zipball/masterSecond,pip install https://github.com/jkpr/QTools2/zipball/masterFor the latest and greatest, replacemasterin the URLs above withdevelop.étapes spécifiques à WindowsCertaines difficultés surviennent sipythonetpipne sont pas ajoutés automatiquement auPATHlors de l'installation. OuvrezCMD(cliquez sur le menu de démarrage, tapezCMD, appuyez sur Entrée).Accédez  à votre exécutablepip, probablement ici:cd C: \ Python27 \ ScriptsContinuer l'installation ou la mise à niveau ...InstallationREMARQUE: les utilisateurs de Windows commencent par la sectionEtapes Spécifiques Windows. Ce package utilise une version modifiée depyxformappeléepmaxformcar 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écessitedeuxcommandes au lieu d’une. Ouvrez CMD ou Terminal et installez les packages pertinentsséparémentetdans l'ordrePremièrementpip installer https://github.com/jkpr/pmaxform/zipball/masterDeuxièmementpip installer https://github.com/jkpr/QTools2/zipball/masterPour les plus récents et les meilleurs, remplacez «master» dans les URL ci-dessus par «developer».UsageAprè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’aqtools2.Pour utiliserqtools2, 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'utiliserqtools2pour les formulaires PMA2020Le moyen le plus simple d'utiliserqtools2est d'utiliser un fichier du dossierscripts[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 scriptButxlsform-convert.pyConvertir un ou plusieurstypesde 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.pyouvre 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.AlternativeSi 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 taperpython). 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 commandeEn plus d'être le bourreau du travail deqtools2, le moduleqtools2.convertfournit é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 --helpGuide de démarrage rapideType de conversionCommandeConversion de formulaire PMApython -m qtools2.convert FILENAME [FILENAME ...]convertir et valider des équivalents de XLSForm-Offline,python -m qtools2.convert -ril FILENAME [FILENAME ...]OptionsDrapeau courtDrapeau longDescription-r--regularCet indicateur indique que le programme doit convertir en XForm et ne pas essayer d’apporter des modifications spécifiques à PMA2020.-p--preexistingIncluez cet indicateur (drapeau) pour empêcher le remplacement de fichiers préexistants.-n--novalidateNe 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_versionIgnorez 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_warnProduire des avertissements pour les directives de liaison incorrectes. Par défaut, une exception est déclenchée et le programme est arrêté.-d--debugAfficher les informations de déboggage. Utiliser pour écraser les bugs.-e--extrasEffectuez 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--suffixUn suffixe à ajouter au nom du fichier de base. Impossible de commencer par un trait d'union ("-").Interface utilisateur graphiquePour ceux qui souhaitent utiliser une interface graphique lancée à partir de la ligne de commande., Le pipeline QTools2 commence ainsipython -m qtools2et vérifiez l’utilisation en ajoutant l’indicateur--helpà la commande ci-dessus.NOTE: l'option-v2a été supprimée à partir de la version 0.2.3.Mises à jourREMARQUE: les utilisateurs de Windows commencent par la section _ ** Etapes spécifiques Windows ** _. Pour installer les mises à jourqtools2, utilisezpip installer https://github.com/jkpr/QTools2/zipball/master --upgradePour les plus récentes et les meilleures, remplacez «master dans les URL ci-dessus par «developer».Suggestions et piègesVérifiez la version dans le terminal pour voir si un programme est installé.Vérifier la version de Java avecjavac -versionVérifiez la version de Python avecpython -V.Vérifiez la version de pip avecpip -V.Un autre exécutable pour Python estpython2.Un autre exécutable pourpipestpip2.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 depmaxformestlxml, 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 depmaxformsur 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".BugsSoumettez les rapports de bugs à James Pringle à l'adressejpringleBEAR @ jhu.edu.