Changes directory structure of stdlib as discussed in #216

[jvdp1]

This PR changes the directory structure of stdlib as discussed in #216 opened by @wclodius2

In short:

• all "experimental" terms have been removed from the names of the modules
• a version ("experimental") tag has been added to all procedures and also in the specs. FORD uses the version tag as meta-data.

[jvdp1]

The FORD documentation can be dowloaded here.

[jvdp1]

This is a major change in terms of structure for stdlib.
Is everybody ok with that? It should be easier for the users to use stdlib now. However, is it still clear enough that the procedures are experimentatl?

[certik]

I think we are ok with the general idea to do it like this.

I think the only thing to figure out is how exactly to document that all those routines are experimental. Should we also add a comment next to each subroutine in the source file? I think I would prefer that --- we want to convey as clearly as possible that the subroutine is experimental.

[leonfoks]

@certik I believe having the version: experimental as @jvdp1 has done should suffice. Having the experimental tag in the Ford doc comments covers all bases. Is there anywhere else that would more clearly indicate the experimental nature of a function?

Could we have a script that simply parses out "version: experimental" and lists them in the docs? Maybe this is something we could add to FORD?

[milancurcic]

This is great, thank you @jvdp1.

I can't review all 51 files, but I trust that it's all or mostly correct. If there are any issues we can fix them as we go.

IMO it's clear enough that procedures are experimental the way it's documented now, but if others want it more explicitly documented, I don't object.

[certik]

I am fine with the current way the version is done, as long as nobody objects. I am always more cautious with regards to these things.

[certik]

Given how important the change is, I am CCing others who committed the most code so far: @zbeekman, @nshaffer, @scivision, @fiolj, @MarDiehl, @aradi, @ivan-pi, to make sure everybody is on board.

[fiolj]

I've been away for a while. I am ok with the change in structure.

[jvdp1]

Could we have a script that simply parses out "version: experimental" and lists them in the docs? Maybe this is something we could add to FORD?

The version of each procedure is mentioned in FORD website when you open the page of a procedure.
I think it would be also nice if the version would be added in the table that lists all the procedures.

[nshaffer]

So in the generated docs, experimental interfaces get a subsection like

Version

Experimental

What would this say for stable interfaces, "stable"? Seems strange to me. Might just be the word "version". If we are only classifying interfaces as "experimental" or "stable", I think maybe calling this section "status" makes more sense? If I'm a user and I see "Version: stable", I wonder "OK, so is there and unstable version as well?" (a la how some Linux distributions classify packages as stable/unstable/testing).

Other than that detail, I support this change.

[certik]

I agree, using Status instead of Version is better I think.

[aradi]

I agree with the suggested change version->status. Otherwise good to go, thanx @jvdp1 !

[jvdp1]

I agree with the comments on status vs version. I changed the title Version in the specs to Status in this commit.

IMO The Status keyword has also the advantage that when a procedure will be moved to the stable version, it could be mentioned something like (if we go in this direction of course):

Status

Stable, since x.x.x

[scivision]

Yes this is a good and necessary change

[ivan-pi]

Looks good to me. When we get to the point of actually stabilizing a routine we should edit the WORKFLOW.md with more accurate instructions on how the status is upgraded.

+1 to merge

[certik]

I think this is good to merge.

[jvdp1]

It seems there is an agreement on the proposed change of the structure of stdlib.
Thank you all for your feedback. I'll merge.