add Bader's draft about OOP in Fortran to the learning section (#477)

* add Bader's draft about OOP features in Fortran

The draft by the late Reinhold Bader (1966-2024) about OOP features
in Fortran is added to the learning section.  Except the addition to
the `learning.yml` file and a boiler plate header in the mandatory
`index.md` file, it is a copy-paste of the illustrations and the
text provided by `pandoc_md.md`, commit a77670d by 2024-09-03 of
the rescuing GitHub repository.[1]

[1] https://github.com/nbehrnd/bader_article

Signed-off-by: Norwid Behrnd <[email protected]>

* explicitly credit Reinhold Bader as author

Signed-off-by: Norwid Behrnd <[email protected]>

* test Sphinx' tip environment

The contribution page[1] describes optional admonition environments
which could help to retrieve hints.  It is tested on one case.

[1] https://fortran-lang.org/en/community/contributing/

Signed-off-by: Norwid Behrnd <[email protected]>

* extend usage of admonitions

Now each instance of string `_Hint:_` is substituted by an
admonition environment.

Signed-off-by: Norwid Behrnd <[email protected]>

* adjust indentations to 2 spaces/level

Snippets of code in the learning section indent with 2 spaces per
level eachl.  This pattern now is used, mostly with help of findent.

Signed-off-by: Norwid Behrnd <[email protected]>

* revise usage of f90 code block fence label

Following the requested Code style,[1] snippets of code which show
a principe but as such can not be successfully compiled no longer
carry the `f90` label.  The presence of at least one colon `:`,
or one elipsis `...` is considered as an indicator.

[1] https://fortran-lang.org/en/community/contributing/

Signed-off-by: Norwid Behrnd <[email protected]>

* redefine images as block level images

The usage of the two illustrations were edited; they now are block
level images.[1]

[1] https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html

Signed-off-by: Norwid Behrnd <[email protected]>

* change Fortran keywords to lower-case letters

Following a recommendation,[1] keywords of Fortran in the snippets
of code, running text, and section headers now are set in lower-
case characters only.  Beside syntax highlighlighting the web site
offers, this then is more consistent in style with the other booklets
already present.  There however are exceptions to this change in the
table about value statements, section Performing I/O with objects of
container-like type).

[1] #477

Signed-off-by: Norwid Behrnd <[email protected]>

* add booklet to the index of the learning section

Bader's draft about the support of OOP by Fortran now equally is
accessible from the centre (section Fortran documentation) as well
as from the lateral menu of the booklets.  The entry in the later
is new by this commit.

Signed-off-by: Norwid Behrnd <[email protected]>

* split oop single page booklet into a multipage booklett

The booklet's content now is organized in three pages.  This deviates
from the state of commit a77670d (2024-09-03) of the rescuing GitHub
respository,[1] however likely reflects better the original intent by
Bader.

[1] https://github.com/nbehrnd/bader_article

Signed-off-by: Norwid Behrnd <[email protected]>

* lightly lint the markdown file for eventual aesthetics

A light edit to improve the aesthetics of the eventual rendering
as html file.  The cross-links within the booklet are removed because
I don't understand the working of internal site links as explained by
the guidelines,[1] nor successfully identified a working example among
the other booklets by others.

[1] https://fortran-lang.org/en/community/contributing/

Signed-off-by: Norwid Behrnd <[email protected]>

* Update source/learn/oop_features_in_fortran/object_based_programming_techniques.md

Co-authored-by: Federico Perini <[email protected]>

* Update source/learn/oop_features_in_fortran/object_based_programming_techniques.md

Co-authored-by: Federico Perini <[email protected]>

* Update performance_and_ease_of_use.md

add code fence labels `f90`

* add missing f90 code fence labels

Signed-off-by: Norwid Behrnd <[email protected]>

---------

Signed-off-by: Norwid Behrnd <[email protected]>
Co-authored-by: Federico Perini <[email protected]>

Author: nbehrnd

data/learning.yml

@@ -276,6 +276,16 @@ books:
       - link: /learn/intrinsics/UNPACK
       - link: /learn/intrinsics/VERIFY
 
+  - title: Fortran Object Oriented Programming
+    description: Putting Fortran’s object-related features to practical use
+    category: Fortran Documentation
+    link: /learn/oop_features_in_fortran
+    pages:
+      - /learn/oop_features_in_fortran
+      - /learn/oop_features_in_fortran/object_based_programming_techniques
+      - /learn/oop_features_in_fortran/object_oriented_programming_techniques
+      - /learn/oop_features_in_fortran/performance_and_ease_of_use
+
 # Web links listed at the bottom of the 'Learn' landing page
 #
 reference-links:

source/learn.md

@@ -185,4 +185,5 @@ learn/building_programs/index
 learn/best_practices/index
 learn/intrinsics/index
 learn/rosetta_stone
+learn/oop_features_in_fortran/index
 :::

source/learn/oop_features_in_fortran/images/Dependency_inversion.png

@@ -0,0 +1,38 @@
+# Putting Fortran’s object-related features to practical use
+
+:::{toctree}
+:maxdepth: 2
+:hidden:
+Object-based programming techniques <object_based_programming_techniques>
+Object-oriented programming techniques <object_oriented_programming_techniques>
+Performance and ease of use <performance_and_ease_of_use>
+:::
+
+This article by the late Reinhold Bader (1966-2024)
+describes how advanced Fortran language features can be
+applied toward object-based and object-oriented programming techniques.
+These are, of course, to a significant extent a matter of taste,
+personal style and possibly overarching program design considerations,
+so should be taken with a pinch of salt.
+
+Language features from Fortran 95 and later will be used; those from
+Fortran 2003 and later will also be shortly described. They are
+explained in more detail in e.g., Metcalf, Reid, Cohen and Bader.[^mfe]
+See also [Fortran 95 language
+features](https://en.wikipedia.org/wiki/Fortran_95_language_features) for
+the language's fundamentals; the prerequisite for understanding this article
+is that features explained there are well understood.
+
+Boldface will be used where term definitions are introduced. They are
+additionally annotated by "(not a Fortran term)" or similar if the term
+is not used in the Fortran standard itself, but is in general use in the
+technical literature.
+
+Compilable and runnable example code is available from an external
+[Github repository](https://github.com/reinh-bader/object_fortran).
+
+[^mfe]:
+    Metcalf, Michael; Reid, John; Cohen, Malcolm; Bader, Reinhold (2023).
+    _Modern Fortran Explained._ Numerical Mathematics and Scientific Computation.
+    Oxford University Press.
+    [ISBN 978-0-19-887657-1](https://en.wikipedia.org/wiki/Special:BookSources/978-0-19-887657-1).