*rq.txt*	Aide à la relecture

Pour obtenir des informations sur l'installation de ce fichier, tapez >
	:help add-local-help
dans Vim.

Pour Vim version 6.2.  Dernière modification : 05 mar 2005


		 MANUEL du TRADUCTEUR VIM - par David Blanchet


Outil de relecture			*relecture* *relecteur* *rq.vim*

Ce fichier précise le fonctionnement des outils utilisés pour la relecture de
la traduction des manuels de Vim.

1. Introduction				|rq-intro|
2. Installation du greffon 		|rq-installation|
3. Format du fichier de remarques	|rq-format-fichier|
4. Format des remarques			|rq-format-remarques|
5. Utilisation du greffon		|rq-greffon|
6. Exemple				|rq-exemple|

==============================================================================
1. Introduction						*rq-intro*

Cet outil a été mis en place pour formaliser le travail des relecteurs.
Initialement conçu pour les relectures des fichiers traduits lors de la
traduction française des manuels de Vim, il peut également convenir à d'autres
travaux similaires.

Pour que traducteur et relecteur passent le moins de temps possible à
comprendre ce que l'autre a voulu signifier, un certain nombre de structures
et de formalismes ont été mis en place.

L'objectif de l'outil est de simplifier la tâche de relecture, tant du point
de vue du relecteur, que de celui du traducteur qui reprend son fichier
traduit. Pour cela, l'outil de relecture s'attache à 3 tâches principales :

- La rédaction des remarques, en créant les champs et en les remplissant dans
  la mesure du possible (notamment le numéro de ligne et leur contenu) et en y
  mettant un peu d'ordre, voir |rq-format-remarques|.

- La navigation dans les remarques, celle-ci pouvant se faire depuis le
  fichier relu ou depuis les remarques (un peu à l'image de Quickfix, en
  mettant à jour les positions des curseurs dans les différentes fenêtres),
  voir |rq-greffon|.

- La prise en compte des remarques, en ajustant les décalages causés par la
  suppression ou l'ajout de caractères dans le fichier relu, ainsi que la
  rédaction de réponses/commentaires dans le fichier de remarques si débat il
  y a (et il y en a souvent !), voir |rq-greffon|.

L'outil comprend un greffon permettant des traitements entre le fichiers en
cours de relecture et un fichier contenant les remarques et les commentaires
formulés par le relecteur. Un fichier de syntaxe permet la coloration du
fichier de remarques.

==============================================================================
2. Installation du greffon 				*rq-installation*

Voici les étapes nécessaires pour installer le greffon. Il s'agit d'un greffon
de type de fichier (*.rq) :

- Copiez le fichier "rq_greffon.vim" dans le répertoire approprié. Mettez-le
  par exemple dans le répertoire "~/.vim/ftplugin". Pour plus de détails sur
  l'emplacement des greffons de type de fichiers, voir |ftplugin-name|.

- Copiez le fichier de coloration syntaxique "rq_syntaxe.vim" dans le
  répertoire "~/.vim/syntax" et renommez-le "rq.vim".

- Copiez le fichier de coloration syntaxique "rq_indent.vim" dans le
  répertoire "~/.vim/indent" et renommez-le "rq.vim".

- Ajoutez ces deux lignes dans votre vimrc et METTEZ-LES À JOUR avec vos
  informations personnelles : >
  
	let Rq_Auteur = "Votre Nom <VotreAdresse@Electronique>" 
	let Rq_Initiales = "VosInitiales" 

< Par exemple : 
	let Rq_Auteur = "David Blanchet <david DOT blanchet AT free DOT fr>"
	let Rq_Initiales = "DB"
  Si vous omettez cette étape, ces informations vous seront demandées à chaque
  ouverture de fichier de remarques.	

- Ajoutez ces quelques lignes dans votre ~/.vim/filetype.vim : >

    if has("autocmd")
	augroup filetypedetect
	au BufRead,BufNewfile *.rq? setf rq
	au BufNewfile *.rq? if exists("*CreerEntete")|call CreerEntete()|endif
	augroup END
    endif

< Ce bloc permet de charger le greffon lors de l'édition ou de la création
  d'un fichier de remarques. Si c'est un nouveau fichier, l'en-tête est généré.

Vous pouvez également (mais ce n'est pas obligatoire) ajouter un mappage pour
simplifier la création des fichiers de remarques. Pour cela, ajoutez cette
ligne dans votre vimrc : >

	nmap <F2> :split %.rq<CR>

Remplacez <F2> par la touche qui vous convient. Ce mappage crée un fichier de
remarques pour le tampon en cours d'édition. Si un fichier de remarques existe
déjà dans le même répertoire, il est ouvert.

==============================================================================
3. Format du fichier de remarques			*rq-format-fichier*

La suite de ce manuel donne les interactions entre deux fichiers. Le premier
est le fichier relu : c'est la production du traducteur à partir duquel le
relecteur formule ses remarques. Le second est le fichier de remarques : il
contient l'ensemble des remarques du relecteur à propos du fichier relu.

Le fichier de remarques respecte un format particulier qui, d'une part, permet
au greffon de fonctionner, et d'autre part fixe la forme des informations
pour ceux qui le produisent et ceux qui vont le lire. Il comporte 2 types de
contraintes. Le premier porte sur son nom et le deuxième sur son contenu.


NOM DU FICHIER

Le nom du fichier de remarques est construit à partir du nom du fichier relu,
auquel est ajouté l'extension « .rq ». Ce qui donne, pour le fichier relu

	help.txt ~

le fichier de remarques

	help.txt.rq ~

Actuellement, le greffon utilise cette convention pour faire le lien entre le
fichier relu et le fichier de remarques.


CONTENU DU FICHIER

Le fichier est constitué d'un en-tête puis d'une série de remarques. Cette
section expose seulement l'en-tête du fichier. Pour le format des remarques,
voir |rq-format-remarques|.

L'en-tête contient différentes informations. Prenons l'exemple suivant (le
fichier de remarques ne comporte pas de renfoncement particulier, si vous
utilisez l'exemple ci-dessous, veillez à supprimer les tabulations au début de
chaque ligne) : >

	# Traduction de la documentation de VIM.       vim:tw=78:ts=8:ft=rq:
	
	# Remarques de relecture
	# Arthur <arthur@tagada.net>
	# Dernière modification : 03 mar 2003

	# Réponses PM
	# Paul <paul@ploumploum.net>
	# Dernière modification : 05 mar 2003

	fichier : intro.txt ################################################

Voici quelques explications sur les différents éléments présents :

- La ligne de mode permet à Vim de charger le greffon et le fichier de syntaxe
  correspondant. Les détails du greffon sont donnés dans |rq-greffon|.

- Préciser l'auteur des dernières modifications ainsi que leur date permet au
  destinataire du fichier de savoir d'où les remarques proviennent et de
  consulter leur auteur le cas échéant ; de plus, cela permet de savoir où en
  est le fil d'une discussion dans le fichier de remarques. Le greffon permet
  la mise à jour de la dernière date de modification. Pour cela, le champ doit
  respecter cette orthographe (la casse est indifférente).
  La personne qui modifie le fichier est invitée à ajouter ces informations au
  fichier avant de le transmettre. Voir |rq-identite|.

- Le fichier concerné par les remarques de relecture. Ce champ est nécessaire
  au bon fonctionnement du greffon.

À la suite de cet en-tête se trouvent les remarques.

==============================================================================
4. Format des remarques					*rq-format-remarques*

Une remarque est repérée par le numéro de la ligne qu'elle concerne dans le
fichier relu. Elle contient un commentaire du relecteur, la copie de la ligne
concernée, une deuxième copie avec une proposition (ou illustration du propos
de la remarque) par le relecteur. Une remarque peut éventuellement concerner
plusieurs lignes. Toutes ces informations sont données dans des champs.

Une remarque contient également un champ « Statut », indiquant si le
traducteur l'a prise en compte ou non. Des champs « Réponse » peuvent être
ajoutés si traducteur et relecteur ont besoin d'ajouter des commentaires (Par
exemple la raison du rejet d'une remarque, ou un problème récurrent de
traduction).

Le champ « Statut » contient généralement : « fait », « rejeté » ou « en
souffrance ».

Voici à quoi ressemble une remarque : >

	Ligne : 12
	Remarque : Coquille.
	-1. Intrduction				|intro|
	+1. Introduction			|intro|
	Statut : fait
	Réponse DB : On ne devrait jamais traduire passé une heure du matin.

L'orthographe précise des différents champs est importante, car le greffon les
génère et les utilise. 

La ligne incriminée est copiée 2 fois. La première copie est précédée d'un
'-' et sert de ligne de contexte pour le lecteur. Elle ne doit pas être
modifiée. La deuxième est précédée d'un '+'. Le relecteur peut (idéalement,
doit) la modifier pour illustrer l'objet de la remarque.

Pour l'agrément de lecture, la coloration syntaxique met en évidence les
principaux éléments de la remarque. Pour le bon fonctionnement du greffon,
comme pour le confort du lecteur, chaque remarque est séparée par une ligne
vide.

Pour que le traducteur qui reçoit les remarques du relecteur puisse les
prendre simplement en compte, les remarques sont ordonnées selon leur numéro
de ligne.

==============================================================================
5. Utilisation du greffon				*rq-greffon*

Le greffon permet d'automatiser la prise en compte des différentes contraintes
évoquées dans les sections précédentes.

Le greffon travaille avec le fichier relu et le fichier de remarques
simultanément. Il tente d'offrir des fonctionnalités voisines de celles que
|Quickfix| offre pour le code.

Les différentes commandes supposent que les fichiers relu et de remarques
sont tous les deux ouverts dans le même Vim et que chacun d'entre eux apparaît
dans une fenêtre.


GÉNÉRATION DES REMARQUES
							*rq-generer*
Le greffon propose deux manières de générer des remarques.

Depuis le fichier de remarques :

,R		Génère un squelette de remarque vide sous le curseur. Cette
		commande n'est disponible que dans le fichier de remarques.
		Le curseur est amené après le champ « Remarque : » ; et Vim
		passe en mode Insertion.

Depuis le fichier en cours de relecture :

{Visuel},r  ou
[quant],r	Génère un squelette de remarque depuis la ligne courante. Si
		[quant] est spécifié, utilise [quant] lignes à partir de la
		ligne courante. Si invoqué depuis une zone Visuel, utilise les
		lignes de cette zone.
		
		La remarque est insérée au "bon" endroit, c'est-à-dire après
		les remarques concernant des lignes précédentes et avant des
		remarques concernant des lignes ultérieures.
		
		Par exemple, pour générer une remarque sur les 2 lignes que
		vous êtes en train de lire, amenez-y le curseur et faites : >
			2,r

<		Ce qui donne : >

	Ligne : 263-264
	Remarque : 
	-Par exemple, pour générer une remarque sur les 2 lignes que
	-vous êtes en train de lire, amenez-y le curseur et faites : 
	+Par exemple, pour générer une remarque sur les 2 lignes que
	+vous êtes en train de lire, amenez-y le curseur et faites : 
	Statut : 

<		Le curseur est amené après le champ « Remarque : » ; et Vim
		passe en mode Insertion. Vous pouvez alors préciser l'objet de
		votre remarque et modifier les lignes précédées d'un '+'.


NAVIGUER DANS LES REMARQUES
							*rq-naviguer*
,s		Depuis le fichier de remarques : saute dans le fichier relu à
		la ligne de la remarque actuellement sous le curseur.
		Depuis le fichier relu : saute dans le fichier de remarques et
		amène le curseur au prochain champ « Statut ».

Lors de la prise en compte des remarques, le fichier relu est modifié. Les
corrections apportées entrainent parfois des lignes plus longues ou au
contraire plus courtes. Pour que les commandes de navigation (",s" et les
commandes suivantes) sautent à la bonne ligne, le greffon effectue une
recherche en se basant sur les lignes de contexte de la remarque concernée.

Les commandes suivantes mettent l'affichage à jour dans le fichier de
remarques et dans le fichier relu.

,n 		Saute à l'emplacement de la remarque suivante.

,p		Saute à l'emplacement de la remarque précédente.

,f 		Saute à la première remarque.

,l 		Saute à la dernière remarque.

Les commandes suivantes sont similaires aux précédentes, mais elles n'opèrent
que sur les remarques qui restent à traiter (c.-à-d. les remarques dont le
statut est vide ou « en souffrance »).

,N		Comme ",n", pour une remarque à traiter.

,P		Comme ",p", pour une remarque à traiter.

,F		Comme ",f", pour une remarque à traiter.

,L		Comme ",l", pour une remarque à traiter.


PRENDRE EN COMPTE UNE REMARQUE AUTOMATIQUEMENT
							*rq-remplacer*
Certaines remarques demandent au traducteur de reprendre très attentivement
une partie des différents éléments proposés par le relecteur. Cette prise en
compte est manuelle et inévitablement réfléchie. En revanche, il arrive
parfois que certaines remarques ne souffrent aucune discussion (par exemple
les coquilles). Ces remarques ne nécessitent aucune réflexion particulière
sinon assurer le minimum pour leur intégration au milieu du texte.

Le greffon propose une commande pour reporter automatiquement la proposition
du traducteur dans le fichier relu. Pour cela, utilisez la commande suivante :

,x		Remplace les lignes du fichier relu par la proposition du
		relecteur.
		NOTE : Cette commande utilise la commande ",s" pour trouver
		les lignes à remplacer. Par conséquent, elle est capable de
		trouver les lignes même si le fichier a subi quelques
		modifications. Toutefois, des modifications trop importantes
		peuvent faire échouer la recherche. Dans ce cas, il vous
		faudra reporter les modifications à la main.

L'efficacité de cette commande dépend beaucoup du soin apporté à la rédaction
de la remarque. Si vous utilisez cette commande, assurez-vous toujours que le
remplacement des lignes s'est bien déroulé comme prévu. Vérifiez également
qu'elles s'intègrent avec fluidité (de format comme de style) au milieu des
lignes qui les entourent.

NOTE : L'aspect automatique bien plaisant de cette commande ne doit pas vous
épargner une relecture consciencieuse de ce qui est écrit. J'insiste.


COMMENTER LES REMARQUES
					*rq-commentaires* *rq-reponses*
Les remarques peuvent être commentées par le traducteur ou par le relecteur.
Pour ajouter un commentaire, utilisez la commande suivante :

,a		Ajoute un commentaire à la fin de la remarque sur laquelle se
		trouve le curseur.

Pour lire les derniers commentaires du correspondant, utilisez les commandes
suivantes :

,j		Saute au commentaire suivant du correspondant.

,k		Saute au commentaire précédent du correspondant.

Ces commandes prennent en compte l'enchaînement des commentaires du traducteur
et du relecteur et ne sautent qu'aux commentaires nouvellement formulés. Par
exemple, si un fichier de remarques a déjà fait plusieurs allers-retours entre
le relecteur et le traducteur, la navigation dans les commentaires ne
concernera que ceux qui ont été rédigés lors du dernier aller-retour.

							*rq-identite*
Pour conserver de manière précise l'enchaînement des commentaires, chaque
utilisateur doit préciser son adresse électronique (qui figurera dans
l'en-tête du fichier de remarque) et ses initiales (qui figureront dans les
réponses aux remarques). Le respect des instructions d'installation du greffon
permet de personnaliser votre production une bonne fois pour toutes. Si ces
informations ne sont pas précisées dans votre vimrc (voir |rq-installation|),
elles seront demandées lors du chargement de chaque tampon.


AUTRES COMMANDES

							*rq-statistiques*
,g		Insère des statistiques concernant la prise en compte des
		remarques par le traducteur. Si des statistiques sont déjà
		présentes, elles sont mises à jour.

							*rq-nouveau*
,e		Crée l'entête du fichier de remarques. Utile pour générer un
		nouveau fichier de remarques. Voici un exemple de marche à
		suivre :
		- Créer un nouveau fichier dont le nom se termine par ".rq",
		  par exemple : >
		  	:e starting.txt.rq
<		- Préciser à Vim le type de fichier concerné : >
			:set ft=rq
<		  Le greffon se plaint alors que l'entête du fichier n'est pas
		  valide et suggère d'en créer un.
		- Générer l'entête avec la commande ,e.
		NOTE : la commande ne fonctionne que si le tampon courant a
		un nom se terminant par « .rq ».
		NOTE : le greffon refuse d'insérer un entête si le tampon
		n'est pas vide, pour assurer la cohérence des informations
		entre l'entête et le reste du fichier.
		NOTE : voir l'installation du greffon au sujet de la
		création du fichier de remarques |rq-installation|, en
		particulier la fin de la section.
		
,w		Enregistre le fichier sans tenir compte des en-têtes. Cette
		commande permet d'enregistrer les données malgré un format
		erroné. Son utilisation régulière est déconseillée et devrait
		être réservée aux situations exceptionnelles, telles que la
		récupération de données ou le débogage.

==============================================================================
6. Exemple						*rq-exemple*

Voici un extrait du fichier "help.txt.rq", contenant des remarques issues de
la relecture de la traduction du fichier "help.txt".


# Traduction de la documentation de VIM.	    vim:tw=78:ts=8:ft=rq:

# Remarques de relecture :
# David Blanchet <david.blanchet@free.fr>
# Dernière modif : 02 fév 2003

# Réponses FV :
# Fabien Vayssière <fabien.vayssiere@laposte.net>
# Dernière modification : 05 fév 2003

# Réponses DB :
# David Blanchet <david.blanchet@free.fr>
# Dernière modification : 10 fév 2003

# Réponses bis FV :
# Fabien Vayssière <fabien.vayssiere@laposte.net>
# Dernière modification : 02 mar 2003

# Réponses bis DB :
# David Blanchet <david.blanchet@free.fr>
# Dernière modification : 11 mars 2003


fichier : help.txt #######################################################

[...]

Ligne : 16
Remarque : mettre un verbe au lieu d'un nom
-		       Double-clic gauche sur un marqueur entre deux |bars|. 
+		       Double-cliquer gauche sur un marqueur entre deux |bars|. 
Statut : fait

Ligne : 22
Remarque : pertinence de la traduction (source : DHO, Dico Hachette-Oxford)
-		       On peut également spécifier un contexte d'utilisation :
+		       On peut également préciser un contexte d'utilisation :
Statut : fait

Ligne : 30
Remarque : la commande est 'vim' sans majuscule. Même remarque pour la version
anglaise !
-		         argument de la commande Vim      -      :help -r
+		         argument de la commande vim      -      :help -r
Statut : rejeté
Réponse FV : Effectivement, c'est quelque chose qui m'a fait sourciller au
	début. Mais bon, il faut se rendre compte que TOUTES les occurences
	(ou presque) de la chaîne « vim » dans la doc sont écrites ainsi : «
	Vim » (avec majuscule) -- nom de commande ou pas. Je ne fais que
	suivre cette usage. La confusion n'est d'ailleurs pas vraiment
	possible.

Ligne : 43
Remarque : alternative perso de la traduction.
-|tutor|		Un cours d'entraînement de 30 minutes pour les débutants
+|tutor|		Un tutoriel de 30 minutes pour les débutants
Statut : fait
Réponse FV : C'était ma première intention. Et puis j'ai mené des recherches
	sans fin sur le terme « tutoriel », et pour savoir si oui ou non il
	était plus correct d'utiliser « didacticiel ». Mon dictionnaire est
	sur ce point à côté de la plaque, qui mentionne « logiciel à usage
	éducatif » pour « didacticiel ». Et rien pour « tutoriel ». Il semble
	que le meilleur usage soit « didacticiel » (après tout, « tutoriel »
	est un anglicisme). Un arbitrage sur ce dilemne ?
Réponse DB : Mon vieux Larousse dit qu'un didacticiel est « un logiciel
	spécialement conçu pour l'enseignement assisté par ordinateur ». Mais,
	il date carrément. Avant d'avoir des "compagnons" dans tous les sens,
	certains logiciels Windows proposait effectivement des « didacticiels ».
	En ce qui concerne l'usage de la langue, « tutoriel » me paraît plus
	actuel et par conséquent plus parlant. Académiquement, « didacticiel »
	semble plus correct. J'ai tendance à préférer « tutoriel ».

[...]

 vim:tw=78:ts=8:ft=help:norl: