+ DHIS 2 guide de documentation +

+ + + DHIS 2 guide de documentation + + + + Jason + + + Pickering + + + + + + + + 14/09/09 + + + + DHIS2 + + + Documentation + + + DocBook + + + + + + 2 + + + 28/10/09 + + + + Ajout de quelques informations supplémentaires sur des documents multilingues et des éditeurs. + + + + + + 1 + + + 29/09/09 + + + + Ajout d'informations plus vous lancer dans le bzr et DocBook + + + + + + + DHIS2 guide de documentation + +

+ + DHIS 2 Documentation Aperçu du système + + + DHIS 2 est un système Web d'information de gestion globale en cours de développement très actif. Bien qu'il soit principalement destiné à la gestion de granulats, les données géoréférencées de santé, il devrait être possible d'utiliser le système à d'autres fins aussi. Actuellement, il existe un grand nombre de poches isolées de systèmes de documentation dans divers formats (MediaWiki, documents Word, Confluence). Il ya une nécessité de consolider le processus de documentation et de la mettre davantage en ligne avec la nature distribuée du développement de l'application elle-même. On a donc suggéré de déplacer la documentation actuelle sur la plateforme DocBook. Cet article ne va pas discuter des mérites relatifs de la plate-forme DocBook, mais servira plutôt comme un guide succinct à son utilisation par DHIS 2 exécutants, des utilisateurs et développeurs. Les lecteurs sont encouragés à prendre leur propre décision quant à savoir si d'utiliser DocBook ou non à des fins de documentation. + +

+ + Introduction + + + Un des principaux avantages de DocBook est qu'il existe une séparation complète entre le contenu et la présentation. DocBook est un format pur XML, et est bien documenté. On croit que seul un très petit sous-ensemble de ses fonctionnalités seront nécessaires afin d'atteindre beaucoup plus de documentation de qualité pour DHIS. Il ya quelque 400 marque distincte en place les éléments qui répondent à presque n'importe quel niveau de besoins en documentation technique, mais en réalité, seulement quelques douzaines de ces éléments devront probablement être employées pour assurer une documentation de haute qualité pour DHIS 2, tant pour les imprimés ainsi que sur des formats en ligne, telles que HTML ou de systèmes d'aide intégré dans l'application elle-même. Par conséquent, il existe un large éventail de possibilités en termes de quel éditeur peut être utilisé pour la création de fichiers DocBook. Une liste assez complète des possibilités se situe + + ici + + . Il est actuellement recommandé d'utiliser + + Syntext Serna gratuit + + pour les fichiers source DocBook montage comme WYSIWYG. Il n'est pas recommandé d'utiliser la XMLmind éditeur XML Editor Personal Edition (aussi connu sous le nom XXE personnelles), comme l'éditeur "silencieusement" lieux des espaces inutiles et d'autres ornements à la source DocBook qui permet l'édition collaborative de documents très difficile. + + + L'un des concepts clés à garder à l'esprit lors de création de documentation en DocBook, ou autres formes de présentation neutre, c'est que la + + contenu + + du document devrait être considéré en première instance. Le + + Présentation + + du document aura lieu dans une étape distincte, où elle sera rendue dans différents formats, tels que HTML et PDF. Il est donc important que le document est sera organisé et structuré, avec des balises DocBook et les éléments structurels qui sont pris en compte. + + + Pratique, il est intéressant de diviser votre document en plusieurs sections à l'aide de la «secte», ou élément de section. Des éléments de section peuvent également être imbriqués entre eux, tels que "Section 1" et "article 2". Ce concept est essentiellement le même que + + Microsoft Word + + ou d'autres programmes de traitement de texte. DocBook se charge automatiquement de la numérotation des sections pour vous lorsque le document est produit. Deux autres éléments importants sont les itemizedlist "et" NumberedList ". Ils sont tout à fait similaire, mais une liste détaillée correspond à une liste à puces, dont une liste numérotée sera rendue à chaque élément étant numérotés de façon séquentielle. Les autres éléments clés sont "screenshot" et "table" qui devrait être auto-explicatif. + +

+ + Premiers pas avec Launchpad + + + Actuellement, le système de documentation fait partie du code source hébergé par + + Launchpad + + . Launchpad est une plate-forme collaborative qui permet à plusieurs personnes de travailler sur des projets en collaboration. Pour que cela soit possible, un système de contrôle de version est nécessaire afin de gérer tous les changements que plusieurs utilisateurs mai faire. Launchpad utilise le + + Bazaar + + contrôle de code source du système. Alors qu'il est au-delà de la portée de ce document pour décrire la fonctionnalité de + + Bazaar + + , Les utilisateurs qui souhaitent créer de la documentation devra gagner au moins une compréhension de base du fonctionnement du système. Un guide de base est fournie dans la section suivante. + + + Afin de commencer à ajouter ou éditer la documentation, vous devriez d'abord effectuer un checkout du code source. Si vous ne possédez pas déjà un ID de connexion Launchpad, vous devrez en obtenir un. Cela peut être fait + + ici + + . Une fois que vous vous inscrivez sur Launchpad, vous aurez besoin de demander l'accès à la + + dhis2-Documenteurs + + groupe. Connectez-vous sur Launchpad, puis accéder à la demande + + ici + + . Votre demande devra être approuvée par les administrateurs du groupe. Une fois que vous avez été autorisés à accéder au groupe, vous pouvez valider les modifications apportées à la branche de documentation et d'envoyer et de recevoir des courriels sur la liste des groupes. + +

+ + Obtenir la source du document + + + Afin de modifier la documentation, vous aurez besoin de télécharger les pages source de la documentation à votre ordinateur. Launchpad utilise un système de contrôle de version connue sous le nom bzr. Il existe différentes méthodes pour obtenir Bazaar à travailler sur votre système, selon le système d'exploitation que vous utilisez. Une bonne étape-par-étape pour + + Microsoft + + systèmes d'exploitation peuvent être consultés + + ici + + . Si vous utilisez Linux, vous aurez besoin d'installer bzr sur votre système grâce à votre gestionnaire de paquets, ou à partir du code source. + + + Une fois que vous avez installé bzr sur votre système, vous aurez besoin de télécharger le source du document. Il suffit de suivre cette procédure: + + + + + Assurez vous d'avoir installé Bazaar. + + + + + Début Bazaar par clic droit sur un dossier si vous utilisez + + Windows + + et en sélectionnant + + Ici bzr + + . Si vous utilisez Linux, vous pouvez simplement créer un dossier pour contenir les sources du document. Vous pouvez placer la source du document dans n'importe quel dossier que vous aimez. + + + + + Pour télécharger la dernière version du type de documents DHIS2 projet: + + bzr branche http://bazaar.launchpad.net/% 7Edhis2-documenters/dhis2/dhis2-docbook-docs + + Si vous utilisez Linux, ou encore, si vous utilisez + + Windows + + tapez l'URL dans le référentiel de code source " + + http://bazaar.launchpad.net/ 7Edhis2-documenters/dhis2/dhis2-docbook-docs% + + " + + + + + Le processus de téléchargement devrait démarrer et tous les fichiers source de la documentation sera téléchargé dans le dossier que vous avez spécifié. + + + +

+ + Modification de la documentation + + + Une fois que vous avez téléchargé le source, vous devez disposer d'une série de dossiers au sein de la dhis2-docbook-docs. Tous les documents doivent être placés dans le + + dhis2-docbook-docs/src/docbkx/XX + + dossier. Notez que la + + XX + + représente la norme ISO 639-1 (deux lettres) code de langue de la documentation. Si vous développez la documentation en langue anglaise, le placer à l'intérieur du + + / dhis2-docbook-docs/src/docbkx/en / + + dossier. Placez les fichiers image que mai être liée à votre document dans le + + / dhis2-docbook-docs/src/docbkx/XX/resources/images + + dossier et de liens entre ces intérieur de votre document DocBook en utilisant un fichier de lien relatif. Lorsque les documents sont construits, dans une étape distincte, les images seront automatiquement copiées dans le répertoire correct pendant le processus de construction. + +

+ + En utilisant des images + + + Les captures d'écran sont très utiles pour fournir des informations aux utilisateurs sur la manière dont des actions doit être effectuée. DocBook a pas de mécanismes intrinsèques de savoir exactement comment l'image doit être rendu dans le document final. Par conséquent, il est nécessaire de prévoir des instructions à travers leurs attributs. Le fragment de code XML suivant montre comment une image peut être spécifiée pour occuper 80% de la largeur de la page disponible. Pour les captures d'écran au format paysage, ce qui semble être un montant approprié. Vous mai besoin d'expérimenter un peu pour obtenir une bonne largeur de votre image. Alternativement, vous pouvez modifier la résolution de l'image elle-même, afin d'obtenir une taille adéquate pendant le rendu. + + + <screenshot> <screeninfo> DHIS2 connexion écran </ screeninfo> <mediaobject> <imageobject> <imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/> </ imageobject> </ mediaobject> < / screenshot> + + + Pour d'autres images, en fonction de leur taille, une valeur différente mai être nécessaire. Si vous ne spécifiez pas une largeur de votre image, et sa dimension intrinsèque est supérieure à la largeur d'écran disponible, l'image mai débordement de certains types de documents avec une largeur fixe, tels que PDF. + +

+ + Lier des documents ensemble + + + DocBook offre un cadre modulaire où plusieurs documents distincts peuvent être reliés entre eux dans un document maître. Fragments de différents documents peuvent également être réutilisée dans différents contextes. Il est donc important de déterminer si votre document doit être construit comme un article ou un chapitre. Les chapitres sont essentiellement des parties d'un livre, et peuvent donc être reliés entre eux dans un document plus volumineux très facilement. Les articles sont essentiellement autonome des documents, mais ils peuvent aussi être rassemblés dans un document plus important au niveau du composant. + + + Si vous voulez lier plusieurs articles réunis dans un livre, DocBook fournit un mécanisme pour assigner un identifiant à un article. Dans l'exemple ci-dessous, une section a été attribué un id. Cet id doit être unique dans le document. + + + + <section id="mod2_1"> <title> Premiers pas avec DHIS2 </ title> .... + + + + Afin d'inclure un article dans un livre, une déclaration XInclude doit être utilisé. L'exemple suivant montre comment. + + + + <chapter> <title> Premiers pas avec DHIS2 </ title> <xi: include xmlns: xi = "http://www.w3.org/2001/XInclude" href = "dhis2_user_man_mod2.xml" XPointer = "mod2_1" encoding = "UTF-8" /> + + + + Notez que le nom du fichier et l'ID a été attribué dans le document parent, se référant au fichier réel (href) et le fragment spécifique du document d'enfants qui devraient être mentionnés dans le document parent (XPointer). + + + Y compris les chapitres d'un livre est très simple. L'exemple ci-dessous illustre comment: + + + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_ mod1.xml" encoding="UTF-8"/> + + + + Dans ce cas, il n'est pas nécessaire de explicitement référence à une partie du document, à moins que vous ne voulez inclure une partie du chapitre. Si vous souhaitez utiliser une section de ce chapitre, vous pouvez affecter un identifiant à cette section, puis de référence qui coupe d'un XPointer. + +

+ + Traitement de la documentation multilingue + + + La structure du répertoire de la documentation a été créé afin de faciliter la création de documents dans n'importe quelle langue. Si vous voulez créer un nouvel ensemble de documents dans une langue donnée, il suffit de créer un nouveau répertoire dans le + + dhis2-docbook-docs/src/docbkx / + + répertoire. Soyez sûr d'utiliser le code ISO 639-1 pour la langue que vous allez créer des documents po Une liste complète de ces codes peuvent être trouvés + + ici + + . Ajouter un nouveau dossier pour les images dans un sous-répertoire, en remplaçant XX par l'actuel code ISO 639-1 pour la langue que vous allez créer des documents po Vous aurez également besoin d'éditer le fichier pom.xml pour l'essentiel dhis2-docs docbook - répertoire. Si vous n'êtes pas sûr de ce que des modifications doivent être apportées à ce fichier, demandez sur la liste de diffusion d'abord, comme ce fichier contrôle la production de toute la documentation. + +

+ + Construire la documentation + + + Un des principaux avantages du format DocBook est que la documentation source peut être transformée en une grande variété de formats, dont HTML, chunked HTML, XHTML, PDF, et un certain nombre d'autres formats. Il existe une grande variété d'outils qui sont capables d'accomplir cette tâche. Fondamentalement, le source XML du document est transformée en utilisant le standard DocBook feuilles de style XSL dans le format souhaité. La liste complète des outils capables de transformer DocBook ne seront pas répertoriés ici, mais quelques exemples sont fournis ci-dessous. + + + Dernières versions de la documentation sont disponibles + +

+ + Construire la documentation avec Apache Maven + + + Afin de transformer les fichiers source de documentation pour différents formats, tels que HTML ou PDF, vous aurez besoin d'installer le programme Apache Maven. Vous pouvez obtenir une copie + + ici + + ou en l'installant dans votre gestionnaire de paquet si vous utilisez Linux. Vous n'avez qu'à exécuter la commande + + mvn clean package + + sur Windows ou sur Linux à partir du + + / dhis2-docs docbook - + + répertoire. Maven va commencer à télécharger les composants nécessaires pour transformer les documents en HMTL et PDF. Une fois le processus terminé (soyez patient la première fois, car il ya un certain nombre de composantes qui doivent être téléchargés), tous les types de document cible sera généré dans le répertoire / + + dhis2-docbook-docs/target/docbkx + + répertoire. Documents HTML sera dans le répertoire HTML et PDF seront dans le répertoire PDF. + +

+ + Construire avec xmlto + + + + xmlto + + est un utilitaire disponible sur les plates-formes Linux pour transformer des documents DocBook en différents formats. Plus d'informations sur le paquet peut être trouvé + + ici + + . Si vous ne souhaitez pas utiliser Apache Maven pour une raison quelconque, vous pouvez installer + + xmlto + + par votre gestionnaire de paquets. Une fois que vous avez installé + + xmlto + + vous pouvez simplement exécuter + + xmlto + + html + + + file_to_transform + + + où les + + file_to_transform + + paramètre est le nom du fichier que vous voulez transformer. Il existe de nombreux autres formats disponibles, tels que PDF, PS, JavaHelp et autres. + +

+ + S'engager vos changements sur Launchpad + + + Une fois que vous avez terminé l'édition de votre document, vous devrez valider vos modifications sur Launchpad. Ouvrez une invite de commande sous Windows ou un shell sous Linux, et naviguez jusqu'au dossier où vous avez placé votre documentation. Si vous avez ajouté tous les nouveaux fichiers ou des dossiers à votre succursale locale, vous devrez les ajouter à l'arbre source avec le + + bzr add + + commande, suivi du nom de dossier ou fichier (s) que vous avez ajoutés. Une fois que vous avez ajouté tous vos nouveaux fichiers, vous aurez besoin de les commettre à votre agence locale avec la commande suivante: + +

+ + + bzr commit-m "Création de traduction en amharique de la documentation» + + +

+ + Il suffit d'ajouter un message informatif de ce que vous avez fait. Une fois que vous avez commis des modifications à votre succursale locale, vous pouvez les pousser à la branche principale avec la commande suivante: +

+ + + bzr push bzr + ssh: / / bazaar.launchpad.net /% 7Edhis2-documenters/dhis2/dhis2-docbook-docs + + +

+ + + Si vous avez des questions, ou ne trouvant pas que vous pouvez démarrer, il suffit d'envoyer un email avec votre problème + + dhis2-documenters@lists.launchpad.net + + . + +