Re: more compiling questions

[Jean-Charles Malahieude]

Le 20/12/2009 16:28, Carl Sorensen disait :
> On 12/20/09 8:14 AM, "Jean-Charles Malahieude"<address@hidden>  wrote:
>
> > Le 20/12/2009 05:19, Carl Sorensen disait :
> > > On 12/19/09 7:29 PM, "Mark Polesky" wrote:
> > >
> > > > 2) If I'm running `make' or `make doc', can I continue to
> > > >      work on git, changing branches, making commits, etc.?  I
> > > >      assume no, but if someone knows, let me know.
> > >
> > > You can't change branches, because that changes the files that make is
> > > working on.
> > >
> > > You can make a commit, because a commit doesn't change the files, it just
> > > changes the git database, which make doesn't use.
> > >
> > > You can't edit files, because make needs them.
> > >
> > > If you really want to do this, you can set up two different local
> > > repositories, and run make in one then do further work on the other.  You
> > > could sync them through a remote repository that you could set up on
> > > repo.or.cz.
> >
> > That's the reason why I use a "local clone". Here is my tree :
> >
> >    GIT |-- Lily
> >        |-- Mentors
> >        \-- Traduc
> >
> > Lily is synchronized with the remote. You then create Mentors :
> >
> > Lily]$ git checkout master
> > Lily]$ git clone -l -s -n . ../Mentors
> >    Initialized empty Git repository in /home/jcharles/GIT/Mentors/.git/
> > Lily]$ cd ../Mentors/
> > Mentors]$ git reset --hard
> >
> > you do whatever you want in Mentors while compile is running in Lily.
> > Later on you pull/push Mentors from/to Lily.
>
> What a cool idea!  I never thought of cloning a local repository locally!
>
>
> > I've written (in French for the moment) a kind of "howto" dedicated to
> > those who would like to help me translating and know nothing about git,
> > emacs and all other aliens. If you are intersted, let me know.
>
> Please let us see it. I think I know enough French to figure out what you've
> written.


Here it is! in wiki formating.
Questions, comments, amendments are welcome.

Cheers,
Jean-Charles

'''Petit guide à l'usage de l'utilisateur de LilyPond impliqué dans la traduction de la documentation'''

= Préliminaires =

Ces quelques lignes constituent un « retour d'expérience » et en quelque sorte un pense-bête destiné à tous ceux qui désirent prêter la main à la traduction de LilyPond, le système ''open source ''de gravure automatisée de partitions musicales.

Le travail de traduction pour LilyPond s'apparente quelque peu à celui d'un artisan qui dispose d'un bâtiment aménagé. On y trouve un magasin dans lequel il entrepose la matière première et des produits finis – fournis par les développeurs ou autres traducteurs – ainsi que plusieurs ateliers – la dorure à l'or fin ne doit pas côtoyer le marteau pilon.

Voici ce à quoi cela pourrait ressembler, à partir d'un répertoire personnel (/home/moi/) :


 GIT |-- Lily 
     |-- Mentors
     |-- Traduc 
     `-- ZeDoc
       |-- fr.po 
       |-- learning 
       |-- local.make 
       |-- notation 
       |-- texidocs 
       `-- usage 


Ce même artisan dispose aussi d'une caisse à outils plutôt bien garnie – emacs – et d'un établi bien ordonné – la console. Il est en cheville avec un transporteur spécialisé – git.


''Je pars du principe que je n'ai pas l'accès en écriture sur le dépôt communautaire, et que ma machine dispose d'une distribution Linux – pour Windows, je ne sais pas faire. L'un des avantages des environnements UNIX réside dans le fait qu'ils sont ''réellement'' multitâches.''


NB : Au fil de ce guide, les cadres en chasse fixe indiquent soit l'utilisation d'une console, soit l'utilisation d'emacs. La console est toujours indiquée par un préfixe en première ligne :

address@hidden repertoire]$

Pour plus d'explications sur l'art de contribuer au développement de LilyPond, il est primordial de lire, dans la langue de Shakespeare, le Manuel du contributeur (version de développement) sur le site lilypond.org et tout particulièrement la partie [http://lilypond.org/doc/v2.13/Documentation/contributor/translating-the-documentation#translating-the-documentation 3.8 Translating the documentation]. Et ne venez pas me dire que cette partie devra être traduite ! 


= Préparation du système de transactions =

Git est un logiciel de gestion de versions décentralisé. C'est un logiciel libre créé par Linus Torvalds, le créateur du noyau Linux, et distribué sous la GNU GPL version 2.

Git ne repose pas sur un serveur centralisé. C'est un outil bas niveau, qui se veut simple et très performant, dont la principale tâche est de gérer l'évolution du contenu d'une arborescence.

Git indexe les fichiers d'après leur somme de contrôle calculée avec la fonction SHA-1. Quand un fichier n'est pas modifié, la somme de contrôle ne change pas et le fichier n'est stocké qu'une seule fois. En revanche, si le fichier est modifié, les deux versions sont stockées sur le disque.


Avant d'utiliser git dans le concret, je crée un fichier de configuration qui me permettra, entre autres, de signer toutes mes contributions à la communauté :

[

address@hidden ~]$ git config --global color.ui auto

address@hidden ~]$ git config --global user.name "c'est moi"

address@hidden ~]$ git config --global user.email address@hidden

Ces commandes vont créer et alimenter un fichier .gitconfig à la racine de mon répertoire personnel. Il recense les réglages personnels de l'utilisateur de git. Pour plus d'information sur ce fichier, il suffit de consulter le manuel de git, et plus précisément la page [http://www.kernel.org/pub/software/scm/git/docs/git-config.html http://www.kernel.org/pub/software/scm/git/docs/git-config.html].


= Création des dépôts locaux =

Il s'agit de préparer l'agencement du local – le répertoire /home/moi/GIT. 


== Le dépôt généraliste ==

Il s'agit en fait d'une copie locale de plusieurs branches du dépôt communautaire. En effet, mieux vaut travailler chez soi à l'abri des intempéries que de sans arrêt faire la navette et bloquer les autoroutes. Il me servira en outre pour effectuer des fusions entres les différentes branches dont je suis attentivement l'évolution.


Je commence par aménager les lieux, en console :

address@hidden GIT]$ mkdir Lily

address@hidden GIT]$ cd Lily/

address@hidden Lily]$ git init-db

address@hidden Lily]$ mkdir .git/remotes

Dans le souci de préserver à la fois mes articulation et mon clavier, je crée des raccourcis pour les branches que je suis assidûment, en indiquant le protocole utilisé et l'adresse du serveur d'origine ainsi que les correspondances aller et retour :


la branche principale – '''master'''

address@hidden Lily]$ emacs .git/remotes/maitre&

ouvre le fichier en question, dans lequel j'écris les lignes :

 URL: git://git.sv.gnu.org/srv/git/lilypond.git/
 Push: master:refs/heads/master
 Pull: master:refs/remotes/origin/master


et la branche dévolue aux traducteurs – '''lilypond/translation'''

[

address@hidden Lily]$ emacs .git/remotes/trans&


ouvre le fichier en question, dans lequel j'écris les lignes :

 URL: git://git.sv.gnu.org/srv/git/lilypond.git/
 Push: lilypond/translation:refs/heads/lilypond/translation
 Pull: lilypond/translation:refs/remotes/origin/lilypond/translation


Je rapatrie les branches qui m'intéressent. Cette opération se fait en deux temps : le téléchargement à proprement parler des données qui résident sur le serveur communautaire, puis la création d'un lien entre la branche déportée et la branche locale.

[

address@hidden ~]$ cd GIT/Lily/

address@hidden Lily]$ git fetch maitre

address@hidden Lily]$ git checkout -b master origin/master

address@hidden Lily]$ git fetch trans

address@hidden Lily]$ git checkout -b lilypond/translation origin/lilypond/translation

== Les copies de travail ==

Elles sont au nombre de deux, et s'apparentent aux « ateliers » vus plus haut.

''Mentors'' correspond à la branche master. Elle regroupe tous les travaux de pur développement et est à la base de toutes les versions ; c'est là que je gère le fichier po/fr.po qui contient la version française des messages d'avertissement ou d'erreur. ''Traduc'' correspond à la branche de traduction pour tout ce qui concerne la documentation de LilyPond.


Le recours à des copies de travail permet, malgré un surcroit d'occupation du disque, d'économiser de la bande passante. Par ailleurs, ceci m'évitera de devoir repartir à zéro si je venais à tout casser puisque c'est là seulement que seront lancées les compilations... 

J'en profiterai pour recopier dans chacune d'elles le fichier local.make qui contient une ligne unique (CPU_COUNT = 2) indiquant le nombre de cœurs dont dispose ma machine.

address@hidden ~]$ cd GIT/Lily/

address@hidden Lily]$ git status

# On branch lilypond/translation

 nothing to commit (working directory clean)

address@hidden Lily]$ git clone -l -s -n . ../Traduc

 Initialized empty Git repository in /home/jcharles/GIT/Traduc/.git/

address@hidden Lily]$ cd ../Traduc/

address@hidden Traduc]$ git reset --hard

 HEAD is now at 418323f known issue in NR: extra cautionnary accidentals in \alternative block

address@hidden Traduc]$ cp ../ZeDoc/local.make .

address@hidden Traduc]$ cd ../Lily/

address@hidden Lily]$ git status

# On branch lilypond/translation

 nothing to commit (working directory clean)

address@hidden Lily]$ git checkout master

address@hidden Lily]$ git clone -l -s -n . ../Mentors

 Initialized empty Git repository in /home/jcharles/GIT/Mentors/.git/

address@hidden Lily]$ cd ../Mentors/

address@hidden Mentors]$ git reset --hard

 HEAD is now at 23aa0f9 Chord repetition fixes

address@hidden Mentors]$ cp ../ZeDoc/local.make .

address@hidden Mentors]$

== Le répertoire de secours ==

Le répertoire ''ZeDoc'' constitue une « zone de préservation ». En effet, quoi de plus frustrant que de devoir tout refaire parce qu'une synchronisation est récalcitrante alors que la dernière ligne du fichier xyz.itely était atteinte ! Il contient donc la même arborescence que le répertoire Documentation/fr afin d'y transférer temporairement les fichiers en cours de traduction, le temps par exemple de gérer un conflit de rapatriement ou si je me vois contraint de faire un git reset --hard. Y est aussi stockée une copie du fichier local.make.


= La traduction =

Ce travail comporte deux aspects. Tout d'abord, il est primordial d'avancer dans la traduction jusqu'à obtenir et fournir l'intégralité de la documentation de LilyPond dans la langue de Molière. Dans un deuxième temps, bien que cela soit souvent nécessaire de s'y appliquer en parallèle, les documents déjà traduits doivent suivre l'évolution de leur version originale.


''Pour les besoins de la démonstration, toutes les opérations qui suivent sont effectuées sur la branche dévolue aux traducteurs – l'atelier Traduc – et à l'aide d'emacs.''

''Vous trouverez en annexe une liste des différentes commandes et parmétrages utiles pour emacs.''


== Ouverture du chantier ==

Avant toute chose, il est préférable de compiler la documentation en local, afin de pouvoir se rendre compte au plus vite et en réel du travail fourni. C'est aussi une bonne habitude à prendre que de relire les modifications apportées dans les mêmes conditions que l'utilisateur normal qui se connecte sur lilypond.org – ou a téléchargé la documentation – et non simplement dans le fichier source, surchargé quant à lui de commandes et commentaires. Les « dérapages incontrôlés » du clavier y seront plus évidents !


Comme vous le savez, la documentation de LilyPond regorge d'exemples. Ceux-ci s'appuient sur la version du logiciel. Il est donc nécessaire de commencer par le compiler en local si l'on n'a pas installé la dernière version de développement. N'oublions pas que lorsque des parties du programme seront modifiées en profondeur, il faudra re-générer ces « binaires ».


 C-x C-f ~/GIT/Traduc/VERSION


 M-x compile
 Compile command: ./autogen.sh


 M-x compile
 Compile command: make -j2

 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 20:05:31

[...]

 Compilation finished at Sat Nov 21 20:11:04


 M-x compile
 Compile command: make -j2 doc

 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 20:12:10

[...]

 Compilation finished at Sat Nov 21 20:51:58


== Activité pour LilyPond ==

Nous pouvons maintenant mettre les mains dans le cambouis.


La documentation étant disponible sous différents formats – HTML pour une lecture dans un navigateur, PDF en vue de son impression, et INFO pour une consultation en console ou sous emacs – les règles qui s'appliquent aux rédacteurs s'appliquent de la même manière aux traducteurs :

* longueur de ligne des fichiers sources limitée à 80 caractères,
* langue, syntaxe et orthographe irréprochables,
* ponctuation correcte,
* respect des règles typographiques, à ceci près qu'un point sera toujours suivi de '''deux''' espaces pour une meilleure lecture en mode INFO – les superflues seront automatiquement éliminées lors de la compilation du HTML ou du PDF.

LilyPond tend à imprimer de la musique selon les règles de l'art de la gravure traditionnelle, la documentation vise donc le même objectif d'extrème qualité.


La documentation et le site internet de LilyPond sont découpés en plusieurs parties – on pourrait même les comparer à des ''matriochkas'', ces fameuses poupées russes. Chaque partie se compose d'un fichier maître qui fait appel à une hiérarchie de différents fichiers. Par exemple, la partie traitant de la musique vocale – vocal.itely – est rattachéee au chapitre Notation spécialisée – specialist.itely – lui-même partie intégrante du manuel de notation – notation.itely.


De nombreux exemples inclus dans la documentation sont regroupés dans un répertoire spécifique – Documentation/snippets. Ainsi, lorsqu'une syntaxe évolue, il n'y a qu'un seul fichier à modifier, au lieu des huit instances – une pour chacune des langues disponibles à ce jour. Ils proviennent en majorité du ''LilyPond Snippet Repository'' (LSR) – dépôt des extraits de code mentionné sous l'appellation « Morceaux choisis » dans la documentation. Leur titre et explication sont traduits dans un fichier séparé ; toutes ces versions « localisées » seront rapatriées dans le fichier d'origine par une routine spécifique. Toutes les lignes de commentaire des exemples, issus du LSR ou non, sont répertoriées dans le fichier Documentation/po/fr.po.


Si l'on considère la traduction du fichier vocal.itely, il faudra donc, au fur et à mesure de l'avancement, penser à traduire aussi les commentaires répertoriés dans Documentation/po/fr.po et les entêtes des fichiers inclus – modification ou création d'un fichier

*.texidoc

.


=== Traduction nouvelle ===

La traduction francophone ayant débuté en 2006, de nombreuses parties ont déjà été traduites, du moins partiellement. Le ''Grand Documentation Project'' lancé début 2008 a grandement ralenti le rythme dans la mesure où le manuel d'initiation a été remanié de fond en comble, ce qui n'a pas épargné les autres. 


Lorsqu'une partie de la documentation n'est pas disponible en français, cela ne signifie pas pour autant que son fichier source est inexistant. Ceci se produit lorsque une ancienne traduction est devenue tellement obsolète qu'elle a été « déconnectée » ; le fichier est présent dans l'arborescence de Documentation/fr mais sous forme de « squelette ». Voici les premières lignes de Documentation/fr/notation/percussion.itely avant qu'un traducteur ne décide de le reprendre :


 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-

 @ignore
     Translation of GIT committish: bdf8540b74167817eab96ed3d13b35477217f9fe

     When revising a translation, copy the HEAD committish of the
     version that you are working on.  See TRANSLATION for details.
 @end ignore

 @c \version "2.12.0"

 @c Translators: Valentin Villenave
 @c Translation checkers: Jean-Charles Malahieude, John Mandereau

 @node Percussions
 @section Percussions
 @translationof Percussion

 @menu

* Vue d'ensemble des percussions::

 @end menu

 @node Vue d'ensemble des percussions
 @subsection Vue d'ensemble des percussions
 @translationof Common notation for percussion

 La notation rythmique sert avant tout aux parties de percussions ou de
 batterie, mais on peut aussi s'en servir à des fins pédagogiques, pour
 montrer le rythme d'une mélodie.

 @menu

* Références en matière de notation pour percussions::

* Notation de base pour percussions::

* Portées de percussion::

* Notes fantômes::

 @end menu

 @node Références en matière de notation pour percussions
 @unnumberedsubsubsec Références en matière de notation pour percussions
 @translationof References for percussion @c external

 @untranslated

 @node Notation de base pour percussions


Si d'aventure le fichier source n'existe pas dans l'arborescence « francophone », il faudra y recopier le fichier en version originale.


=== Suivi et mise à jour d'une traduction existante ===

Prenons par exemple le fichier Documentation/fr/notation/vocal.itely ; il a été grandement remanié et nécessite une révision en profondeur. La version anglaise intègre de nouveaux paragraphes, le découpage est quelque peu modifié, de nouveaux exemples sont apparus aussi bien au fil du texte que par appel à un ''snippet''. 


Commençons par mettre à jour notre copie de travail :

address@hidden ~]$ cd GIT/Lily/

address@hidden Lily]$ git status

# On branch

master
 nothing to commit (working directory clean)

address@hidden Lily]$ git checkout lilypond/translation

 Switched to branch 'lilypond/translation'

address@hidden Lily]$ git pull trans

[...]

  19 files changed, 0 insertions(+), 0 deletions(-)

address@hidden Lily]$ cd ../Traduc

address@hidden Traduc]$ git pull

[...]

  19 files changed, 0 insertions(+), 0 deletions(-)

address@hidden Traduc]$

Nous voilà prets et presque dans le vif du sujet. 


Les traducteurs disposent d'un outil qui permet de vérifier que les traductions déjà en ligne correspondent bien à la version originale. Il se lance à partir du répertoire Documentation et renvoie un différentiel 

 C-x C-d ~/GIT/Traduc/Documentation/
 M-x compile
 Compile command: make ISOLANG=fr NO_COLOR=1 check-translation


Cependant, l'ampleur des travaux engendrés par le ''GDP'' le rend malheureusement peu exploitable en l'état actuel de la version française, aussi je ne m'étendrai pas.


Pour plus de confort, et pour éviter de jongler avec trop de tampons, nous ouvrons deux instances d'emacs : l'une pour notre ouvrage, et l'autre pour suivre en permanence la version originale en parallèle. Nous pourrons ainsi non seulement vérifier que le fil de ce qui est déjà traduit est bien en phase avec le discours original, mais encore recopier des parties de la version anglaise – nouveau découpage, indexation, exemples à actualiser.


 C-x C-f ~/GIT/Traduc/Documentation/fr/notation/vocal.itely

pour la version sous-titrée, et

 C-x C-f ~/GIT/Traduc/Documentation/notation/vocal.itely

pour la version originale.


Lorsqu'une section n'existe pas en français, comme « Vue d'ensemble de la musique vocale », elle se présente ainsi :

[...]

 @node Vue d'ensemble de la musique vocale
 @subsection Vue d'ensemble de la musique vocale
 @translationof Common notation for vocal music @c external

 @untranslated

[...]

et le lecteur sera redirigé sur la version anglaise lorsqu'il activera le lien.


Je commence par supprimer ce commentaire – @c external – et la commande @untranslated, puis recopie ce qu'il y a dans la version anglaise pour le traduire. Je n'oublie pas de faire une petite sauvegarde de temps en temps, 


Plus loin, je note qu'il est fait appel à un ''snippet'' :

[...]

 @snippets

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]

 {simple-lead-sheet.ly}

[...]

Je commence par vérifier s'il n'est pas déjà traduit – il pourrait être inclus dans une autre partie d'un manuel – auquel cas je me contenterai d'en vérifier la correction :

 C-x C-f ~/GIT/Traduc/Documentation/fr/texidocs/simple-lead-sheet.texidoc


À mon grand désespoir, l'ami emacs m'ouvre un fichier vide ! Il faut donc aller chercher la matière première :

 C-x C-f ~/GIT/Traduc/Documentation/snippets/simple-lead-sheet.ly

et recopier ce qui est nécessaire dans simple-lead-sheet.texidoc sans oublier d'y adjoindre la ligne qui comportera le numéro de révision :

 %% Translation of GIT committish: 
   texidoc = "
 When put together, chord names, a melody, and lyrics form a lead sheet:

 "
   doctitle = "Simple lead sheet"


Je fais ce qu'il faut pour obtenir :

 %% Translation of GIT committish: 
   texidocfr = "
 Pour obtenir la partition d'un chanson, il suffit d'assembler
 des noms d'accords, une mélodie et des paroles :

 "
   doctitlefr = "Chanson simple"

et enregistre avec C-x C-s


Après avoir avancé quelque peu, notamment si une section est achevée, je recompile la partie « restaurée ». J'active donc le ''buffer'' Documentation/fr/notation/vocal.itely. Rappelez-vous les matriochkas ! Il faut prévenir la grand-mère qu'on a changé la couleur d'une des petites-filles :

 M-x compile
 Compile command: touch ../notation.tely
 -*- mode: compilation; default-directory: "~/GIT/Traduc/Documentation/fr/notation/" -*-
 Compilation started at Sat Nov 21 21:02:54

 touch ../notation.tely

 Compilation finished at Sat Nov 21 21:02:55


Dans le cas où j'ai ajouté ou modifié un fichier dans Documentation/fr/texidocs/, j'ajoute sa traduction au ''snippet'' complet. Cette opération se lance à partir d'un ''buffer'' contenant le fichier ~/GIT/Traduc/VERSION :

 C-x C-f ~/GIT/Traduc/VERSION
 M-x compile
 Compile command: scripts/auxiliar/makelsr.py 
 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 21:06:39

[...]

 Compilation finished at Sat Nov 21 21:08:09

puis re-génère la documentation

 M-x compile
 Compile command: make -j2 doc
 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 21:09:43

[...]

 Compilation finished at Sat Nov 21 21:14:14


Je consulte le résultat avec Firefox. J'en profite pour vérifier que les liens renvoient au bon endroit... ZUT Y A UNE FAUTE GROSSIÈRE DANS LE SNIPPET !


Je reviens sous emacs, ''buffer'' simple-lead-sheet.texidoc, je corrige, puis enregistre.

Je reprends vocal.itely, puis 

 M-x compile
 Compile command: touch ../notation.tely


Je reprends VERSION, puis

 M-x compile
 Compile command: scripts/auxiliar/makelsr.py 

 M-x compile
 Compile command: make -j2 doc
 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 21:24:44

[...]

 Compilation finished at Sat Nov 21 21:28:02


Ouf ! Je ne m'en suis pas si mal tiré. 


= Transmission des travaux =

Après d'ultimes vérifications, nous pourrons faire part, au monde entier, du résultat de notre travail. 

Nous commencerons par une synchronisation avec le dépôt communautaire afin de prendre en compte les changements apportés par nos collègues. Ceci nous obligera éventuellement à modifier notre travail tout frais. 


Nous allons commencer par repérer ce qui va constituer notre contribution, puis empaquèterons le différentiel de ces modifications sous forme de ''patch''.

Par principe, et comme fait toute ménagère qui se respecte – on ne mélange pas les produits d'entretien et les produits de bouche – les envois sont constitués selon leur nature. Autrement dit, j'enverrai les corrections de typographie dont j'aurai eu connaissance, séparément de mes travaux de mise à jour. 


== Préparatifs ==

À ce stade, nous avons besoin d'une étiquette ; ainsi le destinataire de nos travaux, à la lecture du « code barre » collé sur l'emballage, pourra remonter la chaîne en cas de problème.

Générons donc un numéro de révision – tu sais, le scrogneugneu après le « ''Translation of GIT committish:'' » – en activant le ''buffer'' VERSION 

 M-x compile
 Compile command: git rev-parse HEAD

 -*- mode: compilation; default-directory: "~/GIT/Traduc/" -*-
 Compilation started at Sat Nov 21 21:32:12

 git rev-parse HEAD
 a96c7e737821ab403455303e198f9110ec45dbb5

 Compilation finished at Sat Nov 21 21:32:48

et prenons bien soin de recopier cette chaîne de 40 caractères dans tous les fichiers que nous avons modifiés ou ajoutés.


== Commissionement ==

Il s'agit en quelque sorte d'établir le bon de livraison. Nous utiliserons deux commandes de git : git-status qui va nous permettre de déterminer quels seront les fichiers concernés, et git-commit validera le commissionnement.


=== Choix des fichiers concernés ===

La commande git-status, appelée grâce au mode git d'emacs, nous présente un tableau de tous les fichiers nouveaux ou mouvementés.


 M-x git-status 


me revoie quelque chose comme :

 Directory:  ~/GIT/Traduc/
 Branch:     lilypond/translation
 Head:       6417526547 - Increase default space between left edge and key sig (only used if no clef present)

      Modified     Documentation/fr/notation/vocal.itely
      Unknown      Documentation/fr/texidocs/simple-lead-sheet.texidoc
      Modified     Documentation/snippets/simple-lead-sheet.ly

Le ''Unknown'' signifie que ce fichier est nouveau et pas encore pris en compte. C'est normal, c'est moi qui l'ai fait !


Je me place après le ''Modified'' et tappe un m pour marquer (u pour ''Unmark'') le curseur descend (tout seul) d'une ligne. Là , je tappe un a pour ''Add'' puisque je veux prendre ce fichier en compte, puis un m pour qu'il fasse partie du même envoi. Par contre, je ne fais rien pour les fichiers de Documentation/snippets/ ; un développeur ou le coordinateur des traductions s'en chargera à l'occasion. 


J'ai donc maintenant :

 Directory:  ~/GIT/Traduc/
 Branch:     lilypond/translation
 Head:       6417526547 - Increase default space between left edge and key sig (only used if no clef present)

* Modified

    Documentation/fr/notation/vocal.itely

* Added

       Documentation/fr/texidocs/simple-lead-sheet.texidoc
      Modified     Documentation/snippets/simple-lead-sheet.ly

Vous noterez que tous les fichiers concernés par l'envoi sont préfixés d'un astérisque (

*

).


Je tappe un c pour ''Commit'', ce qui m'ouvre un ''buffer'' pour entrer l'entête du commit. L'auteur de cet envoi est automatiquement repris d'après le fichier ~/.gitconfig. Si ce commisionnement est fait pour le compte d'un autre traducteur, il me faudra '''impérativement''' le modifier.

La première ligne de cet entête apparaîtra comme titre du commissionnement ; j'insère une ligne vide et mets mes commentaires. Par exemple :

Author: c'est moi

 --- log message follows this line ---
 Doc-fr: vocal.itely review

* master file vocal.itely

* associated texidocs

Une fois que c'est fait, je valide le commissionnement :

 C-c C-c


Le buffer git-status, qui est resté dans le demi-écran supérieur, m'affiche alors :

 Directory:  ~/GIT/Traduc/
 Branch:     lilypond/translation
 Head:       61cb2d5eed - Doc-fr: vocal.itely review

* Uptodate

    Documentation/fr/notation/vocal.itely

* Uptodate

    Documentation/fr/texidocs/simple-lead-sheet.texidoc
      Modified     Documentation/snippets/simple-lead-sheet.ly

La mention

* Uptodate

 indique que la prise en compte est effective.


=== Dernières vérifications ===

Pour éviter les télescopages et placer mes apports en tête de liste, je fais un dernière synchronisation avec le serveur communautaire :

[

address@hidden Lily]$ git pull trans

[

address@hidden Lily]$ cd ../Traduc

[

address@hidden Traduc]$ git fetch

[

address@hidden Traduc]$ git rebase origin


Le cas échéant, les fichiers en conflit seront un peu plus verbeux et feront apparaître un

<<<<

 là où le problème se situe dans le fichier. Ces conflits devront être gérés manuellement, puis

[

address@hidden Traduc]$ git add ''fichier-en-conflit''

[

address@hidden Traduc]$ git rebase --continue


== Transmission des travaux ==

Pour des raisons que je serais incapable d'expliquer, et par expérience, j'active l'autre branche de mon dépôt généraliste : le push est annulé par unez modification non commitée.

[

address@hidden Traduc]$ cd ../Lily

[

address@hidden Lily]$ git checkout master

[

address@hidden Lily]$ cd ../Traduc

[

address@hidden Traduc]$ git push


puis referme le carton à expédier :

address@hidden ~]$ cd ../Lily

address@hidden ~]$ git format-patch origin/lilypond/translation

J'ouvre mon client de messagerie et joint ce xxx-Doc-fr-truc.patch à l'attention de la liste lilypond-user-fr.


= Annexes =
== Les plus d'emacs ==

Petit rappel, et information pour ceux qui n'utilisent pas emacs à longueur de temps :

C-caractère = +caractère

M-caractère = +caractère

Quelques commandes bien pratiques :

C-f moi

: charge fichier moi [file]

C-x C-s

: sauve fichier [save]

C-x s: demande quel fichier sauvegarder

C-w lui

: enregistre sous... lui [write]

M-g g 10

: va à la ligne 10 [goto]

C-w : coupe 

M-w: copie

C-y

: colle [yank]

C-_: annule l'opération précédente (incrémental)

C-s zut: recherche zut à partir du curseur

C-r zut: recherche zut en remontant à partir du curseur

C-x 2: partage la fenêtre en deux

C-x o: bascule d'une fenêtre à l'autre

C-p

: remonte d'une ligne affichée (longueur > l'écran) sinon

C-n

: descend d'une ligne affichée (longueur > l'écran) sinon

C-j: passe à la ligne suivante en respectant l'indentation


D'autres un peu plus évoluées :

M-x repls123321

remplace, Ã  partir du curseur, toutes les occurences de 123 par 321

M-%123321

remplace, Ã  partir du curseur, toutes les occurences de 123 par 321 avec validation individuelle


Et dans un fichier ''Texinfo'' :

C-c s : affiche un tampon contenant le découpage du .*tely

 clic gauche pour ateindre le nœud


Ayant installé le mode auctex pour emacs, il me faut une nouvelle macro pour pouvoir directement obtenir le découpage des fichiers ".*tely" puisque la macro "C-c C-s" a été réaffectée. 

Par ailleurs, j'aime que les fichiers soient traités selon leur typologie, donc j'ai dans mon ~/.emacs :

 ;;;;; JE TRADUIS POUR LILY ;;;;;;;
 ;; associe l'extension .lytex au mode latex/auctex
 (setq auto-mode-alist
       (cons '("\\.lytex$" . latex-mode) auto-mode-alist))
 ;; de même, mode html pour .ihtml
 (setq auto-mode-alist
       (cons '("\\.ihtml$" . html-mode) auto-mode-alist))
 ;; de même, mode texinfo pour .texidoc
 (setq auto-mode-alist
       (cons '("\\.texidoc$" . texinfo-mode) auto-mode-alist))

 ;; ASSIGNE RACOURCI CLAVIER SI AUCTEX INSTALLÉ
 ;; CORRESPONDANT AU C-c C-s DU MODE TEXINFO
 (setq TeX-auto-save t)
 (setq TeX-parse-self t)
 (setq-default TeX-master nil)
 (add-hook 'Texinfo-mode-hook
       '(lambda ()
          (define-key Texinfo-mode-map "\C-cs"
               'texinfo-show-structure)))
 ;;;;; C'EST SYMPA POUR LES AUTRES ;;;;;;; 

== Extras en vrac ==


Quelqu'un m'a envoyé des corrections sous forme de rustine. Je commence par reporter les modifications dans mes propres fichiers :

address@hidden rep]$ git am rustine

(si c'est un patch réalisé avec git)

address@hidden rep]$ git apply rustine

 (dans le cas contraire)

puis commissionne en le gratifiant, soit avec emacs comme vu plus haut, soit en console :

address@hidden rep]$ git commit -a --author="pas moi "

-----

Quelqu'un menvoie un fichier brut qui n'a pas l'encodage utf-8. Il me faut le convertir :

address@hidden rep]$ cd le-dossier

address@hidden dossier]$ iconv -f ISO-8859-15 -t UTF-8 Fichier_Reçu -o Fichier_OK_utf8

Je fais un différentiel avec mon fichier :

address@hidden dossier]$ diff -u FichierDeMonDépôt Fichier_OK_utf8 > fichier.patch

parce que je suis avare de mes yeux