[Gambas-devel] Example project metadata

[Tobias Boege]

On Sun, 07 Jul 2013, Beno?t Minisini wrote:
> Le 04/07/2013 11:43, Tobias Boege a ?crit :
> > Hi Benoit,
> >
> > the last couple of days I implemented Fabien's approach[0] to better example
> > projects - halfways.
> >
> > There is a patch to the IDE attached which changes the following:
> >
> > - Project.module: Add Niveau and Tags Public variables. An ".example" file
> >    in the project directory makes a project an "example project". If it is
> >    missing, it is not an example project. The data is written in
> >    WriteProject() and read in ReadProject() - if the .example file exists;
> > - FCreateProject: New "Example project" CheckBox in the "Options" and a new
> >    wizard step to enter example Niveau and Tags. The project creator is
> >    forced to write a project description here, too. If the CheckBox is
> >    ticked, the ".example" file is created here;
> > - FProjectProperties: CheckBox to make/unmake the project an "example"
> >    project and a new TabPanel page to manipulate Niveau and Tags. Note that
> >    this TabPanel page is only visible when the project is an example project.
> >    That new page is not very populated - not to say it looks ugly. The
> >    aforementioned CheckBox may also be misplaced but I didn't want to mess
> >    around with the usual layout. Any ideas? Based on the value of the
> >    CheckBox, the ".example" file is created or delete here.
> >
> > Please tell me what you don't like.
> >
> > What's missing?
> >
> > - Displaying the niveau and tags in FWelcome and FOpenProject;
> > - Sorting examples by niveau;
> > - Filtering by tags;
> > - The gambasdoc.org page with official example guidelines (just a few notes
> >    I planned).
> >
> > I couldn't get behind the sources of FWelcome and FOpenProject yet. Maybe a
> > new control to display examples which is shared by the two forms suits
> > better.
> >
> > As for the examples themselves, I have gone through 1/3 of them which I
> > understand (this excludes, e.g. DBus, MySQLExample, ReportExample). Mainly I
> > fixed these things:
> >
> > - Naming conventions;
> > - Comments;
> > - Style and educational things (based on MHO).
> >
> > We could also just leave things as-is and I just commit the overhauled
> > examples and not the changes to the IDE if you think the IDE stuff could not
> > be a good idea at all.
> >
> > Regards,
> > Tobi
> >
> > [0] http://sourceforge.net/mailarchive/message.php?msg_id=30788433
> >
> 
> I agree with adding Tags to examples, but I find the Level thing purely 
> subjective and useless. It can be replaced by specific tags.
> 

Sure. As for the level, I thought that "Beginner" means

- demonstrate usage of a class/classes in a component;
- comments focus on the interface, i.e. the "how";

whereas "Advanced" is

- show what can be done with this class/classes or component/components;
- expect knowledge about basic usage;
- comments focus on the classes interacting, the "what".

E.g. the "MediaPlayer" is advanced and "MapView" on the other hand is not.
We could also easily judge over the classification by looking at the number
of source files in these cases. Projects which define multiple custom
classes are likely advanced.

This is roughly what I would have said about these niveaus on the gambasdoc
page.

> I agree with adding Tags to all projects, even if it is used only with 
> example projects.
> 

This makes .example superfluous.

> Maybe some tags should be predefined.
> 

Now that the "niveau" term is not that subjective anymore to you (I hope),
these could be candidates, right? It's not that I want this classification
for didactic purposes or easy filtering for newbies but instead to be able
to tell example creators that they can create two favours of examples and
which criteria they have to meet in each case.

This distinction between "Beginner" and "Advanced" was observed by nearly
all who answered to my original thread at gambas-user.

> Don't use an '.example' file, put everything in the '.project' 
> configuration file.
> 
> I don't think it is useful to enter tags in the project creation dialog, 
> because you usually don't know exactly what they are at that point.
> 
> Then I will design a new example IDE interface. And you're right, the 
> code should be shared between FOpenProject and FWelcome through a common 
> form.
> 
> *But* I think the more important keeps working on the examples 
> themselves! :-)
> 

It's a tiresome work :-) I frequently take breaks to do something in gb.data
nowadays - which brings me to another question: I saw that trunk is labelled
as version 3.4.90. Does this mean we are done with the 3.4 series (which
would contradict the latest "News" item)? When will the next stable version
come out? I'd like to have a Tree class committed before to have it tested
ASAP by the stable users (especially if it's a new minor version).

Regards,
Tobi