Mongueurs de Perl :: Articles :: Relire un article

Après nous avoir rejoint, vous êtes invité à relire les articles dont la rédaction est finie.

Un article est indiqué comme étant à relire sur la page du planning du groupe de travail et vous avez un peu de temps : vous avez envie de le relire, c'est une bonne idée ! Mais comment faire ? Voici des pistes pour une collaboration fructueuse.

Relire

Avant tout, il vous faut accéder au fichier de l'article : Subversion est notre ami. Vous trouverez un peu d'aide sur l'usage de ce logiciel. Un petit svn update pour s'assurer d'avoir la dernière version et c'est parti.

Pour relire cet article, lancez votre éditeur favori sur le fichier source de l'article. Veillez à ce que ce logiciel n'ajoute pas de caractères qui lui sont propres ; utilisez pour cela un éditeur de texte (différent d'un traitement de texte), tel que vi, emacs, xemacs, gedit, kedit (liste non exhaustive), mais pas avec OpenOffice.org ni Word ... Le but étant que, si vous n'avez qu'une ligne à modifier, qu'une seule ligne soit réellement modifiée ...

Pour faciliter une première relecture sans modification, vous pouvez aussi utiliser un outil comme podviewer, ou un autre outil effectuant un formatage de l'article : pod2txt, pod2latex...

Modification

Au fur et à mesure de la relecture, vous pouvez corriger les fautes d'orthographe ou de typo directement, pas besoin de mettre plus de formes pour ce genre de corrections.

A contrario, si la correction que vous souhaitez apporter est susceptible d'être soumise à débat, veillez à ajouter un commentaire contenant votre suggestion de modification. C'est l'auteur qui décidera de prendre ou non votre remarque en compte. Il en est de même pour une suggestion entraînant de grosses modifications de l'article.

La façon d'insérer un commentaire dépend du format de fichier de l'article sur lequel vous travaillez :

• En POD, vous pouvez insérer des lignes comme ceci (penser à passer une ligne avant et apres) :
  
  ...article relu...
  
  =for comment ### FIXME Votre Nom
  Votre commentaire...
  
  ...article relu...
  
  ou bien comme ceci :
  
  ...article relu...
  
  =cut
  
  # FIXME VotrePrénom VotreNom
  # Ceci est mon commentaire
  # bla bla bla ...
  
  =pod
  
  ...article relu...
  

Cette dernière forme a l'avantage d'être plus lisible. Évitez cependant de mettre vos commentaires au milieu d'un paragraphe, le commentaire ainsi inséré ayant tendance à séparer en deux parties le paragraphe originel ; que ce soit dans le source ou dans la version HTML ou texte après transformation du POD.

• En XML/DocBook, faites de la sorte :
  
  ...article relu...
  <!-- FIXME VotrePrénom VotreNom
  Ceci est mon commentaire
  bla bla bla ...
  -->
  ...article relu...
  

Le label FIXME est prévu pour aider les auteurs à retrouver les endroits où quelqu'un signale un manque ou une mauvaise formulation.

Envoi

Une fois le fichier totalement relu, sauvegardez-le et lancez la commande svn commit ; reportez-vous à la page d'aide de Subversion pour savoir ce que fait cette commande et les informations à saisir.

Ayez à l'esprit que toutes les modifications sont envoyées par mail sous forme d'un diff (cf man diff), donc que toute modification d'un seul caractère sera susceptible d'être reprise par l'auteur. N'hésitez donc pas à faire de nombreuses modifications constructives.

Quelques mots pour conclure : veillez à respecter l'esprit de l'article insufflé par l'auteur, votre relecture est censée l'aider dans son travail ; il en reste l'auteur, vous êtes un gentil relecteur ...