Where to put example .prm files?

[tjhei]

We currently have cookbooks/ and benchmarks/ and I am looking for a place to put several example files that are interesting variations of existing .prm files.

My interpretation of cookbooks/: Teach something about ASPECT in a section in the manual. My interpretation of benchmarks/: Used to reproduce an existing benchmark most often published in the literature somewhere, often with postprocessing steps.

Here some examples of what I would like to add:

• several interesting cases with free surface
• several examples with different kind of nullspaces

So, where should I put these? Should we make an examples/ folder? Just add to cookbooks/ without a manual section or create a manual section that contains a single paragraph?

[bobmyhill]

Would contrib/examples work? Or do you want the folder to be more visible than that (in which case I'd favour a top-level examples directory)?

[jdannberg]

I just want to add here that in case you make a new examples/ directory, it would be worth moving the files from cookbooks/future/ there as well. These are "prm files that may at some point become a cookbook with a section in the manual" (as per the README). I am not sure for how many of these that has actually happened, but I think that's currently the place to put the kind of files you describe. If your prm files have comments that explain what's being done, I like the idea of just having maybe a sentence in the manual that says: This file shows how to do A, B, and C.

But if these are variations of existing cookbooks, you could also just make a new Section at the end of the corresponding cookbook explaining the change (like in the Convection in a 2d box cookbook, which has several "Play time" subsections with modifications of the input file).

For your specific examples, I would also link them from the Free Surface and Nullspace Sections in the manual, which I think would be super useful for anyone reading these.

[tjhei]

I just want to add here that in case you make a new examples/ directory, it would be worth moving the files from cookbooks/future/ there as well

Yes, I was thinking of those files as well.

If your prm files have comments that explain what's being done, I like the idea of just having maybe a sentence in the manual that says: This file shows how to do A, B, and C.

That makes sense, even though it is some extra effort. I am looking forward to the switch to markdown generated manual...

Would you still be in favor of making examples/ or would you just put them into cookbooks/?

[jdannberg]

I think I would prefer having them in a separate examples/ folder.
I remember we have slides for tutorials where we explain what types of training materials we have, and we always sort them from largest to least amount of documentation, so

tutorial videos --> cookbooks --> tests

Examples would be a separate step in between the cookbooks and the tests.

[bangerth]

Several of @cedrict 's recent cookbooks are not so different from what I think you want to do: They reproduce something someone has done in a paper, or show an application case. I think there is really no particular reason why what @tjhei suggests above can't also go into the cookbooks section. My vote is that whatever setup you have might as well go into the cookbooks section, in particular if you are "looking for a place to put several example files that are interesting variations of existing .prm files".

Let's keep things simple. We can always subdivide the cookbooks further than we already do into sections.