Extraction of the demo programs from the specs

[jvdp1]

This PR proposes to create small demo programs of the different features and to include them in the specs through the statement include in ford.
The main advantage is that the demo programs can be compiled and tested.

Using a small Fortran program, I extracted all demo programs from the specs, and generated small files for each of them. By doing that, I noticed that most of them still contained typos, missing statements, undeclared variables, ... I fixed most of them but still a few demo programs must be fixed.

So, the main advantage of this approach is that all demo programs that will be shown in the specs can be compiled (an issue that has been often mentioned).

Questions:

• What do you think about this idea?
• Is the structure OK (test/examples)?
• Currently the demo programs are added to the tests. Is this ok (I don't think so)? what should it be done?

TO DO:

• Fix remaining programs (currently commented in the CMakefile)
• Check the generated website by ford
• Add support of the demo programs to fpm

[urbanjost]

The intrinsics descriptions follow a simple pattern (example program starts with "program demo_$TOPIC" and ends with "end demo_$TOPIC") for a similar purpose (as well as do almost all my own repositories). I am interested in what develops and how it is implemented, as I have found that type of approach useful. fpm(1) is still lacking any supported documentation approach other than that ford(1) seems to be used frequently. Wondering if something might emerge that could be used by all the projects, like an option for ford(1) that could automatically generate man-pages as well as extract demo pages from source code and place them in the fpm example page if certain conventions are used. That is, place the documentation for a routine in the source code, and when ford(1) is run (or some simpler fpm-supported preprocessor) you would get the ford documentation, man-pages as real man-pages and as separate (HTML, LaTex, markdown, ...?) documents and any demo program in the documentation would be extracted and show in the ford(1) listing and in the example/ directory of fpm?

So if you follow some ford-like convention that has a man-page style using simple plain text in your source code

• your code is well documented
• demo programs are automatically generated and easily testable via fpm
• the documentation for a user guide is automatically generated
• and at least for Unix/GNU-Linux/WLS users you would have a CLI version of the procedures

[awvwgk]

Should we put this under just example. Fpm can pick up demo programs and run them as well, means we have to deploy this directory with fpm (maybe for a follow-up PR).

[14NGiestas]

• Should all the examples be added to the CMake tests? Or is it possible to run them without including them in the tests, as with fpm?

It seems it is possible to create a custom target (let's say add_custom_target(examples ...), so you can run the tests and the examples in separate, with a make examples.

I don't know if it's applicable to stdlib.

• Is the current structure (two different test directories (./test/ and ./src/tests)) fine?

I guess moving it into ./src/examples/ would be less surprising than two test and tests folders around the codebase.

[jvdp1]

• Should all the examples be added to the CMake tests? Or is it possible to run them without including them in the tests, as with fpm?

It seems it is possible to create a custom target (let's say add_custom_target(examples ...), so you can run the tests and the examples in separate, with a make examples.

I am not aware of that option. I will look at it. Thanks.

I don't know if it's applicable to stdlib.

• Is the current structure (two different test directories (./test/ and ./src/tests)) fine?

I guess moving it into ./src/examples/ would be less surprising than two test and tests folders around the codebase.

Indeed, .src/examples/ makes more sense.

[awvwgk]

It seems it is possible to create a custom target (let's say add_custom_target(examples ...), so you can run the tests and the examples in separate, with a make examples.

I am not aware of that option. I will look at it. Thanks.

Let's not create a custom target for this purpose. Instead prefix the test names and use ctest -R '^example/' to select tests based on a regular expression.

[jvdp1]

It seems it is possible to create a custom target (let's say add_custom_target(examples ...), so you can run the tests and the examples in separate, with a make examples.

I am not aware of that option. I will look at it. Thanks.

Let's not create a custom target for this purpose. Instead prefix the test names and use ctest -R '^example/' to select tests based on a regular expression.

@awvwgk This sounds a good idea. But I am not sure how to organize that. Any hints?

[jvdp1]

@fortran-lang/stdlib This PR is ready for reviewing and merging.

[14NGiestas]

LGTM I've tested with both cmake and fpm (in which seems there is no way to run all of them at once AFAIK you need to provide a name).
Maybe it is worth mentioning in the README how to run only the examples.

[jvdp1]

LGTM I've tested with both cmake and fpm (in which seems there is no way to run all of them at once AFAIK you need to provide a name). Maybe it is worth mentioning in the README how to run only the examples.

Thank you. I just added instructions to run the examples with fpm.

[jvdp1]

@14NGiestas @awvwgk I moved the directory src/examples to example, as discussed during the last Fortran Monthly call.
I believe this is ready to be merged.

[14NGiestas]

LGTM. One step closer to fpm-ization of fortran & stdlib.

[jvdp1]

Thank you for the review. I will merge this PR.