Further documentation improvements

[edwardhartnett]

The documentation can be improved by:

• Changing the rest of the text from upper-case, so that the docs are not SHOUTING so much.
• I couldn't get automatic links to subroutines working using their upper-case names. So I can use sptrun() and I get a link, but when I change it to SPTRUN() the link does not happen. It would be better to make the upper-case links work, since this is all F77 code and people are used to it being in upper-case.
• Examples can be much better handled.

[GeorgeVandenberghe-NOAA]

So are you changing SPTRUN(.. to lowercase?. This does sound like a good idea to standardize the case of our codes

Fortran is case insensitive as you know so perhaps we should just run everything through tr to change everything to lowercase
and be done with it. Actually the break from uppercase to lowercase began in the 70s and early 80s and code that is all uppercase usually has a fortran 66 pedigree. Okay, maybe I need to take that back, code with #ifdefs might have case sensitive content.. I don't know if DEFINED settings used by cpp are case sensitive. IMO (and I may be wrong) fortran dependence on cpp to do nifty editing things for us at compile time is dangerous since the cpp API has drifted and will continue to drift. We've already been devastated by one such change with WRF which made it unbuildable on newer linux systems. cpp is supposed to support C codes. IMO (again maybe I'm ignorant) we should use fpp exclusively if we want preprocessing since that at least considered fortran in its design.

[edwardhartnett]

Actually it is a little more inconsistent than I would like. ;-)

If there is a function called func_1(), then in Fortran I can write func_1() or FUNC_1, or even FuNc_1() and it will work. But in doxygen, only func_1() will generate the auto-link to the function documentation.

In other words, Fortran does not care, but doxygen demands all lower-case function and subroutine names, to get links working., And links are really really great. So it's worth lower-casing the names in the docs, so that the links work, and hoping our users understand that fortran does not notice case at all.

[edwardhartnett]

In terms of pre-processing, it seems that all the fortran compilers have settled on cpp, and it is pretty standardized when used correctly (yes, it is all case sensitive!)

Pre-processor commands are great in the correct places, but should not be over-used. What should be understood is that every time you use an #ifdef you are requiring another CI run, so this gets expensive quick, or, more typically, masses of ifdefs are added but never used in testing, which is just as bad as untested code.

Preprocessor code is great when substituting a value in from configure (like the version number), or handling build options (like openmp on or off).

[edwardhartnett]

I will also note that typically fortran 77 may be all upper-case, but Fortran 90 is usually lower-case code, IME. This is simply because the lower-case letters were introduced before F77, so by F90, everyone has them. ;-)

[GeorgeVandenberghe-NOAA]

Well my 15 second suggestion to use tr to change cases will break stuff, in particular any formatted writes that fortran does. They'll still survive execution fine but capitalization which we want in a print to make it readable, would be destroyed if everything went to lowercase so I'll take that back. But making all of the code lowercase is a good idea.

[edwardhartnett]

We cannot just blindly make the code lower-case, as you note, but can do so with care, once good testing is in place.

But for this batch of changes, only doxygen is being worked on and lower-cased. Code is remaining untouched.

[edwardhartnett]

@AlexanderRichert-NOAA I have added you to this issue. Thanks for the help!

Please mention this issue in your documentation PRs.