Page 1 sur 2

Index des fonctions

MessagePosté: Vendredi 14 Janvier 2011, 08:19
par GMaths
Un message a été lancé pour dire qu'il faudrait un lieu pour recenser les packages.

Un nouveau message a été lancé pour annoncer une nouvelle documentation.

Personnellement, j'avoue que je n'imprime jamais les docs... car je ne les lis jamais entièrement : je n'ai encore jamais lu plus de 5 pages consécutives de la doc Asymptote... et je suis sûr qu'il y a des choses que je n'y ai encore jamais lues. Donc, personnellement, ce qui manque, le plus pour Asymptote, c'est d'avoir quelque chose comme cela :

une page internet de ce type : http://www.piprime.fr/files/asymptote/geometry/modules/geometry.asy.index.type.html, qui permet de rapidement connaitre toutes les syntaxes... et que l'on pourrait progressivement rattacher ensuite à des exemples.

Si personne ne se lance là dedans, je vais finir par le faire un jour... un jour.

Je le dis pour Asymptote...
... mais je le dis aussi pour le suggérer à Alain avec ses packages Tikz. ;-) Passera-t-il par ici pour le lire ? :D J'espère car cela m'éviterait de faire aussi un index pour ses packages. :mrgreen:

---------

Edition du 29/02/2012 : ... pour signaler que peu de temps après le message ci-dessus... naissait une page "Index des fonctions", en lien dans la signature ci-dessous.

Re: Packages, docs et index des fonctions

MessagePosté: Vendredi 14 Janvier 2011, 10:50
par projetmbc
Bonjour,
l'exemple que tu donnes est simplement la documentation des packages comme cela peut se faire pour des bibliothèques comme par exemple celle-ci. C'est une très bonne idée, après à chaque programmeur d'un package de prendre l'habitude de documenter son code. Peut-être qu'un outil comme docxygen peut être utilisé à cette fin.

Si cette documentation n'est pas accompagné d'exemple, je n'en vois pas l'utilité. C'est juste ennuyeux et inefficace au possible car cela ne devient utile que lorsque l'on commence à connaître le langage et du coup cela ne sert plus que de pense-bête.

En tout cas, réunir tout ce qui apparait sur ce forum autour de Asymptote serait une bonne idée parce que les messages du forum disparaissent vite de la surface du moment.

Re: Packages, docs et index des fonctions

MessagePosté: Vendredi 14 Janvier 2011, 15:53
par rebouxo
Je dois dire que j'ai du mal à comprendre ce que tu cherches à faire.
Le fait qu'une doc ne se lise pas comme un roman, ne veux pas dire que l'impression soit inutile. Moi z'aussi je zappe dans une doc. L'intérêt (pour moi) c'est de pouvoir avoir sous les yeux la doc et le code que tu tapes. Comme j'ai pas encore deux écrans (et que je ne saurais pas avoir deux trucs différents sur deux écrans)... A la limite, avec une tablette... Mais bon, je vais encore attendre un peu que tout cela se standardise.

Olivier

Re: Packages, docs et index des fonctions

MessagePosté: Vendredi 14 Janvier 2011, 18:18
par GMaths
rebouxo a écrit:Je dois dire que j'ai du mal à comprendre ce que tu cherches à faire.

Tu as regardé le lien ?

Je dis que lorsque je me demande quels sont les paramètres que je peux passer quand je tente de définir une droite, la lecture des lignes suivantes :

Code: Tout sélectionner
line Ox(coordsys)
line Oy(coordsys)
line altitude(vertex)
line altitude(vertex)
line bisector(line,line,real,bool)
line bisector(point,point,point,point,real)
line bisector(point,point,real)
line bisector(segment,real)
line bisector(side)
line bisector(vertex,real)
line cevian(vertex,point)
line changecoordsys(coordsys,line)
line complementary(explicit line)
line extend(line)
line hline(coordsys)
line isogonal(vertex,point)
line isotomic(vertex,point)
line line(coordsys,real,real)
line line(coordsys,real,real,real)
line line(explicit side)
line line(point,bool,point,bool)
line line(real,point)
line line(segment)
line median(side)
line median(vertex)
line parallel(point,explicit pair)
line parallel(point,explicit vector)
line parallel(point,line)
line perpendicular(point,explicit pair)
line perpendicular(point,explicit vector)
line perpendicular(point,line)
line radicalline(circle,circle)
line reverse(line)
line sector(int,int,line,line,real,bool)
line symmedian(vertex)
line tangent(circle,abscissa)
line tangent(circle,explicit vector)
line tangent(circle,point)
line tangent(ellipse,abscissa)
line tangent(explicit arc,abscissa)
line tangent(explicit arc,point)
line tangent(hyperbola,abscissa)
line tangent(parabola,abscissa)
line vline(coordsys)
line[] complementary(explicit segment)
line[] tangents(circle,point)
line[] tangents(ellipse,point)
line[] tangents(hyperbola,point)
line[] tangents(parabola,point)


me montre clairement l'étendue des possibilités en matière de fonctions qui définissent un objet de type line... et si je doute d'une commande à la seule lecture des paramètres, alors en cliquant sur le lien, j'ai une explication.

rebouxo a écrit:Le fait qu'une doc ne se lise pas comme un roman, ne veux pas dire que l'impression soit inutile.


Où ai-je écrit que cela t'était inutile ou que cela était inutile pour d'autres ? Procès d'intention !

rebouxo a écrit:L'intérêt (pour moi) c'est de pouvoir avoir sous les yeux la doc et le code que tu tapes.


Je comprends très bien cela... au point que je suis incapable de faire du latex, sans avoir le rendu sous les yeux.

rebouxo a écrit:Comme j'ai pas encore deux écrans (et que je ne saurais pas avoir deux trucs différents sur deux écrans).


J'aurais abandonné latex si je n'avais pas acheté un deuxième écran (à l'époque deux 17 pouces).
Il est vrai qu'aujourd'hui, avec un seul de mes 26 pouces, on peut travailler en visualisant code et version compilée... mais quand j'ai débuté, je n'avais qu'un 17 pouces et je souffrais au point d'avoir vite décidé d'en acheter un deuxième.
Je serais incapable de travailler sur un portable... et donc je comprends très bien que ceux qui bossent sur un écran de taille raisonnable ressentent le besoin d'avoir la version imprimée de certaines docs, pour avoir deux choses simultanément sous les yeux. J'ai investi dans deux grands écrans pour pouvoir m'en passer... avec l'intérêt de pouvoir abuser de la fonction recherche dans les pdfs.

Donc imprimez, imprimez... pas de problème pour moi.

Je ne tentais que de dire qu'il y a un autre type de support qui peut être utile à certains : voilà ce qu'il fallait comprendre.

Re: Index des fonctions

MessagePosté: Samedi 15 Janvier 2011, 13:42
par c-top
GMaths a écrit:Donc, personnellement, ce qui manque, le plus pour Asymptote, c'est d'avoir quelque chose comme cela :


Oui, tout simplement une API comme celle de java
http://download.oracle.com/javase/1.5.0/docs/api/

Le problème c'est qu'il faut beaucoup de temps pour une seule personne...

Re: Index des fonctions

MessagePosté: Samedi 15 Janvier 2011, 17:24
par projetmbc
c-top a écrit:Le problème c'est qu'il faut beaucoup de temps pour une seule personne...

En fait, ceci est le boulot des programmeurs.Il serait bien qu'à chaque fois que quelqu'un tape un nouveau programme ou package, il le documente en interne en plus d'une documentation fournissant des exemples.

J'avais proposé Doxygen qui permet de documenter son code en utilisant les commentaires : voir ici.

Pour ce qui concerne Asymptote lui-même, je suis très étonné que ceci n'existe pas. C'est un gros projet... Il faudrait demander cela aux concepteurs d'Asymptote.

Re: Index des fonctions

MessagePosté: Samedi 15 Janvier 2011, 19:54
par GMaths
Une version succincte et provisoire : http://gmaths.net/asy/index/, une simple extraction du fichier asy.list.

En attendant :
- des fonctions de recherche et de filtrage ;
- d'autres choses... suivant mon humeur et mon temps de libre.

Il y a 3 bogues identifiés. Leur résolution attendra.

Edition : il y a en fait davantage de bogues, dans le fichier asy.list (qui est j'imagine le produit d'un script qui tente d'extraire automatiquement les fonctions d'Asymptote) : même si cela peut rendre des service (car les lignes erronées se devinent), dommage que cela ne soit pas fiable à 100%.

Re: Index des fonctions

MessagePosté: Samedi 15 Janvier 2011, 22:16
par projetmbc
Au temps pour moi... A-t-on accès au code des fonctions à utiliser côté utilisateur et non côté code source de Asymptote ?

Par contre, ceci ne retire rien à ce que j'ai dis pour les nouveaux packages faits par çi, par là.

Re: Index des fonctions

MessagePosté: Samedi 15 Janvier 2011, 23:36
par Romain Janvier
Merci beaucoup pour tout cela. Perso, moi non plus je n'imprime pas les docs, mais je cherche soit dans les version online, soit dans les versions pdf, cela va bien plus vite que sur du papier.

Ca fait un moment que je cherchais aussi un equivalent de la liste des specifications de geometry.asy pour les autres packages, parce que qu'est ce que c'est penible de ne jamais savoir quels sont les parametres possibles pour les fonctions utilisées, meme les plus courantes.

Après, effectivement, cela serait top d'avoir une doc aussi detaillee que celles de certaines api, mais comme je ne mets presque jamais de commentaires dans mes fichiers, je ne peux pas reprocher aux autres de ne pas le faire.

Re: Index des fonctions

MessagePosté: Dimanche 16 Janvier 2011, 10:51
par c-top
projetmbc a écrit:En fait, ceci est le boulot des programmeurs.Il serait bien qu'à chaque fois que quelqu'un tape un nouveau programme ou package,


Oui, et je dirais même plus je pense que les premiers à le faire devrait être les développeurs d'asymptote. Puisque l'essentiel du produit est développé par eux. A chaque nouvelle version ils n'auraient plus qu'à passer leur moulinette pour la doc type API. Une des principales difficultés pour l'utilisateur asymptote est que toutes les infos dont-il a besoin ne se trouvent pas forcement dans les fichiers asy. Le code source C contient lui aussi des renseignements indispensables pour comprendre les mécanismes de ce logiciel.

Re: Index des fonctions

MessagePosté: Dimanche 16 Janvier 2011, 11:21
par GMaths
GMaths a écrit:Une version succincte et provisoire : http://gmaths.net/asy/index/, une simple extraction du fichier asy.list.

En attendant :
- des fonctions de recherche et de filtrage ;
- d'autres choses... suivant mon humeur et mon temps de libre.

Il y a 3 bogues identifiés. Leur résolution attendra.

Edition : il y a en fait davantage de bogues, dans le fichier asy.list (qui est j'imagine le produit d'un script qui tente d'extraire automatiquement les fonctions d'Asymptote) : même si cela peut rendre des service (car les lignes erronées se devinent), dommage que cela ne soit pas fiable à 100%.


J'ai posé la question et on peut surveiller la réponse : sur le forum de JCBowman.

Re: Index des fonctions

MessagePosté: Dimanche 16 Janvier 2011, 11:23
par MB
Je ne connaissais pas le fichier asy.list : tu sais comment il est créé ?

Re: Index des fonctions

MessagePosté: Dimanche 16 Janvier 2011, 11:43
par GMaths
MB a écrit:Je ne connaissais pas le fichier asy.list : tu sais comment il est créé ?


Apparemment, c'est ce que produit la commande :

Code: Tout sélectionner
asy -l


... avec une retouche qui n'est pas très claire pour moi :

Extrait du Makefile d'installation de la version SVN :

Code: Tout sélectionner
asy-keywords.el: asy
        @echo Creating $@;
        $(ASY) -l > asy.list
        ls $(addsuffix /*.asy,$(KEYWORDS)) | grep -v plain\* | \
          grep -v three_\* | grep -v featpost3D | xargs $(ASY) -l >> asy.list
        perl ./asy-list.pl asy.list 2.09svn


Contenu de asy-list.pl :

Code: Tout sélectionner
#!/usr/bin/env perl
#####
# asy-list.pl
#
#  Build asy-keywords.el from list of asy global functions and variables
#
#####

open(keywords, "> asy-keywords.el") ||
    die("Couldn't open asy-keywords.el for writing.");

print keywords <<END;
;;
;; This file is automatically generated by asy-list.pl.
;; Changes will be overwritten.
;;
(defvar asy-keywords-version "$ARGV[1]")

END

sub add {
  print keywords $_[0]." ";
}

sub openlist {
    open(asylist, $ARGV[0]) || die("Couldn't open $ARGV[0]");
}

print keywords <<END;
(defvar asy-keyword-name '(
END

open(camp, "camp.l") || die("Couldn't open camp.l");

# Search for the %% separator, after which the definitions start.
while (<camp>) {
  if (/^%%\s*$/) {
    last; # Break out of the loop.
  }
}

while (<camp>) {
  if (/^%%\s*$/) {
    last; # A second %% indicates the end of definitions.
  }
  if (/^(\w+)\s*\{/) {
    add($1);
  }
}

openlist();

while (<asylist>) {
  if (/^(\w*)[^ ]* (\w*)\(.*/) {
    push @types, $1;
    push @functions, $2;
  }
  if (/^([^ ]*) (\w*);/) {
    push @variables, $2;
  }
}

@saw{@types} = ();
@types = sort keys %saw;
undef %saw;

@saw{@functions} = ();
@functions = sort keys %saw;
undef %saw;

@saw{@variables} = ();
@variables = sort keys %saw;
undef %saw;

print keywords <<END;
))

(defvar asy-type-name '(
END

foreach(@types) {
 print keywords $_ . " ";
}

print keywords <<END;
))

(defvar asy-function-name '(
END

foreach(@functions) {
 print keywords $_ . " ";
"asy-list.pl" 106L, 1612C

@saw{@types} = ();
@types = sort keys %saw;
undef %saw;

@saw{@functions} = ();
@functions = sort keys %saw;
undef %saw;

@saw{@variables} = ();
@variables = sort keys %saw;
undef %saw;

print keywords <<END;
))

(defvar asy-type-name '(
END

foreach(@types) {
 print keywords $_ . " ";
}

print keywords <<END;
))

(defvar asy-function-name '(
END

foreach(@functions) {
 print keywords $_ . " ";

Re: Index des fonctions

MessagePosté: Jeudi 20 Janvier 2011, 17:47
par GMaths
GMaths a écrit:
GMaths a écrit:Edition : il y a en fait davantage de bogues, dans le fichier asy.list (qui est j'imagine le produit d'un script qui tente d'extraire automatiquement les fonctions d'Asymptote) : même si cela peut rendre des service (car les lignes erronées se devinent), dommage que cela ne soit pas fiable à 100%.


J'ai posé la question et on peut surveiller la réponse : sur le forum de JCBowman.


Finalement... il semble plutôt très fiable ce fichier asy.list... sauf que, tout ce qui a été défini par des typedef n'est pas directement pris en compte.

Un exemple pour comprendre :

on ne va pas trouver de transform3, car transform3 est défini ainsi :

Code: Tout sélectionner
typedef real[][] transform3;


Et donc, alors que l'on aimerait retrouver dans l'index ceci :

Code: Tout sélectionner
transform3 scale(real x, real y, real z)


on y lit plutôt :

Code: Tout sélectionner
real[][]..........scale(real x, real y, real z);


c'est à dire que l'on en revient aux fondamentaux.

Pour améliorer l'index, j'avais pensé de prendre en compte les typedef de tous les asy... au niveau du php mais le problème est que, par exemple, tous les objets de type real[][] ne doivent pas être assimilés à des transform3.

Re: Index des fonctions

MessagePosté: Jeudi 20 Janvier 2011, 18:20
par GMaths
GMaths a écrit:Pour améliorer l'index, j'avais pensé de prendre en compte les typedef de tous les asy... au niveau du php mais le problème est que, par exemple, tous les objets de type real[][] ne doivent pas être assimilés à des transform3.


J'ai écrit sur le forum officiel qu'il est dommage que les typedef ne sont pas directement pris en compte... sans croire qu'il va être proposé de changer les choses. On verra ce que répondra JCB.

Donc, si je persiste avec mon idée d'index... je crois que je vais devoir moi même extraire les renseignements nécessaires directement des fichiers.asy
Je vais devoir approfondir mes connaissances sur les "expressions régulières" en php.

Re: Index des fonctions

MessagePosté: Jeudi 20 Janvier 2011, 18:57
par GMaths
GMaths a écrit:J'ai écrit sur le forum officiel qu'il est dommage que les typedef ne sont pas directement pris en compte... sans croire qu'il va être proposé de changer les choses. On verra ce que répondra JCB.

Qui ne tente rien, n'a rien : je lui ai demandé de clarifier le fichier asy.list en ajoutant des choses.
Affaire à suivre.

Re: Index des fonctions

MessagePosté: Dimanche 30 Janvier 2011, 12:17
par GMaths
GMaths a écrit:
GMaths a écrit:J'ai écrit sur le forum officiel qu'il est dommage que les typedef ne sont pas directement pris en compte... sans croire qu'il va être proposé de changer les choses. On verra ce que répondra JCB.

Qui ne tente rien, n'a rien : je lui ai demandé de clarifier le fichier asy.list en ajoutant des choses.
Affaire à suivre.

Des nouvelles : la demande sera sans suite... mais j'ai eu une suggestion.

Petite amélioration de l'index accessible via ma signature.

Quand je trouve un peu de temps... je travaille sur un script qui se passera d'asy.list : je vais analyser fichier asy par fichier asy, en exploitant la sortie obtenue avec "asy -p".

Re: Index des fonctions

MessagePosté: Dimanche 30 Janvier 2011, 12:24
par projetmbc
Bonjour,
dans la mesure où ta proposition est directement lié au développement de Asymptote, il serait pas mal que tu essayes de te greffer au projet lui-même. ce genre de choses est de la doc. pure et dure qui devrait être sur le site de Asymptote.

Re: Index des fonctions

MessagePosté: Dimanche 30 Janvier 2011, 12:26
par projetmbc
Autre chose, avec jQuery, excuses moi j'aime bien cette bibliothèque, il y a la possibilité de faire des onglets assez facilement. Il pourrait être envisageable dans un 2nd temps de les utiliser pour pouvoir choisir des infos suivant la 1ère lettre de la fonction dont l'utilisateur souhaite avoir les infos.

Re: Index des fonctions

MessagePosté: Dimanche 30 Janvier 2011, 12:41
par GMaths
projetmbc a écrit:Autre chose, avec un jQuery, excuses moi j'ai bien cette bibliothèque, il y a la possibilité de faire des onglets assez facilement. Il pourrait être envisageable dans un 2nd temps de les utiliser pour pouvoir choisir des infos suivant la 1ère lettre de la fonction dont l'utilisateur souhaite avoir les infos.
Tout cela (onglets et sélection par première lettre), je sais faire... sans jQuery
mais je préfère ne pas me précipiter pour bien réfléchir à bien prendre en compte tout ce que je peux pourrais ajouter.