Docs: build_lcl_docs. Fixes an incompatibility with FPDoc 3.3.x.

* FPDoc 3.3.X changed the syntax for the --footer argument. It uses an ''@' prefix for file names and treats anythine else as text for the footer..  build_lcl_docs did not handle that syntax.  Since we do not know which version of FPDoc will be used, we must handle both.
* Accepts --footer=filename.ext for 3.2.X.
* Accepts --footer=@filename.ext for 3.3.X.
* Accepts --footer="Your text here" for 3.3.X.
* File name expansion and validation occurs in the setter for TFPDocRun.FooterFilename.
* Modifies README.txt and all of the script files (.bat, .sh) to document requirements and usage.

(cherry picked from commit 2f59545512)

docs/html/README.txt

@@ -1,23 +1,79 @@
-HTML documentation of Lazarus
+CHM and HTML Documentation for Lazarus
-=============================
+======================================
 
 This directory contains the tools to create the HTML and CHM documentation for
 Lazarus. The documentation is stored in fpdoc format in the docs/xml/ directory.
 
+The build_lcl_docs program requires a docs/chm directory which contains rtl.xct
+and fcl.xct. The process fails if either the directory or the files are missing.
+The process creates lcl and lazutils subdirectories for output.
+Update the content in locallclfooter.xml before starting the script.
+
+Scripts contain a path to the FPDoc program which may need to be updated
+to match your local installation. This allows either FPDoc version 3.2.X or
+3.3.X to be used to generate documentation formats.
+
+Note: It is recommended to use the FPDoc version from FPC trunk (main).
+If you are unlucky and got a buggy revision, you can try with the released
+FPDoc program.
+
+
 For UNIXes:
 
-The script build_html.sh will automatically create the whole HTML
+build_html.sh and build_chm.sh will automatically create the documentation for the
-documentation.
+output formats.
-Build build_lcl_docs.lpi
-../../lazbuild build_lcl_docs.lpi
 
-./build_lcl_docs --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc --fpcdocs=../chm --outfmt chm --footer locallclfooter.xml
+Build build_lcl_docs.lpi:
+  ../../lazbuild build_lcl_docs.lpi
+
+Update the PATH environment variable in build_chm.bat and build_html.bat for
+your local installation. Run the script(s), or run build_lcl_docs.exe directly.
+
+Run a script:
+  ./build_chm.sh
+  ./build_html.sh
+
+Run the program:
+  ./build_lcl_docs --fpdoc /path/to/trunk/fpdoc/fpdoc --fpcdocs=../chm --outfmt chm --footer locallclfooter.xml
 
-Note: It is recommened to use the fpdoc from fpc trunk. If you are unlucky and got a buggy revision, you can try with the released fpdoc.
 
 For Windows:
 
-Build the project build_lcl_docs.lpi, fix the PATH in the build_html.bat batch
+build_html.bat and build_chm.bat will automatically create the documentation for the
-script to your local installation and then run the script, or run
+output formats.
-build_lcl_docs.exe directly.
 
+Build build_lcl_docs.lpi:
+  ..\..\lazbuild.exe build_lcl_docs.lpi
+
+Update the PATH environment variable in build_chm.bat and build_html.bat for
+  your local installation. Run the script(s), or run build_lcl_docs.exe directly.
+
+Run a script:
+  .\build_chm.bat
+  .\build_html.bat
+
+Run the program:
+  .\build_lcl_docs.exe --fpdoc \path\to\trunk\fpdoc --fpcdocs=..\chm --outfmt chm --footer locallclfooter.xml
+  .\build_lcl_docs.exe --fpdoc \path\to\trunk\fpdoc --fpcdocs=..\chm --outfmt html --footer locallclfooter.xml
+
+
+FPDoc Version Differences
+
+When using FPDoc 3.3.1 or higher, the syntax for the --footer argument was changed.
+
+For FPDoc version 3.2.X, the syntax is:
+
+  --footer=path/to/filename.ext
+
+For  FPDoc verions 3.3.X, the syntax requires an @ symbol as a prefix for the file
+name. For example:
+
+  --footer=@path/to/filename.ext
+
+FPDoc verions 3.3.X allows a string of text to used as the footer. For example:
+
+  --footer="(c) 2022. All rights reserved."
+
+
+All of the scripts have a commented version of the various command using the FPDoc 3.3.X
+syntax. Use the one needed for your system and FPDoc version.

docs/html/build_chm.bat

@@ -1,11 +1,31 @@
 REM
-REM Builds all Lazarus docs and pack them in one .chm file
+REM Builds  Lazarus documentation for LCL and LazUtils in CHM format.
+REM
+REM Requires a $(LazarusDir)\docs\chm directory which contains rtl.xct and fcl.xct.
+REM Process fails if either the directory or the files are missing.
+REM Process creates .\lcl and .\lazutils subdirectories for CHM output.
+REM Update the content in locallclfooter.xml before starting the script.
 REM
 REM Notes:
 REM
 REM 1 - If necessary, please fix the path so it finds fpdoc.exe (normally in your fpc compiler dir)
 REM 2 - Before running this file, first compile the project build_lcl_docs.lpi
+REM ..\..\lazbuild.exe build_lcl_docs.lpi
 REM
-PATH=D:\programming\fpc\bin\i386-win32\;%PATH%
+
-build_lcl_docs.exe --outfmt chm
+REM PATH=C:\lazarus\fpc\3.2.2\bin\x86_64-win64;%PATH%
+PATH=C:\fpc331\fpc\bin\x86_64-win64;%PATH%
+
+REM build chm output without footers
+.\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm
+
+REM For FPDoc 3.2.X: build chm output with footers in locallclfooter.xml
+REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer=locallclfooter.xml
+
+REM For FPDoc 3.3.X: build chm output with footers in locallclfooter.xml
+REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer=@locallclfooter.xml
+
+REM For FPDoc 3.3.X: build chm output with footer text
+REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer="(c) 2022. All rights reserved."
+
 pause

docs/html/build_chm.sh

@@ -1,7 +1,30 @@
 #!/bin/bash
-# Builds all Lazarus docs and pack them in one .chm file
-#
-../../lazbuild build_lcl_docs.lpi
-./build_lcl_docs --outfmt chm --fpcdocs=../chm --footer locallclfooter.xml
 
-# Preferably: use trunk fpdoc: --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc
+#
+# Builds  Lazarus documentaiton for LCL and LazUtils in CHM format.
+# Requires a $(LazarusDir)/docs/chm directory which contains rtl.xct and fcl.xct.
+# Process fails if either the directory or the files are missing.
+# Process creates ./lcl and ./lazutils subdirectories for CHM output.
+# Update the content in locallclfooter.xml if needed before starting the script.
+#
+
+# Path to the fpdoc program
+# The trunk (main) version of fpdoc is recommended.
+# CHANGE THIS TO A PATH VALID FOR YOUR SYSTEM AND FPDOC VERSION.
+#fpdocpath="../../fpc/3.2.2/bin/x86_64-win64"
+fpdocpath="../../../fpc331/fpc/bin/x86_64-win64"
+
+# rebuild if needed
+#../../lazbuild build_lcl_docs.lpi
+
+# build chm output without footers
+./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc
+
+# For FPDoc 3.2.X: build chm output with footers in locallclfooter.xml
+#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=locallclfooter.xml
+
+# For FPDoc 3.3.X: build chm output with footers in locallclfooter.xml
+#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=@locallclfooter.xml
+
+# For FPDoc 3.3.X: build chm output with footer text
+#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer="(c) Copyright 2022. All rights reserved."

docs/html/build_html.bat

@@ -1,11 +1,31 @@
 REM
-REM Builds all Lazarus docs
+REM Builds Lazarus documentation for LCL and LazUtils in HTML format.
+REM
+REM Requires a $(LazarusDir)\docs\chm directory which contains rtl.xct and fcl.xct.
+REM Process fails if either the directory or the files are missing.
+REM Process creates .\lcl and .\lazutils subdirectories for HTML output.
+REM Update the content in locallclfooter.xml before starting the script.
 REM
 REM Notes:
 REM
 REM 1 - If necessary, please fix the path so it finds fpdoc.exe (normally in your fpc compiler dir)
 REM 2 - Before running this file, first compile the project build_lcl_docs.lpi
+REM ..\..\lazbuild.exe build_lcl_docs.lpi
 REM
-PATH=C:\Programas\lazarus22\fpc\2.2.0\bin\i386-win32;%PATH%
+
-build_lcl_docs.exe
+REM PATH=C:\lazarus\fpc\3.2.2\bin\x86_64-win64;%PATH%
-pause
+PATH=C:\fpc331\fpc\bin\x86_64-win64;%PATH%
+
+REM build html output without footers
+REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm
+
+REM For FPDoc 3.2.X: build html output with footers in locallclfooter.xml
+REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer=locallclfooter.xml
+
+REM For FPDoc 3.3.X: build html output with footers in locallclfooter.xml
+.\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer=@locallclfooter.xml
+
+REM For FPDoc 3.3.X: build html output with footer text
+REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer="(c) 2022. All rights reserved."
+
+pause

docs/html/build_html.sh

@@ -1,14 +1,30 @@
 #!/bin/bash
-# Builds all Lazarus docs and pack them in one .chm file
-#
-# Notes:
-#
-# Before running this file, first compile the project build_lcl_docs.lpi
-#
-# In order to link to RTL and FCL, place rtl.xct and fcl.xct in ../chm/
-# 
-# This uses the fpdoc in PATH. See README.txt
-# 
-./build_lcl_docs --fpcdocs=../chm --outfmt html
 
+#
+# Builds  Lazarus documentaiton for LCL and LazUtils in HTML format.
+# Requires a $(LazarusDir)/docs/chm directory which contains rtl.xct and fcl.xct.
+# Process fails if either the directory or the files are missing.
+# Process creates ./lcl and ./lazutils subdirectories for HTML output.
+# Update the content in locallclfooter.xml if needed before starting the script.
+#
 
+# Path to the fpdoc program
+# The trunk (main) version of fpdoc is recommended.
+# CHANGE THIS TO A PATH VALID FOR YOUR SYSTEM AND FPDOC VERSION.
+#fpdocpath="../../fpc/3.2.2/bin/x86_64-win64"
+fpdocpath="../../../fpc331/fpc/bin/x86_64-win64"
+
+# rebuild if needed
+#../../lazbuild build_lcl_docs.lpi
+
+# build html output without footers
+./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc
+
+# For FPDoc 3.2.X: build html output with footers in locallclfooter.xml
+#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=locallclfooter.xml
+
+# For FPDoc 3.3.X: build html output with footers in locallclfooter.xml
+#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=@locallclfooter.xml
+
+# For FPDoc 3.3.X: build html output with footer text
+#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer="(c) Copyright 2022. All rights reserved."

docs/html/build_lcl_docs.lpr

@@ -239,11 +239,41 @@ begin
   FCSSFile:=AValue;
 end;
 
+{ Handles fpdoc 3.3.1 changed usage of the --footer argument. It can be
+   either a string with the content for the footer, or a file name when
+   prefixed with @. Handles both old and new syntax.
+   @ cannot be included in the call to TrimAndExpandFilename.
+   All file name validation occurs here. }
 procedure TFPDocRun.SetFooterFilename(AValue: String);
+var
+  vFilename: String;
 begin
-  AValue:=TrimAndExpandFilename(AValue);
+  vFileName := '';
-  if FFooterFilename=AValue then Exit;
+  if (AValue <> '') then
-  FFooterFilename:=AValue;
+  begin
+    // check for fpdoc 3.3.1 file name with @ prefix
+    if (AValue[1] = '@') then
+    begin
+      vFilename := TrimAndExpandFilename(Copy(AValue, 2, Length(AValue)-1));
+      if not FileExistsUTF8(vFileName) then
+         AValue := '"Footer file not found: @' + vFileName + '"'
+      else
+         AValue := '@' + vFilename;
+    end
+    // wrap anything with spaces in Quote characters when needed
+    else if (Pos(' ', AValue) <> 0) and (aValue[1] <> '"') then
+    begin
+     AValue :='"' + AValue + '"';
+    end
+    // expand and validate file name without the @ prefix
+    else
+    begin
+      vFilename := TrimAndExpandFilename(AValue);
+      if FileExistsUTF8(vFileName) then AValue := vFilename;
+    end;
+  end;
+  if FFooterFilename = AValue then Exit;
+  FFooterFilename := AValue;
 end;
 
 procedure TFPDocRun.SetPasSrcDir(AValue: string);
@@ -349,7 +379,10 @@ begin
       Params.Add('--css-file='+ExtractFileName(CSSFile)); // the css file is copied to the OutDir
   end;
 
-  if (FooterFilename<>'') and FileExistsUTF8(FooterFilename) then
+  { In fpdoc 3.3.1 footerfilename is no longer just a file name. It can be the
+    footer text or a file name when prefixed with @.
+    Validation and quoting handled in the property setter. }
+  if (FooterFilename<>'') then // and FileExistsUTF8(FooterFilename) then
     Params.Add('--footer='+FooterFilename);
 
   if EnvParams<>'' then