Re: règle pour écrire les "usage: ..."

Le 13/07/2022 21:36, Thomas a écrit :

Cela dit, le message « Unexpected switch -v » est inapproprié. Selon
que ta syntaxe accepte ou non plus d'un fichier, ce sera soit :
 File not found '-v' (sauf bien sûr si le fichier -v existe)
soit :
 No more than one file! (gui_file -v)

 
j'ai tendance à penser qu'en l'absence de "--", tout argument commençant
par "-" est une option, et que, sorties de la zone prévue pour elles,
elles sont mal positionnées.

Pour fixer le contexte, je précise que je ne connais pas le monde Ada,
mais que je n'ai pas non plus une connaissance théorique des normes
Posix. Simplement je travaille sur des machines Unix depuis près de
35 ans, ce qui me donne une habitude « pratique » de la plupart des
commandes. Cette habitude fait que j'ai certaines attentes quant au
comportement lors de la lecture des arguments, et que la plupart du
temps je ne suis pas surpris par le comportement réel.

Ce sont ces attentes, satisfaites dans l'immense majorité des cas, que
je décris ici.

ça me parait un peu cafouilleux de dire : les noms de fichier commençant
par "-" sont autorisés, à condition d'en trouver un qui ne commence pas
par "-" à mettre en 1er.

Alors moi, voici comment je me représente les choses et ce n'est pas
cafouilleux dans mon esprit, même si j'ai peut-être une représentation
fausse. Pour moi, la syntaxe d'une commande est pratiquement toujours
de la forme :
 NOM [OPTIONS] [ARGUMENTS]

Où :
 NOM
     Est le nom unique de la commande, le plus souvent tout en minuscules,
     et toujours sans espaces.
 OPTIONS
     Est une liste d'options dont chacune commence par un tiret, parfois
     deux tirets pour les options longues. Chaque option est soit sans
     paramètre, soit avec un paramètre unique. Qu'il y ait ou non un
     paramètre est propre à l'option et ne change pas pour cette commande
     et cette option. Exemples :
       -a
       --nom-long
       -a param
       -aparam
       --nom-long=param
     Et lorsque toutes les options courtes sont sur un seul caractère je
     sais que je peux les combiner dans n'importe quel ordre. Exemples :
       ls -lt -r
       ls -r -l -t
       ls -tlr
 ARGUMENTS
     Est une liste d'arguments, souvent des noms de fichiers traités dans
     l'ordre l'un après l'autre.

Par ailleurs, je sais que l'on passe automatiquement de la partie OPTIONS
à la partie ARGUMENTS dès que l'on trouve un mot qui commence par autre
chose qu'un tiret (en dehors des paramètres d'options bien sûr). Et que
si le premier argument doit commencer par un tiret, alors il faut mettre
explicitement un séparateur -- entre les deux parties (ce séparateur
étant bien sûr autorisé même si le premier argument ne pose pas de souci.

Voilà, c'est ça ma représentation implicite, qui marche la plupart du
temps sauf pour certaines commandes que je trouve alors bizarres tant
que je ne m'y suis pas habitué. C'est le même genre de représentation
implicite qui fait que lorsque je vois un mammifère je ne m'attends
pas à ce qu'il ponde des œufs... jusqu'au jour où je tombe sur un
ornithorynque.

[...]

 
j'ai oublié de demander en passant : je peux garder le même "Usage:"
même s'il laisse penser que l'ordre est important ? l'important c'est
qu'en réalité ça ne soit pas le cas ?

À mon avis, oui. Ceux qui veulent respecter l'ordre le respecteront
et tout ira bien pour eux, tout comme ceux qui pensent que l'ordre
n'a pas d'importance. Ça me rappelle cette anecdote d'un logiciel où
le message « press any key to continue » aurait été changé en « press
a key to continue », parce que des utilisateurs ne savaient pas trouver
la touche « any » mais qu'ils savaient trouver la touche « a ».

Pour moi, dans ma représentation implicite, ce qui est dans [OPTIONS] est
par défaut indépendant de l'ordre, alors que ce qui est dans [ARGUMENTS]
est par défaut sensible à l'ordre.

[...]

 
Là aussi, encore que ta syntaxe est assez particulière. Comme Nicolas
je ne sais pas ce que fait ton logiciel et je ne l'utiliserai sans
doute jamais,

 
et je vous remercie tous de prendre du temps pour moi malgré ça :-))
 
(ce que j'espère au fond, c'est qu'un jour vous trouviez mon logiciel
utile et que vous constatiez le résultat de vos "contributions")

Pour le moment tu ne nous en as pas dit assez pour qu'on sache à quoi ça
pourrait nous servir (ou alors tu l'as fait dans une autre discussion,
que je n'ai pas lue ou que j'ai oubliée à cause de ma mauvaise mémoire).

[...]

 
Te serait-il possible d'accepter l'option -od dans tous les cas lors du
parsing, en disant juste 'attention cette option ne fait rien dans cette
version de la syntaxe' ? Bon, je ne suis pas sûr que ce soit une bonne
idée non plus.

En fait, ce que j'imagine, c'est que le parsing des options se fasse d'une
façon indépendante. Tu vois un '-ni', tu mets un flag 'with_ni'. Tu vois un
'-od /tmp', tu mets le flag 'with_od' et tu stockes '/tmp' dans 'the_od'.
Tu vois un '-v', tu mets le flag 'with_v'. Et c'est seulement à la fin que
tu fais des tests de cohérence : si tu vois à ce moment-là que le booléen
'with_od' a été positionné mais pas 'with_ni', c'est là que tu peux balancer
un message d'erreur.

tu veux dire, faire un avertissement au lieu d'une erreur ?
actuellement il fait un avertissement pour les options inconnues,
ce que j'ai transformé en erreur parce que ça me parait bcp plus sur
(voir plus haut).

Avertissement ou erreur, c'est toi qui décides. Mais tu t'es simplifié le
parsing des options en faisant une seule boucle et sans te poser des
questions, jusqu'au moment où tu as enfin *tous* les éléments en main
pour le message le plus approprié.

Ou alors tu changes la syntaxe pour qu'il y ait *une* sous-commande
obligatoire, plus les paramètres optionnels, et enfin les paramètres
positionnels. Par exemple :
 
Usage: ./rapid i [-v] gui_file
       ./rapid ni [-v] [-od output_directory] gui_file...

 
oui, comme dans svn :-)
intéressant :-)

Je n'avais pas osé parlé de cvs :-)

Note qu'ils font déjà partie des cas particuliers qui ne rentrent pas
dans les cases de ma représentation implicite.

[...]

Désolé, j'ai déjà beaucoup écrit, je n'ai pas le courage de continuer.


--
Olivier Miakinen