improve script documentation

utils/cronjobs_osgeo_lxd/cron_grass_current_stable_build_binaries.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# script to build GRASS GIS new current binaries + addons + progman from the `releasebranch_8_4` binaries
+# script to build GRASS GIS new current binaries + addons + progman from the `releasebranch_8_4` branch
 # (c) 2002-2024, GPL 2+ Markus Neteler <neteler@osgeo.org>
 #
 # GRASS GIS github, https://github.com/OSGeo/grass
@@ -15,7 +15,7 @@
 # - generates the user 8 HTML manuals
 # - injects DuckDuckGo search field
 
-# Preparations, on server:
+# Preparations, on server (neteler@grasslxd:$):
 #  - Install PROJ incl Datum shift grids
 #  - Install GDAL
 #  - Install apt-get install texlive-latex-extra python3-sphinxcontrib.apidoc
@@ -31,7 +31,9 @@
 #    ln -s /var/www/code_and_data/grass84 .
 #
 #################################
-PATH=/home/neteler/binaries/bin:/usr/bin:/bin:/usr/X11R6/bin:/usr/local/bin
+# variables for build environment (grass.osgeo.org specific)
+MAINDIR=/home/neteler
+PATH=$MAINDIR/bin:/usr/bin:/usr/local/bin
 
 GMAJOR=8
 GMINOR=4
@@ -40,7 +42,6 @@ DOTVERSION=$GMAJOR.$GMINOR
 VERSION=$GMAJOR$GMINOR
 GVERSION=$GMAJOR
 
-###################
 # fail early
 set -e
 
@@ -49,9 +50,7 @@ CFLAGSSTRING='-O2'
 CFLAGSSTRING='-Werror-implicit-function-declaration -fno-common'
 LDFLAGSSTRING='-s'
 
-#define several paths if required:
-
-MAINDIR=/home/neteler
+# define GRASS GIS build related paths:
 # where to find the GRASS sources (git clone):
 SOURCE=$MAINDIR/src/
 BRANCH=releasebranch_${GMAJOR}_$GMINOR
@@ -78,18 +77,17 @@ halt_on_error()
   exit 1
 }
 
+# function to configure for compilation
 configure_grass()
 {
 
-# which package?
-#   --with-mysql --with-mysql-includes=/usr/include/mysql --with-mysql-libs=/usr/lib/mysql \
-
-# cleanup
+# cleanup from previous run
 rm -f config_$GMAJOR.$GMINOR.git_log.txt
 
 # reset i18N POT files to git, just to be sure
 git checkout locale/templates/*.pot
 
+# configure for compilation
 CFLAGS=$CFLAGSSTRING LDFLAGS=$LDFLAGSSTRING ./configure \
   --with-cxx \
   --with-sqlite \
@@ -104,6 +102,7 @@ CFLAGS=$CFLAGSSTRING LDFLAGS=$LDFLAGSSTRING ./configure \
   --with-pdal \
   --with-fftw \
   --with-nls \
+  --with-libsvm \
   --with-blas --with-blas-includes=/usr/include/atlas/ \
   --with-lapack --with-lapack-includes=/usr/include/atlas/ \
   --with-zstd \
@@ -114,12 +113,12 @@ CFLAGS=$CFLAGSSTRING LDFLAGS=$LDFLAGSSTRING ./configure \
  fi
 }
 
-######## update from git:
+# be sure the directories are there
 
 mkdir -p $TARGETDIR
 cd $GRASSBUILDDIR/
 
-# clean up
+# clean up from previous run
 touch include/Make/Platform.make
 $MYMAKE distclean > /dev/null 2>&1
 
@@ -128,31 +127,30 @@ git status | grep '.rst' | xargs rm -f
 rm -rf lib/python/docs/_build/ lib/python/docs/_templates/layout.html
 rm -f config_${DOTVERSION}.git_log.txt ChangeLog
 
-# be sure to be on branch
+# be sure to be on the right branch
 git checkout $BRANCH
 
 echo "git update..."
 git fetch --all --prune && git checkout $BRANCH && git pull --rebase || halt_on_error "git update error!"
 git status
 
-# for the contributors list in CMS
+# for the "contributors list" in old CMSMS (still needed for hugo?)
 cp -f *.csv $TARGETMAIN/uploads/grass/
 
-#configure
+# configure for compilation
 echo "configuring"
 configure_grass || (echo "$0: an error occurred" ; exit 1)
 pwd
 ARCH=`cat include/Make/Platform.make | grep ^ARCH | cut -d'=' -f2 | xargs`
 
-########  now GRASS is prepared ####################
-
-#### next compile GRASS:
+########  now GRASS GIS source code is prepared ####################
+#### next compile GRASS, takes a while
 $MYMAKE
 
 
 echo "GRASS $VERSION compilation done"
 
-# now GRASS is prepared ############################################
+########  now GRASS GIS binaries are prepared ####################
 
 #### create module overview (https://trac.osgeo.org/grass/ticket/1203)
 #sh utils/module_synopsis.sh
@@ -175,9 +173,11 @@ rm -f $TARGETHTMLDIR/*.*
 cp -rp dist.$ARCH/docs/html/* $TARGETHTMLDIR/
 echo "Copied pygrass progman to http://grass.osgeo.org/grass${VERSION}/manuals/libpython/"
 
+# search to be improved with mkdocs or similar; for now we use DuckDuckGo
 echo "Injecting DuckDuckGo search field into manual main page..."
 (cd $TARGETHTMLDIR/ ; sed -i -e "s+</table>+</table><\!\-\- injected in cron_grass8_relbranch_build_binaries.sh \-\-> <center><iframe src=\"https://duckduckgo.com/search.html?site=grass.osgeo.org%26prefill=Search%20manual%20pages%20at%20DuckDuckGo\" style=\"overflow:hidden;margin:0;padding:0;width:410px;height:40px;\" frameborder=\"0\"></iframe></center>+g" index.html)
 
+# copy important files to web space
 cp -p AUTHORS CHANGES CITING CITATION.cff COPYING GPL.TXT INSTALL.md REQUIREMENTS.md $TARGETDIR/
 
 # clean wxGUI sphinx manual etc
@@ -233,19 +233,19 @@ cat i18n_stats.txt | grep lib  > i18n_stats_libs.txt
 cat i18n_stats.txt | grep wxpy > i18n_stats_wxpy.txt
 cd $GRASSBUILDDIR
 
-# package the package
+# package the GRASS GIS package
 $MYMAKE bindist
 if [ $? -ne 0 ] ; then
    halt_on_error "make bindist."
 fi
 
-#report system:
+# report system:
 echo "System:
 $ARCH, compiled with:" > grass-$DOTVERSION\_$ARCH\_bin.txt
 ## echo "Including precompiled $GDALVERSION library for r.in.gdal" >> grass-$DOTVERSION\_$ARCH\_bin.txt
 gcc -v 2>&1 | grep -v Reading >> grass-$DOTVERSION\_$ARCH\_bin.txt
 
-# clean old version off
+# clean old version from previous run
 rm -f $TARGETDIR/grass-$DOTVERSION\_$ARCH\_bin.txt
 rm -f $TARGETDIR/grass-${DOTVERSION}*.tar.gz
 rm -f $TARGETDIR/grass-${DOTVERSION}*install.sh
@@ -273,7 +273,7 @@ cd $GRASSBUILDDIR
 # compile addons
 
 # update addon repo (addon repo has been cloned twice on the server to
-#   separate grass7 and grass8 addon compilation)
+# have separate grass7 and grass8 addon compilation)
 (cd ~/src/grass$GMAJOR-addons/; git checkout grass$GMAJOR; git pull origin grass$GMAJOR)
 # compile addons
 cd $GRASSBUILDDIR
@@ -298,14 +298,15 @@ for dir in `find ~/.grass$GMAJOR/addons -maxdepth 1 -type d`; do
     fi
 done
 sh ~/cronjobs/grass-addons-index.sh $GMAJOR $GMINOR $GPATCH $TARGETHTMLDIR/addons/
+# copy over hamburger menu assets
 cp $TARGETHTMLDIR/grass_logo.png \
    $TARGETHTMLDIR/hamburger_menu.svg \
    $TARGETHTMLDIR/hamburger_menu_close.svg \
    $TARGETHTMLDIR/grassdocs.css \
    $TARGETHTMLDIR/addons/
 chmod -R a+r,g+w $TARGETHTMLDIR 2> /dev/null
 
-# cp logs from ~/.grass$GMAJOR/addons/logs/
+# copy over logs from ~/.grass$GMAJOR/addons/logs/
 mkdir -p $TARGETMAIN/addons/grass$GMAJOR/logs/
 cp -p ~/.grass$GMAJOR/addons/logs/* $TARGETMAIN/addons/grass$GMAJOR/logs/