*develop.txt* Pour Vim version 6.2.MANUEL de RÉFÉRENCE VIM - par Bram Moolenaar
Développement de Vim *development*
Ce texte est important pour tous ceux qui désirent s'impliquer dans le
développement ultérieur de Vim.
1. Buts du projet |design-goals|
2. Règles de codage |coding-style|
3. Choix de conception |design-decisions|
4. Hypothèses |design-assumptions|
Voir le fichier "README.txt" dans le répertoire "src" pour un premier aperçu
du code source.
==============================================================================
1. Buts du projet *design-goals*
Ces buts apparaissent (grosso modo) par ordre décroissant d'importance.
NOTE : Quelques-uns de ces points se contredisent. C'est intentionnel : un
équilibre doit être trouvé entre eux.
VIM EST... COMPATIBLE VI *design-compatible*
Tout d'abord, il doit être possible d'utiliser Vim au pied levé en
remplacement de Vi. Quand l'utilisateur le désire, il doit pouvoir utiliser
Vim en mode compatible en remarquant à peine la différence avec le Vi
original.
Restrictions :
- Les bogues identifiés de Vi ne sont pas reproduits dans Vim.
- Il existe différentes versions de Vi. J'utilise la Version 3.7 (6/7/85)
comme référence. Mais le support pour les autres versions est également
inclus si possible. Le Vi issu de POSIX n'est pas tenu pour une source
définitive.
- Vim apporte de nouvelles commandes, auxquelles on ne peut pas demander
d'échouer sous prétexte qu'elles n'existent pas dans Vi.
- Vim inclut de nombreuses fonctionnalités que Vi n'a pas. Revenir de Vim à Vi
posera des problèmes, c'est inévitable.
- Certaines fonctionnalités ne sont presque jamais utilisées (mode Open, envoi
d'un courriel lors d'un plantage, etc.) : elles seront incluses seulement
lorsque quelqu'un trouvera une bonne raison de les inclure, et si cela ne
représente pas trop de travail.
- Pour quelques points, il est opportun de discuter si la compatibilité Vi
doit être maintenue ou non. Celle-ci restera accessible à travers un drapeau
d'option.
VIM EST... AMÉLIORÉ *design-improved*
Les améliorations apportées par Vim doivent en faire un meilleur Vi, sans
qu'il ne devienne un éditeur complètement différent. Les extensions doivent
respecter l'« esprit Vi ».
- Utiliser le clavier autant que possible. La souris nécessite une troisième
main dont nous sommes dépourvus. De nombreux terminaux n'ont pas de souris.
- Lorsque la souris est quand même utilisée, éviter d'avoir à revenir au
clavier. Éviter de mélanger le recours au clavier et à la souris.
- Ajouter des commandes et des options de manière cohérente. Sinon, les
utilisateurs auront du mal à les trouver et à les retenir. Garder à l'esprit
que d'autres commandes et options seront ajoutées par la suite.
- Une fonctionnalité que les utilisateurs ne connaissent pas est une
fonctionnalité inutile. Ne pas ajouter de fonctionnalités obscures, ou du
moins faire clairement ressortir leur existence dans la documentation.
- Minimiser l'usage de Ctrl et des autres modificateurs (ils sont plus
difficiles à taper).
- Il existe de nombreux utilisateurs de Vim novices et inexpérimentés. Leur
faciliter la prise en main de Vim et leur permettre d'apprendre
progressivement avec le temps.
- Il n'y a pas de limitation pour les fonctionnalités qui peuvent être
ajoutées. Leur sélection se fait selon : 1° la demande des utilisateurs,
2° l'effort nécessaire au développement et 3° la personne responsable du
développement.
VIM EST... MULTI-PLATES-FORMES *design-multi-platform*
Vim essaie d'aider le plus grand nombre d'utilisateurs possible sur le plus
grand nombre de plates-formes possible.
- Supporter le plus grand nombre de types de terminaux possible. Les besoins
minimaux sont le positionnement du curseur et l'effacement de l'écran. Les
commandes doivent utiliser uniquement les touches dont disposent la plupart
des terminaux. Supporter toutes les touches du clavier pour les mappages.
- Supporter le plus grand nombre de plates-formes possible. Pour cela, il faut
qu'il se trouve une personne désirant assurer le développement de Vim sur
chaque plate-forme, et sans « salir » le code.
- Supporter le plus grand nombre de compilateurs et bibliothèques possible.
Tout le monde n'est pas capable ou autorisé à installer un autre compilateur
ou une autre bibliothèque IHM graphique.
- De nombreuses personnes passent d'une plate-forme à une autre, et de la
version IHM graphique au terminal. Les fonctionnalités doivent être
présentes dans toutes les versions, ou au moins dans le plus grand nombre
possible avec un effort raisonnable. Essayer d'éviter que les utilisateurs
ne doivent changer de plate-forme pour accomplir leur travail efficacement.
- Si une fonctionnalité n'est pas possible sur certaines plates-formes, ou
uniquement possible sur une plate-forme, cela ne signifie pas qu'elle ne
peut pas être incluse. (Ce point contredit intentionnellement le précédent :
un juste milieu doit être trouvé.)
VIM EST... BIEN DOCUMENTÉ *design-documented*
- Une fonctionnalité qui n'est pas documentée est une fonctionnalité inutile.
Une rustine pour une nouvelle fonctionnalité doit inclure sa documentation.
- La documentation doit être compréhensible et intelligible. L'utilisation
d'exemples est recommandée.
- Le texte ne doit pas être plus long qu'il n'est nécessaire. Plus une
documentation est courte, plus un élément sera facile à trouver.
VIM EST... RAPIDE ET LÉGER *design-speed-size*
Vim ne doit pas être trop lourd pour les ressources du système. Il doit rester
performant en vitesse et peu gourmand en mémoire.
- Chaque année, les ordinateurs deviennent de plus en plus gros et rapides.
Vim peut également grossir, mais pas plus vite que les ordinateurs. Il doit
rester utilisable sur les anciens systèmes.
- La plupart du temps, Vim est lancé depuis un shell. Le temps de démarrage
doit être court.
- Les commandes doivent être performantes. Le temps qu'elles consomment doit
être aussi court que possible. Les commandes utiles peuvent prendre un peu
plus de temps.
- Ne pas oublier que certaines personnes utilisent Vim à travers une connexion
lente. Minimiser les délais de communication.
- Les éléments qui font croître la taille de façon significative et qui ne
sont pas utilisés par le plus grand nombre doivent être des fonctionnalités
qu'on peut choisir de désactiver.
- Vim n'est qu'une composante parmi tant d'autres. Il ne doit pas se
transformer en une application massive, mais doit pouvoir coopérer avec
d'autres programmes.
VIM EST... MAINTENABLE *design-maintain*
- Le code source ne doit pas devenir une jungle. Il doit être fiable.
- Utiliser la même mise en forme dans tous les fichiers pour en faciliter la
lecture |coding-style|.
- Utiliser les commentaires de façon constructive !
- Le portage vers une autre plate-forme doit être facile, sans avoir à changer
trop de code indépendant des plates-formes.
- Utiliser l'esprit orienté-objet : placer les données et le code ensemble.
Minimiser le report de connaissances vers d'autres parties du code.
VIM EST... FLEXIBLE *design-flexible*
Vim doit permettre aux utilisateurs de travailler selon leurs méthodes
préférées, plutôt que de les forcer à un schéma particulier. Cela vaut pour
les éléments qui ont un impact important (p. ex., l'option 'compatible') comme
pour les détails. Les valeurs par défaut sont soigneusement choisies afin que
la plupart des utilisateurs apprécient Vim tel qu'il est. Les commandes et les
options peuvent être utilisées pour ajuster Vim aux désirs de l'utilisateur et
à son environnement.
VIM N'EST PAS... *design-not*
- Vim n'est pas un shell ni un système d'exploitation. On ne pourra pas lancer
de shell dans Vim ou l'utiliser pour contrôler un débogueur. Ce sera plutôt
l'inverse : utiliser Vim comme composante d'un shell ou d'un EDI.
D'une façon plus satirique : "Unlike Emacs, Vim does not attempt to include
everything but the kitchen sink, but some people say that you can clean one
with it. ;-)" [N.D.T. : Traduction libre, en gardant à l'esprit que Vim est
aussi le nom d'un produit décapant dans les pays anglo-saxons :
« Contrairement à Emacs, Vim n'est pas une cuisine aménagée tout confort,
mais certains affirment qu'ils ont pu briquer la leur avec ;-) ».] XXX
- Vim n'est pas un éditeur à l'interface graphique avancée qui soigne son
apparence au détriment de sa consistance sur toutes les plates-formes. Mais
des fonctionnalités d'interface graphique bien conçues sont les bienvenues.
==============================================================================
2. Règles de codage *coding-style*
Vous trouverez ici les règles à suivre quand vous voudrez modifier le code
source de Vim. Vous êtes prié de les respecter, afin que les sources restent
lisibles et maintenables.
Cette liste n'est pas complète. Jetez un coup d'oeil au code source pour plus
d'exemples.
[N.D.T. : Vim est un projet international et son développement s'effectue en
anglais, tant pour la documentation que pour le code. Veuillez ne pas perdre
ce point de vue lors de la lecture de cette section.]
FAIRE DES CHANGEMENTS *style-changes*
Voici les étapes élémentaires pour apporter des changements au code :
1° Ajuster la documentation. Faire cela en premier vous permet de garder à
l'esprit l'attente de l'utilisateur ;
2° Effectuer la modification du code source ;
3° Vérifier dans "../doc/todo.txt" si le changement concerne un des points
listés ;
4° Créer une rustine avec `diff -c` pour le code et la documentation
modifiés ;
5° Écrire une petite note sur ce qui a changé et l'inclure dans la rustine.
UTILISATION DES FONCTIONS COMMUNES *style-functions*
Certaines fonctions d'usage commun possèdent une version spéciale pour Vim.
Utilisez toujours les versions pour Vim, elles ont été introduites avec une
bonne raison.
NOM NORMAL NOM POUR VIM DIFFÉRENCE DE LA VERSION VIM
free() vim_free() Vérifie si l'argument est NULL
malloc() alloc() Tient compte de la mémoire restante
malloc() lalloc() Comme alloc(), mais avec un argument long
strcpy() STRCPY() Transtype char_u * avec (char *)
strchr() vim_strchr() Accepte les caractères spéciaux
strrchr() vim_strrchr() Accepte les caractères spéciaux
isspace() vim_isspace() Supporte les caractères supérieurs à 128
iswhite() vim_iswhite() TRUE uniquement pour espace et tabulation
memcpy() vim_memmove() Gère les recouvrements lors des copies
bcopy() vim_memmove() Gère les recouvrements lors des copies
memset() vim_memset() Identique sur tous les systèmes
NOMS *style-names*
Les noms de fonctions ne doivent pas faire plus de 31 caractères de long (à
cause de VMS).
N'utilisez pas "delete" comme nom de variable, C++ n'aime pas ça.
En raison de l'impératif pour Vim de fonctionner sur le plus grand nombre de
plates-formes possible, il faut éviter d'utiliser des noms qui sont déjà
définis par les systèmes. Voici une liste de noms qui sont bien connus pour
poser des problèmes (les noms sont donnés comme des motifs d'expressions
rationnelles).
is.*() POSIX, ctype.h
to.*() POSIX, ctype.h
d_.* POSIX, dirent.h
l_.* POSIX, fcntl.h
gr_.* POSIX, grp.h
pw_.* POSIX, pwd.h
sa_.* POSIX, signal.h
mem.* POSIX, string.h
str.* POSIX, string.h
wcs.* POSIX, string.h
st_.* POSIX, stat.h
tms_.* POSIX, times.h
tm_.* POSIX, time.h
c_.* POSIX, termios.h
MAX.* POSIX, limits.h
__.* POSIX, system
_[A-Z].* POSIX, system
E[A-Z0-9]* POSIX, errno.h
*_t POSIX, pour les définitions de types ; utilisez *_T à la place
wait ne pas utiliser comme argument d'une fonction, en conflit
avec types.h
index masque la déclaration globale
time masque la déclaration globale
new mot-clé réservé pour C++
try Borland C++ n'aime pas qu'il soit utilisé comme une variable
basename() fonction de chaîne GNU
dirname() fonction de chaîne GNU
get_env_value() fonction système Linux
DIVERS *style-various*
Les noms déclarés avec "typedef" doivent se terminer par "_t" :
typdef int some_t;
Les noms définis avec "#define" doivent être en majuscules :
#define SOME_THING
Les fonctionnalités débutent toujours par "FEAT_" :
#define FEAT_FOO
N'utilisez pas '\"', certains compilateurs ne le supportent pas. '"' marche
bien.
N'utilisez pas :
#if HAVE_SOME
Certains compilateurs ne le supportent pas et se plaignent que "HAVE_SOME"
n'est pas défini. Utilisez
#ifdef HAVE_SOME
ou
#if defined(HAVE_SOME)
STYLE *style-examples*
Règle générale : une seule instruction par ligne.
Mauvais : if (cond) a = 1;
Bon : if (cond)
a = 1;
Mauvais : while (cond);
Bon : while (cond)
;
Mauvais : do a = 1; while (cond);
Bon : do
a = 1;
while (cond);
Les fonctions commencent par :
Mauvais : int function_name(int arg1, int arg2)
Bon : /*
* Explanation of what this function is used for.
*
* Return value explanation.
*/
int
function_name(arg1, arg2)
int arg1; /* short comment about arg1 */
int arg2; /* short comment about arg2 */
{
int local; /* comment about local */
local = arg1 * arg2;
NOTE : N'utilisez pas des déclarations de fonctions de style ANSI. Certaines
personnes utilisent encore un compilateur qui ne le supporte pas.
ESPACES ET PONCTUATION *style-spaces*
Pas d'espace entre un nom de fonction et la parenthèse :
Mauvais : func (arg);
Bon : func(arg);
Entrez un espace après if, while, switch, etc. :
Mauvais : if(arg) for(;;)
Bon : if (arg) for (;;)
Entrez un espace après une virgule et un point-virgule :
Mauvais : func(arg1,arg2); for (i = 0;i < 2;++i)
Bon : func(arg1, arg2); for (i = 0; i < 2; ++i)
Entrez un espace avant et après '=', '+', '/', etc. :
Mauvais : var=a*5;
Bon : var = a * 5;
En géneral : utilisez des lignes vides pour regrouper des lignes de code
ensemble. Placez un commentaire juste au-dessus du groupe de lignes. Il est
ainsi plus facile de voir rapidement ce qui est fait.
Bon : /* Prepare for building the table. */
get_first_item();
table_idx = 0;
/* Build the table. */
while (has_item())
table[table_idx++] = next_item();
/* Finish up. */
cleanup_items();
generate_hash(table);
==============================================================================
3. Choix de conception *design-decisions*
REPLIAGE
Plusieurs états de repliage devraient être possibles pour le même tampon. Par
exemple, avoir une fenêtre qui montre le texte avec un corps de fonction
replié, et une autre qui montre le corps de fonction.
Le repliage est une façon d'afficher le texte : il devrait donc changer le
texte lui-même. C'est pour cela que le repliage a été développé comme un
filtre entre le texte enregistré dans un tampon (les lignes de tampon) et le
texte affiché dans une fenêtre (les lignes logiques).
DIFFÉRENTS TERMES POUR « FENÊTRE »
Le mot « fenêtre » est souvent utilisé pour plusieurs choses différentes : une
fenêtre à l'écran, une fenêtre xterm ou une fenêtre dans Vim pour visualiser
un tampon...
Afin d'éviter les confusions, certains éléments qui sont parfois appelés
« fenêtre » ont reçu un autre nom. Voici un sommaire de ces éléments :
écran Toute la surface d'affichage. Pour l'IHM graphique, cela fait
quelque chose comme 1024 × 768 pixels. Le shell Vim peut
utiliser l'écran tout entier ou en partie. ["screen"]
shell L'application Vim. Elle peut occuper tout l'écran (p. ex.,
quand elle s'exécute dans une console) ou une partie seulement
(xterm ou IHM graphique).
fenêtre Une vue d'un tampon. Il peut y avoir plusieurs fenêtres dans
Vim. Avec la ligne de commande, la barre de menus, la barre
d'outils, etc., elles composent le shell. ["window"]
À suivre...
==============================================================================
4. Hypothèses *design-assumptions*
Taille des variables :
char 8 bits signé
char_u 8 bits non signé
int 16, 32 ou 64 bits signé
unsigned 16, 32 ou 64 bits non signé
long 32 ou 64 bits signé, peut contenir un pointeur
vim:tw=78:ts=8:ft=help:norl: