Moved the README to markdown and expanded its overview of the files, file generation, and other Fortran wrapper development practices as mentioned in the HDF5 architectural document. I added a new figure and included the SVG file and the original xfig file it was generated from. (#3862)

4 files changed, 406 insertions, 133 deletions

diff --git a/fortran/src/FortBuildFlow.fig b/fortran/src/FortBuildFlow.fig
new file mode 100644
index 0000000..fd2dee7
--- /dev/null
+++ b/fortran/src/FortBuildFlow.fig
@@ -0,0 +1,78 @@
+#FIG 3.2  Produced by xfig version 3.2.9
+#encoding: UTF-8
+Landscape
+Center
+Inches
+Letter
+100.00
+Single
+-2
+1200 2
+6 4650 3675 7725 4350
+2 4 0 1 0 7 52 -1 18 0.000 0 0 7 0 0 5
+	 7725 4350 4650 4350 4650 3735 7725 3735 7725 4350
+4 0 0 37 -1 2 16 0.0000 4 240 2528 4800 4125 H5fort_type_defines.h\001
+-6
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 4125 675 4650 675
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 4125 2775 4575 2775
+2 1 0 4 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 8175 525 9525 525
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 10800 3375 8325 3375 8325 2760 10800 2760 10800 3375
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 10760 1200 11400 1200
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 10820 2100 11460 2100
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 10790 3075 11430 3075
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 4125 3375 1500 3375 1500 60 4125 60 4125 3375
+2 1 0 4 0 7 48 -1 -1 0.000 0 0 -1 0 0 2
+	 1500 1800 4050 1800
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 5775 960 5775 1410
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	2 1 1.00 60.00 120.00
+	 5670 3255 5670 3705
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 14220 1500 11460 1500 11460 870 14220 870 14220 1500
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 14250 2430 11445 2430 11445 1800 14250 1800 14250 2430
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 6975 960 4725 960 4725 360 6975 360 6975 960
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 6960 2025 4710 2025 4710 1425 6960 1425 6960 2025
+2 4 0 1 0 7 52 -1 19 0.000 0 0 7 0 0 5
+	 16875 5250 8100 5250 8100 45 16875 45 16875 5250
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 7725 3225 4650 3225 4650 2610 7725 2610 7725 3225
+2 4 0 1 0 7 63 -1 19 0.000 0 0 7 0 0 5
+	 8025 5250 1425 5250 1425 45 8025 45 8025 5250
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 10800 2400 8310 2400 8310 840 10800 840 10800 2400
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 14265 3375 11475 3375 11475 2775 14265 2775 14265 3375
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 16725 4125 11475 4125 11475 3525 16725 3525 16725 4125
+2 4 0 1 0 7 50 -1 18 0.000 0 0 7 0 0 5
+	 16725 4950 11475 4950 11475 4275 16725 4275 16725 4950
+4 0 0 50 -1 2 24 0.0000 4 284 1249 8250 450 BUILD\001
+4 0 0 50 -1 2 24 0.0000 4 284 2421 1575 1725 CONFIGURE\001
+4 0 0 50 -1 2 16 0.0000 4 221 2083 8550 3150 H5_buildiface.F90\001
+4 0 0 50 -1 2 16 0.0000 4 235 1952 8640 1680 H5match_types.c\001
+4 0 0 50 -1 2 16 0.0000 4 239 2379 11550 2175 H5fortran_types.F90\001
+4 0 0 50 -1 2 16 0.0000 4 240 1507 11550 1275 H5f90i_gen.h\001
+4 0 0 50 -1 2 16 0.0000 4 238 1358 11550 3150 H5_gen.F90\001
+4 0 0 50 -1 2 16 0.0000 4 233 5100 11550 3900 H5[A,D,S,T,E,ES,F,Z,G,I,L,O,P,R,VL]ff.F90\001
+4 0 0 50 -1 2 16 0.0000 4 233 4702 11550 4725 H5[A,D,S,T,E,ES,F,Z,G,I,L,O,P,R,VL]f.c\001
+4 0 0 50 -1 2 16 0.0000 4 240 1944 4815 750 H5config_f.inc.in\001
+4 0 0 50 -1 2 16 0.0000 4 240 1656 4815 1815 H5config_f.inc\001
+4 0 0 50 -1 2 16 0.0000 4 240 2817 4740 3000 H5fort_type_defines.h.in\001
diff --git a/fortran/src/FortBuildFlow.svg b/fortran/src/FortBuildFlow.svg
new file mode 100644
index 0000000..b7ebc47
--- /dev/null
+++ b/fortran/src/FortBuildFlow.svg
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Creator: fig2dev Version 3.2.9 -->
+<!-- CreationDate: 2023-11-17 17:06:33 -->
+<!-- Magnification: 1 -->
+<svg	xmlns="http://www.w3.org/2000/svg"
+	xmlns:xlink="http://www.w3.org/1999/xlink"
+	width="929pt" height="314pt"
+	viewBox="1413 33 15474 5229">
+<g fill="none">
+<!-- Line -->
+<rect x="1425" y="45" width="6600" height="5205" rx="105" fill="#f2f2f2"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="8100" y="45" width="8775" height="5205" rx="105" fill="#f2f2f2"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="4650" y="3735" width="3075" height="615" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<polyline points=" 8175,525 9525,525"
+	stroke="#000000" stroke-width="45px"/>
+<!-- Line -->
+<rect x="8325" y="2760" width="2475" height="615" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp0">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 11230,1170 11260,1200 11230,1230 11407,1207 11407,1193z"/>
+</clipPath>
+</defs>
+<polyline points=" 10760,1200 11400,1200" clip-path="url(#cp0)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 11400,1200 -->
+<polygon points=" 11230,1230 11380,1200 11230,1170 11260,1200 11230,1230"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp1">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 11290,2070 11320,2100 11290,2130 11467,2107 11467,2093z"/>
+</clipPath>
+</defs>
+<polyline points=" 10820,2100 11460,2100" clip-path="url(#cp1)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 11460,2100 -->
+<polygon points=" 11290,2130 11440,2100 11290,2070 11320,2100 11290,2130"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp2">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 11260,3045 11290,3075 11260,3105 11437,3082 11437,3068z"/>
+</clipPath>
+</defs>
+<polyline points=" 10790,3075 11430,3075" clip-path="url(#cp2)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 11430,3075 -->
+<polygon points=" 11260,3105 11410,3075 11260,3045 11290,3075 11260,3105"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<rect x="1500" y="60" width="2625" height="3315" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp3">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 5805,1240 5775,1270 5745,1240 5768,1417 5782,1417z"/>
+</clipPath>
+</defs>
+<polyline points=" 5775,960 5775,1410" clip-path="url(#cp3)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 5775,1410 -->
+<polygon points=" 5745,1240 5775,1390 5805,1240 5775,1270 5745,1240"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp4">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 5700,3535 5670,3565 5640,3535 5663,3712 5677,3712z"/>
+</clipPath>
+</defs>
+<polyline points=" 5670,3255 5670,3705" clip-path="url(#cp4)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 5670,3705 -->
+<polygon points=" 5640,3535 5670,3685 5700,3535 5670,3565 5640,3535"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<rect x="11460" y="870" width="2760" height="630" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="11445" y="1800" width="2805" height="630" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="4725" y="360" width="2250" height="600" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="4710" y="1425" width="2250" height="600" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="4650" y="2610" width="3075" height="615" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Text -->
+<text xml:space="preserve" x="4740" y="3000" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5fort_type_defines.h.in</text>
+<!-- Line -->
+<defs>
+<clipPath id="cp5">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 4480,645 4510,675 4480,705 4657,682 4657,668z"/>
+</clipPath>
+</defs>
+<polyline points=" 4125,675 4650,675" clip-path="url(#cp5)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 4650,675 -->
+<polygon points=" 4480,705 4630,675 4480,645 4510,675 4480,705"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Line -->
+<defs>
+<clipPath id="cp6">
+	<path clip-rule="evenodd" d="M 1413,33 H 16887 V 5262 H 1413 z
+		M 4405,2745 4435,2775 4405,2805 4582,2782 4582,2768z"/>
+</clipPath>
+</defs>
+<polyline points=" 4125,2775 4575,2775" clip-path="url(#cp6)"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Forward arrow to point 4575,2775 -->
+<polygon points=" 4405,2805 4555,2775 4405,2745 4435,2775 4405,2805"
+	stroke="#000000" stroke-width="8px" stroke-miterlimit="8" fill="#000000"/>
+<!-- Text -->
+<text xml:space="preserve" x="4815" y="750" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5config_f.inc.in</text>
+<!-- Text -->
+<text xml:space="preserve" x="4815" y="1815" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5config_f.inc</text>
+<!-- Line -->
+<rect x="8310" y="840" width="2490" height="1560" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="11475" y="2775" width="2790" height="600" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="11475" y="3525" width="5250" height="600" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Line -->
+<rect x="11475" y="4275" width="5250" height="675" rx="105" fill="#e5e5e5"
+	stroke="#000000" stroke-width="8px"/>
+<!-- Text -->
+<text xml:space="preserve" x="8250" y="450" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="288" text-anchor="start">BUILD</text>
+<!-- Text -->
+<text xml:space="preserve" x="1575" y="1725" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="288" text-anchor="start">CONFIGURE</text>
+<!-- Text -->
+<text xml:space="preserve" x="8550" y="3150" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5_buildiface.F90</text>
+<!-- Text -->
+<text xml:space="preserve" x="8640" y="1680" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5match_types.c</text>
+<!-- Text -->
+<text xml:space="preserve" x="11550" y="2175" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5fortran_types.F90</text>
+<!-- Text -->
+<text xml:space="preserve" x="11550" y="1275" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5f90i_gen.h</text>
+<!-- Text -->
+<text xml:space="preserve" x="11550" y="3150" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5_gen.F90</text>
+<!-- Text -->
+<text xml:space="preserve" x="11550" y="3900" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5[A,D,S,T,E,ES,F,Z,G,I,L,O,P,R,VL]ff.F90</text>
+<!-- Text -->
+<text xml:space="preserve" x="11550" y="4725" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5[A,D,S,T,E,ES,F,Z,G,I,L,O,P,R,VL]f.c</text>
+<!-- Line -->
+<polyline points=" 1500,1800 4050,1800"
+	stroke="#000000" stroke-width="45px"/>
+<!-- Text -->
+<text xml:space="preserve" x="4800" y="4125" fill="#000000" font-family="Times" font-style="normal" font-weight="bold" font-size="192" text-anchor="start">H5fort_type_defines.h</text>
+</g>
+</svg>
diff --git a/fortran/src/README b/fortran/src/README
deleted file mode 100644
index f73a59a..0000000
--- a/fortran/src/README
+++ /dev/null
@@ -1,133 +0,0 @@
-===================================
-README for the Fortran APIs to HDF5
-===================================
-
-This directory contains Fortran APIs for HDF5 Library functionality.
-A complete list of implemented Fortran subroutines can be found in the HDF5 
-Reference Manual.
-
-About the source code organization
-==================================
-
-The Fortran APIs are organized in modules parallel to the HDF5 Interfaces.
-Each module is in a separate file with the name H5*ff.F90.  Corresponding C
-stubs are in the H5*f.c files.  For example, the Fortran File APIs are in 
-the file H5Fff.F90 and the corresponding C stubs are in the file H5Ff.c. 
-
-Each module contains Fortran definitions of the constants, interfaces to 
-the subroutines if needed, and the subroutines themselves.  
-
-Users must use constant names in their programs instead of the numerical 
-values, as the numerical values are subject to change without notice. 
-
-Quick overview of the Fortran APIs 
-==============================================
- 
-*  An in-depth description of each Fortran API and its parameters can 
-   be found in the HDF5 Reference Manual.
-
-*  The Fortran APIs come in the form of Fortran subroutines.
-
-*  Each Fortran subroutine name is derived from the corresponding C function
-   name by adding "_f" to the name.  For example, the name of the C function 
-   to create an HDF5 file is H5Fcreate;  the corresponding Fortran subroutine 
-   is h5fcreate_f.
-
-*  The parameter list for each Fortran subroutine usually has two more parameters
-   than the corresponding C function.  These additional parameters typically hold 
-   the return value and an error code.  The order of the Fortran subroutine 
-   parameters may differ from the order of the C function parameters.
- 
-   The Fortran subroutine parameters are usually listed in the following order: 
-      -- required input parameters,
-      -- output parameters, including return value and error code, and 
-         optional input parameters.
-
-   For example, the C function to create a dataset has the following 
-   prototype:
-
-       hid_t H5Dcreate2(hid_it loc_id, char *name, hid_t type_id, 
-             hid_t space_id, hid_t link_creation_prp, hid_t dset_creation_prp,
-             hid_t dset_access_prop);
-   
-   The corresponding Fortran subroutine has the following form:
-   
-       SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &
-       hdferr, dset_creation_prp, link_creation_prp, dset_access_prop)
-
-   The first four parameters of the Fortran subroutine correspond to the 
-   C function parameters.  The fifth parameter dset_id is an output 
-   parameter and contains a valid dataset identifier if the value of the 
-   sixth output parameter, hdferr, indicates successful completion. 
-   (Error code descriptions are provided with the subroutine descriptions 
-   in the Reference Manual.)  The last three input parameters are optional 
-   and may be omitted, resulting in default values being used.
-
-*  Parameters to the Fortran subroutines typically include 
-   predefined datatypes (see the build-time generated file 
-   H5fortran_types.F90 for a complete listing):
-   
-        INTEGER(HID_T)      compares with hid_t type in HDF5 C APIs
-        INTEGER(HSIZE_T)    compares with hsize_t in HDF5 C APIs
-        INTEGER(HSSIZE_T)   compares with hssize_t in HDF5 C APIs
-        INTEGER(SIZE_T)     compares with the C size_t type
-
-   These integer types usually correspond to 4 or 8 byte integers, 
-   depending on the Fortran compiler and corresponding HDF5 
-   C library definitions.
-   
-*  Each Fortran application must call the h5open_f subroutine to 
-   initialize the Fortran predefined datatypes before calling the HDF5 Fortran 
-   subroutines.  The application should call the h5close_f subroutine 
-   after all calls to the HDF5 Fortran Library.
-
-*  When a C application reads data stored from a Fortran program, the data 
-   will appear to be transposed due to the difference in the C - Fortran 
-   storage order.  For example, if Fortran writes a 4x6 two-dimensional dataset 
-   to the file, a C program will read it as a 6x4 two-dimensional dataset into 
-   memory.  The HDF5 C utilities h5dump and h5ls display transposed data, if
-   data is written from a Fortran program.
-
-*  Fortran indices are 1 based.
-
-============================
-FOR DEVELOPERS
-============================
-
-Procedure to add a new function
-----------------------------------
-
-(1) Edit the fortran/src/H5*ff.F90 file
-(2) Edit the fortran/src/H5*f.c file
-(3) Edit the fortran/src/H5f90proto.h file
-(4) Add the new function to fortran/src/hdf5_fortrandll.def.in
-
-Procedure for passing C variables to Fortran
----------------------------------------------
-
-(1) Find the C struct name you are interested in:
-	(a) src/H5public.h if it is a generic type, i.e. H5_*
-            or
-        (b) src/H5*public.h if is a specific type, i.e. H5*_
-
-(2) Put that structure into an array that will be passed to fortran in:
-        (a) fortran/src/H5_f.c (add to nh5init_flags_c subroutine)
-        (b) edit fortran/src/H5f90proto.h and edit nh5init_flags_c interface call
-
-(3) Edit the function call in fortran/src/H5_ff.F90
-        (a) edit the call:  FUNCTION h5init_flags_c
-        (b) edit h5init_flags_c call in h5open_f to match the number of arguments passing
-
-(4) add the size of the array and array to fortran/src/H5f90global.F90
-         - must match the size found it H5_f.c
-
-NOTE: To just add a default C value argument, do steps (2a) and (4)
-
-
-Procedure for adding a new file to the repository
---------------------------------------------------
-
-Add the name of the file to the:
-    (1) Makefile.am located in the same directory as the newfile
-    (2) CMakeLists.txt located in the same directory as the newfile
-
diff --git a/fortran/src/README.md b/fortran/src/README.md
new file mode 100644
index 0000000..229e546
--- /dev/null
+++ b/fortran/src/README.md
@@ -0,0 +1,159 @@
+Information about the Fortran APIs
+===================================
+
+This directory contains Fortran APIs for HDF5 Library functionality.
+A complete list of implemented Fortran subroutines can be found in the HDF5
+Reference Manual.
+
+About the source code organization
+----------------------------------
+
+The Fortran APIs are organized in modules parallel to the HDF5 Interfaces.
+Each module is in a separate file with the name H5\*ff.F90.  Corresponding C
+stubs are in the H5\*f.c files.  For example, the Fortran File APIs are in
+the file H5Fff.F90, and the corresponding C stubs are in the file H5Ff.c.
+
+Each module contains Fortran definitions of the constants, interfaces to
+the subroutines if needed, and the subroutines themselves.
+
+It is crucial for users to use constant names in their programs instead
+of the numerical values, as the constant names have values which are
+subject to change without notice.
+
+Quick overview of the Fortran APIs
+----------------------------------
+
+*  An in-depth description of each Fortran API and its parameters can
+   be found in the HDF5 Reference Manual. They tend to be summarized
+   from the C descriptions.
+
+*  The Fortran APIs come in the form of Fortran subroutines.
+
+*  Each Fortran subroutine name is derived from the corresponding C function
+   name by adding "_f" to the name.  For example, the name of the C function
+   to create an HDF5 file is H5Fcreate;  the corresponding Fortran subroutine
+   is h5fcreate_f.
+
+*  The parameter list for each Fortran subroutine usually has two more parameters
+   than the corresponding C function.  These additional parameters typically hold
+   the return value and an error code.  The order of the Fortran subroutine
+   parameters may differ from the order of the C function parameters.
+
+   The Fortran subroutine parameters are usually listed in the following order:
+
+      * required input parameters,
+      * output parameters, including return value and error code, and
+         optional input parameters.
+
+   For example, the C function to create a dataset has the following
+   prototype:
+
+       hid_t H5Dcreate2(hid_it loc_id, char *name, hid_t type_id,
+             hid_t space_id, hid_t link_creation_prp, hid_t dset_creation_prp,
+             hid_t dset_access_prop);
+
+   The corresponding Fortran subroutine has the following form:
+
+       SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &
+       hdferr, dset_creation_prp, link_creation_prp, dset_access_prop)
+
+   The first four parameters of the Fortran subroutine correspond to the
+   parameters of the C function. The fifth parameter, dset_id, is an output
+   parameter containing a valid dataset identifier, and the sixth
+   output parameter, hdferr, indicates successful completion.
+   The error code descriptions can be found in the subroutine descriptions
+   of the Reference Manual. The last three input parameters are optional
+   and can be omitted, in which case default values will be used.
+
+*  Parameters to the Fortran subroutines typically include
+   predefined datatypes (see the build-time generated file
+   H5fortran_types.F90 for a complete listing):
+
+        INTEGER(HID_T)      compares with hid_t type in HDF5 C APIs
+        INTEGER(HSIZE_T)    compares with hsize_t in HDF5 C APIs
+        INTEGER(HSSIZE_T)   compares with hssize_t in HDF5 C APIs
+        INTEGER(SIZE_T)     compares with the C size_t type
+
+   These integer types usually correspond to 4- or 8-byte integers,
+   depending on the Fortran compiler and corresponding HDF5
+   C library definitions.
+
+*  Before calling HDF5 Fortran subroutines, each Fortran application must initialize Fortran datatypes
+   by calling the h5open_f subroutine. After all calls to the HDF5 Fortran Library, the application
+   should call the h5close_f subroutine.
+
+*  All public APIs for the Reference Manual have Doxygen descriptions and should use parameter aliases when possible.
+
+*  When a C application reads data stored by a Fortran program, the data appears
+   to be transposed. This is because C and Fortran have different storage orders
+   (row-major and column-major, respectively). For instance, if a Fortran program
+   writes a 4x6 two-dimensional dataset to a file, a C program will read it into
+   memory as a 6x4 two-dimensional dataset. The HDF5 C utilities h5dump and h5ls
+   display transposed data if it was written from a Fortran program.
+
+*  It is important to note that in Fortran, the indexing of arrays starts at 1.
+
+
+FOR DEVELOPERS
+==============
+
+* The build system generates APIs compatible with Fortran 90 to handle the backward compatibility
+  of the older F90 APIs. During the configuration process, the build system determines all
+  valid integer and real KINDs, as well as the maximum decimal precision for reals and floats
+  in both Fortran and C.  To determine all the available kinds, the Fortran program
+  *PROGRAM FC_AVAIL_KINDS* is used, which is located in aclocal_fc.f90. The available KINDs
+  are stored in H5config_f.inc, a file processed during configuration time from
+  H5config_f.inc.in. Each program in m4/aclocal_fc.f90 is enclosed with a
+  "!---START-----+" line and a "!---END-------+" line, which are used as markers to
+  isolate each test program for the build systems.
+
+  The valid KINDs for integers and reals that are stored in H5config_f.inc are used in the H5_buildiface.F90 file located in the fortran/src directory. During the build process, H5_buildiface.F90 generates all the valid F90 KIND interfaces for the following APIs: h5awrite_f, h5aread_f, h5dwrite_f, h5dread_f, h5pset_fill_value_f, h5pget_fill_value_f, h5pset_f, h5pget_f, h5pregister_f, and h5pinsert_f. These APIs can handle up to and including rank seven arrays for all the found KINDs. Again, it's important to note that no new Fortran APIs should be added to H5_buildiface.F90 since new Fortran APIs should not use F90 specification but should instead use F2003. The source file generated by H5_buildiface.F90 is H5_gen.F90, which is the Fortran module H5_GEN, Figure 1. This module is included in the HDF5 module HDF5.F90.
+
+  <figure>
+  <!-- Xfig graphic -->
+    <img src="./FortBuildFlow.svg">
+    <figcaption>Figure 1: During the configure and build phases, Fortran files are generated and compiled. This overview explains the flow steps of the build process.</figcaption>
+  </figure>
+
+Procedure to add a new function
+--------------------------------
+
+> [!IMPORTANT]  
+> The use of C stubs (H5\*f.c) is no longer recommended. The C APIs should now be called from Fortran wrappers. C wrappers description exists for maintenance purposes and to create and understand alternative development options.
+
+1. Edit the fortran/src/H5\*ff.F90 file
+2. Edit the fortran/src/H5\*f.c file
+3. Edit the fortran/src/H5f90proto.h file
+4. Add the new function to fortran/src/hdf5_fortrandll.def.in
+
+Procedure for passing C variables to Fortran
+---------------------------------------------
+
+(1) Find the C struct name you are interested in:
+
+        (a) src/H5public.h if it is a generic type, i.e. H5_*
+            or
+        (b) src/H5*public.h if is a specific type, i.e. H5*_
+
+(2) Put that structure into an array that will be passed to Fortran in:
+
+        (a) fortran/src/H5_f.c (add to the h5init_flags_c subroutine)
+        (b) edit fortran/src/H5f90proto.h and edit h5init_flags_c interface call
+
+(3) Edit the function call in fortran/src/H5_ff.F90
+
+        (a) edit the call:  FUNCTION h5init_flags_c
+        (b) edit h5init_flags_c call in h5open_f to match the number of arguments being passed
+
+(4) Add the size of the array and array to fortran/src/H5f90global.F90, it must match the size found in H5_f.c
+
+> [!NOTE]  
+> To add a default C value argument, do steps (2a) and (4).
+
+
+Procedure for adding a new file to the repository
+--------------------------------------------------
+
+Add the name of the file to the:
+    (1) Makefile.am located in the same directory as the new file.
+    (2) CMakeLists.txt located in the same directory as the new file.