Rédaction du manuel de TXM

Actuellement le manuel est rédigé avec LibreOffice Writer en .ODT.

Le document ODT utilise des images stockées dans un répertoire nommé “ImagesTXM”, ainsi que des images internes.

Le manuel est diffusé sous trois formats :

  • HTML, pour la consultation en ligne, organisée par sections principales ;
  • PDF, pour la consultation compatible avec l'impression partielle ou totale d'une version paginée1) ;
  • TXM, pour la consultation assistée par les outils de TXM2)

Les sources de référence du manuel sont sauvegardées dans un entrepôt SVN de Sourceforge3) à l'adresse https://sourceforge.net/p/txm/code/HEAD/tree/trunk/doc/user%20manuals (document principal “txm-manual-fr.odt”).

Proposition de modifications du manuel

Quand on veut proposer des modifications on fournit une nouvelle version du document ODT avec enregistrement des modifications.

Voici une procédure complète à suivre pour proposer des modifications, en s'appuyant sur les outils SVN de TXM :

  1. éventuellement, installer LibreOffice
  2. éventuellement, installer l'extension SVN de TXM4) pour récupérer les sources du manuel :
    • régler le niveau de mise à jour à ALPHA5) :
      • ouvrir la page de préférences “TXM > Avancé”
      • pour le paramètre “Niveau de mise à jour”, sélectionner le niveau ALPHA. Ce niveau de mise à jour permet d'installer les extensions en cours de développement.
      • valider par “OK”
    • ajouter l'extension :
      • lancer la commande “Fichier > Installer une extension”
      • Dans la fenêtre ouverte, sélectionner l'extension “SVN”
      • valider par “OK”
      • accepter la licence puis relancer TXM
    • vérifier la présence de l'extension
      • on doit pouvoir ouvrir la nouvelle vue “Affichage > Vues > Autres… > SVN > SVN Repositories”
  3. récupérer les sources ODT et images du manuel
    • si nécessaire, ajouter l'entrepôt 'doc' des sources du manuel dans l'extension SVN de TXM :
      1. ouvrir la vue “Affichage > Vues > Autres… > SVN > SVN Repositories”
      2. ajouter l'entrepôt avec le bouton “New Respository Location” de la barre d'outils (icone de silo avec un petit '+' - plus - vert)
      3. dans le champ “URL : ” coller l'adresse https://svn.code.sf.net/p/txm/code/trunk/doc
      4. valider avec “Terminer”
    • exporter le répertoire “user manuals” depuis l'entrepôt 'doc' des sources du manuel :
      1. ouvrir la vue “Affichage > Vues > Autres… > SVN > SVN Repositories”
      2. mettre à jour l'entrepôt 'doc' depuis Internet en le sélectionnant puis en cliquant sur le bouton “Refresh” (icone de recyclage) de la barre d'outils
      3. ouvrir la hiérarchie de fichiers de l'entrepôt 'doc' en cliquant sur la flèche horizontale noire située à la racine de l'entrepôt
      4. exporter le répertoire “user manuals” avec la commande “Export…” de son menu contextuel (ouvert par clic droit sur le nom du répertoire)
        1. saisir dans le champ “Path:” le chemin du répertoire où sera exporté le répertoire “user manuals”, ou naviguer jusqu'à ce répertoire avec le bouton “Browse…”
    • le manuel est éditable en ouvrant le fichier “txm-manual-fr.odt” situé dans le répertoire exporté (remarque : ce document utilise les images situées dans le répertoire “ImagesTXM” du répertoire exporté)
  4. passer le document principal “txm-manual-fr.odt” en “Enregistrement des modifications” :
    1. ouvrir le fichier “txm-manual-fr.odt”
    2. lancer la commande “Édition > Suivi des modifications > Enregistrer les modifications”
    3. enregistrer
  5. proposer les modifications à travers une nouvelle version du manuel, deux cas de figure :
    • a) vous avez les droits pour enregistrer une nouvelle version du manuel dans l'entrepôt 'doc' SVN de TXM
      • commiter les sources proposées
        • pour commiter les modifications depuis TXM, il faut utiliser un projet SVN :
          • ouvrir la vue “Affichage > Vues > Autres… > Généralités > Explorateur de projets”
          • si nécessaire, installer le projet 'doc' depuis SVN :
            • commande “Nouveau > Projet… > SVN > Project from SVN” (clic droit dans la vue “Explorateur de projets” pour ouvrir le menu contextuel), valider avec “Suivant”
            • utiliser l'entrepôt 'doc' déjà défini ou le créer avec l'option “Create a new repository location”
            • valider avec “Terminer”, deux fois
              → les sources du manuel sont copiées sur votre disque dur depuis l'entrepôt SVN. On peut dès lors éditer le manuel directement depuis la vue “Explorateur de projets” (double clic sur le fichier “doc > user manuals > txm-manual-fr.odt”))
          • commiter le manuel directement depuis la vue “Explorateur de projets” avec la commande “Equipe > Commit…” du menu contextuel du projet 'doc' (clic droit sur la racine 'doc')
            • lors du premier appel il faut renseigner ses coordonnées d'accès au SVN (identifiant / mot de passe)
    • b) vous n'avez pas les drois pour enregistrer une nouvelle version du manuel dans l'entrepôt 'doc' SVN de TXM
      • envoyer le nouveau document “txm-manual-fr.odt” à l'adresse 'textometrie AT groupes.renater.fr'
      • si les modifications comprennent également des images :
        • créer une archive du répertoire exporté “user manuals”
        • déposer l'archive sur un entrepôt
        • envoyer un lien de téléchargement de l'archive à l'adresse 'textometrie AT groupes.renater.fr'

Production des différents formats du manuel

HTML

Export pour le manuel en ligne de TXM 0.7.9

Le HTML (xhtml) est produit par l'extension Writer2xhtml de LibreOffice Writer :

  1. créer le répertoire “manual_dir”
  2. Lancer “Fichier > Exporter”
  3. choisir le filtre “XHTML 1.1 + MathML 2.0 xhtml”
  4. sélectionner le répertoire de sortie “manual_dir”
  5. choisir le nom de fichier “manual”
  6. valider
  7. régler les paramètres du filtre d'export de la façon suivante :
    • style : format d'origine
    • Dimensions : 100%
    • convertir unité en pixels : oui
    • utiliser la taille d'origine des images: oui
    • exporter les notes : oui
    • exporter les propriétés du document (DC) : oui
    • séparer le document au niveau des titres :
      • niveau des titres : 2
      • répéter le niveau des titres : 5
    • sauver les images dans un sous-répertoire : oui
  8. régler les styles par feuille CSS :
    • recopier le répertoire ”sftp://sheiden@vm-web-preprod.pun.ens-lyon.fr/textometrie/files/software/TXM/0.7.9/index_files” dans le répertoire “manual_dir”
    • lancer la macro SearchAndReplaceInDirectory pour déclarer la CSS en patchant tous les fichiers HTML :
      • inputDirectory : manual_dir
      • find :

</head>

  • replaceWith :

<link href="index_files/sf.css" media="all" rel="stylesheet" type="text/css" /> </head>

Le résultat est un HTML stylé segmenté au niveau des sections principales avec un sommaire général.

Procédure d'export obsolète

Autres outils possible pour produire du HTML

1) LibreOffice Writer

soffice --headless --convert-to htm:HTML --outdir txm-manual ~/svn/doc/user\ manuals/txm-manual-fr.odt

Le résultat est un fichier HTML unique, très gros. On préfère pour l'instant la version découpée pour les accès en ligne rapides.

2) pandoc

pandoc txm-manual-fr.docx -o txm-manual-fr.html

Le résultat est un fichier au format HTML mal formé, notamment sans préambule de déclaration.

PDF

Le PDF est produit par LibreOffice Writer avec la commande “Fichier > Exporter au format PDF…”.

TXM

Le TXM est produit par le module d'import ODT/DOC/RTF + CSV appliqué à un répertoire contenant les sources ODT et images du manuel, exporté ensuite avec la commande “Fichier > Exporter > Corpus au format binaire…”.

Diffusion du manuel de TXM

PDF

Le manuel est diffusé par les logiciels d'installation de TXM et par le site textometrie.org (section Documentation) :

  • télécharger le PDF dans le répertoire 'files/documentation' du site de préprod et faire un push

HTML

En attendant d'être diffusé par le site textometrie.org, le manuel en ligne est diffusé par SF :

  • copier le contenu (répertoires et fichiers) du répertoire 'manual_dir' dans '/home/project-web/txm/htdocs/doc/manual/<version>/fr ' sur SF
  • copier également le contenu (répertoires et fichiers) du répertoire 'manual_dir' dans '/home/project-web/txm/htdocs/doc/manual' sur SF (pour la compatibilité ascendante avec les anciens accès au manuel, notamment indexés par Google)
    • remarque 1 : attention de ne pas écraser le lien 'manual1.xhtml'
    • remarque 2 : on peut se contenter de ne copier que les fichiers .xhtml (pas les .xml et .html)
1) certaines sections de référence, comme la syntaxe des expressions CQL ou des expressions régulières, peuvent être plus pratiques à consulter et à commenter sur un support indépendant
2) à noter que l'édition du corpus ne correspond pas à l'édition HTML du manuel
3) les sources sont versionnées
4) n'importe quel autre client SVN peut aider à récupérer les sources du manuel
5) l'extension SVN est encore à l'état de prototype
public/txm_manual_writing.txt · Dernière modification: 2018/01/24 11:04 par slh@ens-lyon.fr