paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-08-12 14:29:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Docs: Modifies build_lcl_docs and scripts.Address an issue in #28500."

Browse Source 
This reverts commit 8ac2328b60.
This commit is contained in:
dsiders 2021-10-29 18:10:51 +01:00
parent 66db2ec9f6
commit 92b66dbfc5
11 changed files with 131 additions and 466 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/html/build_chm.bat
View File

@ -1,107 +1,11 @@
echo off
cls
REM ========================================================================
REM Builds LCL and LazUtils documentation in CHM format
REM REM
REM use the trunk version of fpdoc if possible: REM Builds all Lazarus docs and pack them in one .chm file
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
REM REM
REM Adjust any paths used in the batch file for use on your system. REM Notes:
REM If needed, compile the build_lcl_docs.lpi project before running this script. REM
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 ======================================================================== REM
REM creates and uses version.inc, commit.inc, date.inc for values used in footers PATH=D:\programming\fpc\bin\i386-win32\;%PATH%
REM git describe doesn't return a usable branch or tag name like 2.3.0 build_lcl_docs.exe --outfmt chm
REM main-2_3 and fixes_2_2 are not what is needed for the doc files pause
REM usable branches or tags like 2.3.0 or 2.2.0-RC2 do not exist
REM just get or set the text used for version.inc
REM ========================================================================
set verno=2.3.0
echo|(set /p=%verno%)> version.inc
REM set verno=<version.inc
REM ========================================================================
REM svn info https://svn.freepascal.org/svn/lazarus/trunk --show-item revision > ./revision.inc
REM not using svn or svn2revision
REM change gitpath to the local repo on your system
REM get hash for the commit used in the build
REM ========================================================================
set gitpath="c:\usr\work\git-lazarus"
git -C %gitpath% describe --all --long > describe.txt
for /f "delims=-g tokens=1-3" %%a in (describe.txt) do set commit=%%c
echo|(set /p=%commit%) > commit.inc
del describe.txt
REM ========================================================================
REM get datestamp for the footer
REM ========================================================================
set dt=%date:~10,4%-%date:~4,2%-%date:~7,2%
echo|(set /p=%dt%) > date.inc
REM ========================================================================
REM rewrite footer files for LCL
REM locallclfooter.xml is the version without a link to the online HTML
REM chmlclfooter.xml includes a link to the online HTML
REM ========================================================================
echo|(set /p="<hr class='footer-sep'/>" & echo.) > locallclfooter.xml
echo|(set /p="<table class='footer'>" & echo.) >> locallclfooter.xml
echo|(set /p="<tr>" & echo.) >> locallclfooter.xml
echo|(set /p="<td class='footer-doc'>Lazarus Component Library (LCL)</td>" & echo.) >> locallclfooter.xml
echo|(set /p="<td class='footer-ver'>Version %verno%-%commit%</td>" & echo.) >> locallclfooter.xml
echo|(set /p="<td class='footer-date'>Generated %dt%</td>" & echo.) >> locallclfooter.xml
echo|(set /p="</tr>" & echo.) >> locallclfooter.xml
echo|(set /p="</table>" & echo.) >> locallclfooter.xml
REM chm footer for releases (no commit info - assumes the tag is enough)
echo|(set /p="<hr class='footer-sep'/>" & echo.) > chmlclfooter.xml
echo|(set /p="<table class='footer'>" & echo.) >> chmlclfooter.xml
echo|(set /p="<tr>" & echo.) >> chmlclfooter.xml
echo|(set /p="<td class='footer-doc'>Lazarus Component Library (LCL)</td>" & echo.) >> chmlclfooter.xml
echo|(set /p="<td class='footer-ver'>Version %verno% (%dt%)</td>" & echo.) >> chmlclfooter.xml
echo|(set /p="<td class='footer-date'>" & echo.) >> chmlclfooter.xml
echo|(set /p="<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>" & echo.) >> chmlclfooter.xml
echo|(set /p="</td>" & echo.) >> chmlclfooter.xml
echo|(set /p="</tr>" & echo.) >> chmlclfooter.xml
echo|(set /p="</table>" & echo.) >> chmlclfooter.xml
REM ========================================================================
REM rewrite footer files for LazUtils
REM locallazutilsfooter.xml is the version without a link to the online HTML
REM chmlazutilsfooter.xml includes a link to the online HTML
REM ========================================================================
echo|(set /p="<hr class='footer-sep'/>" & echo.) > locallazutilsfooter.xml
echo|(set /p="<table class='footer'>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="<tr>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="<td class='footer-doc'>Lazarus Utilities (LazUtils)</td>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="<td class='footer-ver'>Version %verno%-%commit%</td>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="<td class='footer-date'>Generated %dt%</td>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="</tr>" & echo.) >> locallazutilsfooter.xml
echo|(set /p="</table>" & echo.) >> locallazutilsfooter.xml
REM chm footer (no commit info - assumes the tag is enough)
echo|(set /p="<hr class='footer-sep'/>" & echo.) > chmlazutilsfooter.xml
echo|(set /p="<table class='footer'>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="<tr>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="<td class='footer-doc'>Lazarus Utilties (LazUtils)</td>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="<td class='footer-ver'>Version %verno% (%dt%)</td>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="<td class='footer-date'>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="</td>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="</tr>" & echo.) >> chmlazutilsfooter.xml
echo|(set /p="</table>" & echo.) >> chmlazutilsfooter.xml
REM path to the fpdoc executable
set fpdocpath="c:\lazarus\fpc\3.2.0\bin\x86_64-win64"
REM ========================================================================
REM build the CHM output format with the desired footers
REM ========================================================================
echo.
echo Building LCL, LazUtils documentation in CHM format... this can take some time.
echo.
REM build_lcl_docs.exe --outfmt=chm --footer=chmlclfooter.xml --fpcdocs=../chm --fpdoc=%fpdocpath%/fpdoc.exe --warnings --verbose 1>build_chm.log 2>&1
build_lcl_docs.exe --outfmt=chm --fpcdocs=../chm --footer=chmlclfooter.xml --fpdoc=%fpdocpath%/fpdoc.exe --warnings --verbose 2>&1

105
docs/html/build_chm.sh
View File

@ -1,102 +1,7 @@
#!/bin/bash #!/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 and LazUtils CHM documentation
# preferably: use trunk fpdoc: --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc
# run ../../lazbuild ./build_lcl_docs.lpi to build .exe when needed
# change any path information used in this script for your system
#==============================================================
#==============================================================
# uses version.inc, commit.inc, date.inc for values used in footers
# git describe doesn't return a usable branch or tag name like 2.3.0
# main-2_3 and fixes_2_2 are not what is needed for the doc files
# usable branches or tags like 2.3.0 or 2.2.0-RC2 do not exist
# just get or set the text used for version.inc
#==============================================================
verno="2.3.0"
echo $verno > version.inc
#verno=`cat version.inc | dos2unix --`
#==============================================================
#svn info https://svn.freepascal.org/svn/lazarus/trunk --show-item revision > ./revision.inc
# change gitpath to the local repo on your system
# get hash for the commit used in the build
#==============================================================
gitpath="c:/usr/work/git-lazarus"
commit=`git -C $gitpath describe --all --long | cut -d "-" -f 3 | cut -b "2-"`
echo $commit > ./commit.inc
#==============================================================
# get datestamp for the footer
#==============================================================
dt=`date +"%Y-%m-%d"`
echo $dt > ./date.inc
#==============================================================
# rewrite footer files for LCL
# locallclfooter.xml is the version without a link to the online HTML
# chmlclfooter.xml includes a link to the online HTML
#==============================================================
cat <<EOT > ./locallclfooter.xml
<hr class="footer-sep"/>
<table class="footer">
<tr>
<td class="footer-doc">Lazarus Component Library (LCL)</td>
<td class="footer-ver">Version $verno-$commit</td>
<td class="footer-date">Generated $dt</td>
</tr>
</table>
EOT
# chm footer for releases (no commit info - assumes the tag is enough)
cat <<EOT > ./chmlclfooter.xml
<hr class="footer-sep"/>
<table class="footer">
<tr>
<td class="footer-doc">Lazarus Component Library (LCL)</td>
<td class="footer-ver">Version $verno ($dt)</td>
<td class="footer-date">
<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>
</td>
</tr>
</table>
EOT
#==============================================================
# rewrite footer files for LazUtils
# locallazutilsfooter.xml is the version without a link to the online HTML
# chmlazutilsfooter.xml includes a link to the online HTML
#==============================================================
cat <<EOT > ./locallazutilsfooter.xml
<hr class="footer-sep"/>
<table class="footer">
<tr>
<td class="footer-doc">Lazarus Utilities (LazUtils)</td>
<td class="footer-ver">Version $verno-$commit</td>
<td class="footer-date">Generated $dt</td>
</tr>
</table>
EOT
# chm footer for releases (no commit info - assumes the tag is enough)
cat <<EOT > ./chmlazutilsfooter.xml
<hr class="footer-sep"/>
<table class="footer">
<tr>
<td class="footer-doc">Lazarus Utilities (LazUtils)</td>
<td class="footer-ver">Version $verno ($dt)</td>
<td class="footer-date">
<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>
</td>
</tr>
</table>
EOT
# path to the fpdoc executable
fpdocpath="c:/lazarus/fpc/3.2.0/bin/x86_64-win64"
#==============================================================
# build the CHM output format with the desired footers
#==============================================================
./build_lcl_docs.exe --outfmt=chm --fpcdocs=../chm --footer chmlclfooter.xml --fpdoc=$fpdocpath/fpdoc.exe --warnings --verbose 2>&1 | tee ./build_chm.log

35
docs/html/build_html.bat
View File

@ -1,30 +1,11 @@
echo off
cls
REM ========================================================================
REM Builds LCL and LazUtils documentation in HTML format
REM ========================================================================
REM REM
REM use the trunk version of fpdoc if possible: REM Builds all Lazarus docs
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
REM REM
REM Adjust any paths used in the batch file for use on your system. REM Notes:
REM If needed, compile the build_lcl_docs.lpi project before running this script.
REM REM
REM Run build_chm.bat first. It (re-)generates the footer files with version and revision info. REM 1 - If necessary, please fix the path so it finds fpdoc.exe (normally in your fpc compiler dir)
REM ======================================================================== REM 2 - Before running this file, first compile the project build_lcl_docs.lpi
REM
REM path to the fpdoc executable PATH=C:\Programas\lazarus22\fpc\2.2.0\bin\i386-win32;%PATH%
set fpdocpath="c:\lazarus\fpc\3.2.0\bin\x86_64-win64" build_lcl_docs.exe
pause
echo.
echo Building LCL, LazUtils documentation in HTML format... this can take some time.
echo.
REM build_lcl_docs.exe --outfmt html --css-file fpdoc.css --fpcdocs ..\chm --footer locallclfooter.xml --fpdoc %fpdocpath%\fpdoc.exe --warnings --verbose 1>build_html.log 2>&1
build_lcl_docs.exe --outfmt html --css-file fpdoc.css --fpcdocs ..\chm --footer locallclfooter.xml --fpdoc %fpdocpath%\fpdoc.exe --warnings --verbose 2>&1
REM use custom css instead of the built in one
copy lazutils\fpdoc.css lazutils\lazutils\
copy lcl\fpdoc.css lcl\lcl\

19
docs/html/build_html.sh
View File

@ -1,13 +1,12 @@
#!/bin/bash #!/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/
#
./build_lcl_docs --fpcdocs=../chm --outfmt html
# run build_chm.sh first... it generates the footer files with version and revision info
# change any path information used in this script for your system
fpdocpath="c:/lazarus/fpc/3.2.0/bin/x86_64-win64"
# build html output format using locallclfooter.xml, locallazutilsfooter.xml for footer content
./build_lcl_docs.exe --outfmt=html --css-file=fpdoc.css --fpcdocs=../chm --footer locallclfooter.xml --fpdoc=$fpdocpath/fpdoc.exe --warnings --verbose 2>&1 | tee ./build_html.log
# use custom css instead of the built in one
cp lazutils/fpdoc.css lazutils/lazutils/
cp lcl/fpdoc.css lcl/lcl/

16
docs/html/build_lcl_docs.lpi
View File

@ -1,17 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<CONFIG> <CONFIG>
<ProjectOptions> <ProjectOptions>
<Version Value="12"/> <Version Value="11"/>
<PathDelim Value="\"/> <PathDelim Value="\"/>
<General> <General>
<Flags> <Flags>
<MainUnitHasCreateFormStatements Value="False"/>
<MainUnitHasTitleStatement Value="False"/>
<MainUnitHasScaledStatement Value="False"/>
<LRSInOutputDirectory Value="False"/> <LRSInOutputDirectory Value="False"/>
<CompatibilityMode Value="True"/>
</Flags> </Flags>
<SessionStorage Value="InIDEConfig"/> <SessionStorage Value="InIDEConfig"/>
<MainUnit Value="0"/>
<Title Value="build_lcl_docs"/> <Title Value="build_lcl_docs"/>
</General> </General>
<BuildModes Count="1"> <BuildModes Count="1">
@ -22,13 +19,13 @@
</PublishOptions> </PublishOptions>
<RunParams> <RunParams>
<local> <local>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T &apos;Lazarus Run Output&apos; -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/> <LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T 'Lazarus Run Output' -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
</local> </local>
<FormatVersion Value="2"/> <FormatVersion Value="2"/>
<Modes Count="1"> <Modes Count="1">
<Mode0 Name="default"> <Mode0 Name="default">
<local> <local>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T &apos;Lazarus Run Output&apos; -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/> <LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T 'Lazarus Run Output' -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
</local> </local>
</Mode0> </Mode0>
</Modes> </Modes>
@ -63,10 +60,5 @@
<UseAnsiStrings Value="False"/> <UseAnsiStrings Value="False"/>
</SyntaxOptions> </SyntaxOptions>
</Parsing> </Parsing>
<Linking>
<Debugging>
<GenerateDebugInfo Value="False"/>
</Debugging>
</Linking>
</CompilerOptions> </CompilerOptions>
</CONFIG> </CONFIG>

103
docs/html/build_lcl_docs.lpr
View File

@ -1,9 +1,7 @@
program update_lcl_docs; program update_lcl_docs;
{ { Runs FPC's fpdoc document generator to generate LCL documentation,
Runs FPC's fpdoc document generator to generate LCL and LazUtils documentation e.g. in CHM format }
in CHM or HTML format
}
{$mode objfpc}{$H+} {$mode objfpc}{$H+}
{$IFDEF MSWINDOWS} {$IFDEF MSWINDOWS}
@ -24,7 +22,7 @@ var
DefaultXCTDir: String; DefaultXCTDir: String;
DefaultFPDocParams: string = ''; DefaultFPDocParams: string = '';
DefaultOutFormat: string = 'html'; DefaultOutFormat: string = 'html';
DefaultFooterFilename: string = 'locallclfooter.xml'; DefaultFooterFilename: string = 'locallclfooter.xml'; // ToDo
type type
TFPDocRunStep = ( TFPDocRunStep = (
@ -65,8 +63,6 @@ type
FXCTFile: string; FXCTFile: string;
FXMLSrcDir: string; FXMLSrcDir: string;
FExtraOptions : String; FExtraOptions : String;
FChmTitle: String;
procedure SetCSSFile(AValue: String); procedure SetCSSFile(AValue: String);
procedure SetFooterFilename(AValue: String); procedure SetFooterFilename(AValue: String);
procedure SetIncludePath(AValue: string); procedure SetIncludePath(AValue: string);
@ -83,7 +79,7 @@ type
procedure InitVars; procedure InitVars;
procedure AddFilesToList(Dir: String; List: TStrings); procedure AddFilesToList(Dir: String; List: TStrings);
procedure FindSourceFiles; procedure FindSourceFiles;
procedure CreateOutputDir; procedure CreateOuputDir;
procedure RunFPDoc; procedure RunFPDoc;
procedure CopyToXCTDir; procedure CopyToXCTDir;
procedure Execute; procedure Execute;
@ -91,19 +87,18 @@ type
property CSSFile: String read FCSSFile write SetCSSFile; property CSSFile: String read FCSSFile write SetCSSFile;
property FooterFilename: String read FFooterFilename write SetFooterFilename; property FooterFilename: String read FFooterFilename write SetFooterFilename;
property FPDocExe: String read FFPDocExe write FFPDocExe; property FPDocExe: String read FFPDocExe write FFPDocExe;
property IncludePath: string read FIncludePath write SetIncludePath; // semicolon separated search paths property IncludePath: string read FIncludePath write SetIncludePath;// semicolon separated search path
property InputFile: string read FInputFile write SetInputFile; // relative to OutDir, automatically created property InputFile: string read FInputFile write SetInputFile; // relative to OutDir, automatically created
property OutDir: string read FOutDir write SetOutDir; property OutDir: string read FOutDir write SetOutDir;
property OutFormat: String read FOutFormat write FOutFormat; property OutFormat: String read FOutFormat write FOutFormat;
property PackageName: string read FPackageName; property PackageName: string read FPackageName;
property PasSrcDir: string read FPasSrcDir write SetPasSrcDir; property PasSrcDir: string read FPasSrcDir write SetPasSrcDir;
property Step: TFPDocRunStep read FStep; property Step: TFPDocRunStep read FStep;
property UsedPkgs: TStringList read FUsedPkgs; // e.g. 'rtl','fcl', 'lazutils', 'lcl' property UsedPkgs: TStringList read FUsedPkgs; // e.g. 'rtl','fcl', 'lazutils'
property XCTDir: string read FXCTDir write SetXCTDir; property XCTDir: string read FXCTDir write SetXCTDir;
property XMLSrcDir: string read FXMLSrcDir write SetXMLSrcDir; property XMLSrcDir: string read FXMLSrcDir write SetXMLSrcDir;
property XCTFile: string read FXCTFile; property XCTFile: string read FXCTFile;
property ExtraOptions : string read FExtraOptions write FExtraOptions; property ExtraOptions : string read FExtraOptions write FExtraOptions;
property ChmTitle: String read FChmTitle write FChmTitle; // added for LHelp compatibility
end; end;
procedure GetEnvDef(var S: String; DefaultValue: String; EnvName: String); procedure GetEnvDef(var S: String; DefaultValue: String; EnvName: String);
@ -210,7 +205,7 @@ begin
if DefaultOutFormat = '' then if DefaultOutFormat = '' then
begin begin
writeln('Error: outfmt parameter is missing'); writeln('Error: Param outfmt wrong');
PrintHelp; PrintHelp;
end; end;
end; end;
@ -286,7 +281,6 @@ begin
OutFormat:=DefaultOutFormat; OutFormat:=DefaultOutFormat;
FooterFilename:=DefaultFooterFilename; FooterFilename:=DefaultFooterFilename;
XCTDir:=DefaultXCTDir; XCTDir:=DefaultXCTDir;
ChmTitle := '';
FStep:=frsCreated; FStep:=frsCreated;
end; end;
@ -303,7 +297,7 @@ var
p: Integer; p: Integer;
begin begin
if ord(Step)>=ord(frsVarsInitialized) then if ord(Step)>=ord(frsVarsInitialized) then
raise Exception.Create('TFPDocRun.InitVars already called'); raise Exception.Create('TFPDocRun.InitVars not again');
// add IncludePath to ParseParams // add IncludePath to ParseParams
p:=1; p:=1;
@ -353,8 +347,6 @@ begin
Params.Add('--make-searchable'); Params.Add('--make-searchable');
if CSSFile<>'' then if CSSFile<>'' then
Params.Add('--css-file='+ExtractFileName(CSSFile)); // the css file is copied to the OutDir Params.Add('--css-file='+ExtractFileName(CSSFile)); // the css file is copied to the OutDir
if (ChmTitle <> '') then
Params.Add('--chm-title="' + ChmTitle + '"'); // parent TOC/navigation node in LHelp
end; end;
if (FooterFilename<>'') and FileExistsUTF8(FooterFilename) then if (FooterFilename<>'') and FileExistsUTF8(FooterFilename) then
@ -369,7 +361,6 @@ begin
writeln('FPDocExe=',FPDocExe); writeln('FPDocExe=',FPDocExe);
writeln('OutFormat=',OutFormat); writeln('OutFormat=',OutFormat);
writeln('CSSFile=',CSSFile); writeln('CSSFile=',CSSFile);
writeln('ChmTitle=', ChmTitle);
writeln('FooterFilename=',FooterFilename); writeln('FooterFilename=',FooterFilename);
writeln('InputFile=',InputFile); writeln('InputFile=',InputFile);
writeln('OutDir=',OutDir); writeln('OutDir=',OutDir);
@ -414,7 +405,7 @@ var
XMLFile, Filename: String; XMLFile, Filename: String;
begin begin
if ord(Step)>=ord(frsFilesGathered) then if ord(Step)>=ord(frsFilesGathered) then
raise Exception.Create('TFPDocRun.FindSourceFiles already called'); raise Exception.Create('TFPDocRun.FindSourceFiles not again');
if ord(Step)<ord(frsVarsInitialized) then if ord(Step)<ord(frsVarsInitialized) then
InitVars; InitVars;
@ -455,18 +446,18 @@ begin
FStep:=frsFilesGathered; FStep:=frsFilesGathered;
end; end;
procedure TFPDocRun.CreateOutputDir; procedure TFPDocRun.CreateOuputDir;
var var
TargetCSSFile: String; TargetCSSFile: String;
begin begin
if ord(Step)>=ord(frsOutDirCreated) then if ord(Step)>=ord(frsOutDirCreated) then
raise Exception.Create('TFPDocRun.CreateOutputDir already called'); raise Exception.Create('TFPDocRun.CreateOuputDir not again');
if Not DirectoryExistsUTF8(OutDir) then if Not DirectoryExistsUTF8(OutDir) then
begin begin
writeln('Creating directory "',OutDir,'"'); writeln('Creating directory "',OutDir,'"');
if not CreateDirUTF8(OutDir) then if not CreateDirUTF8(OutDir) then
raise Exception.Create('Unable to create directory "'+OutDir+'"'); raise Exception.Create('unable to create directory "'+OutDir+'"');
end; end;
if ord(Step)<ord(frsFilesGathered) then if ord(Step)<ord(frsFilesGathered) then
@ -478,7 +469,7 @@ begin
if CompareFilenames(TargetCSSFile,CSSFile)<>0 then if CompareFilenames(TargetCSSFile,CSSFile)<>0 then
begin begin
if not CopyFile(CSSFile,TargetCSSFile) then if not CopyFile(CSSFile,TargetCSSFile) then
raise Exception.Create('Unable to copy css file: CSSfile="'+CSSFile+'" to "'+TargetCSSFile+'"'); raise Exception.Create('unable to copy css file: CSSfile="'+CSSFile+'" to "'+TargetCSSFile+'"');
end; end;
end; end;
@ -491,9 +482,9 @@ var
CmdLine: String; CmdLine: String;
begin begin
if ord(Step)>=ord(frsFPDocExecuted) then if ord(Step)>=ord(frsFPDocExecuted) then
raise Exception.Create('TFPDocRun.Run already called'); raise Exception.Create('TFPDocRun.Run not again');
if ord(Step)<ord(frsOutDirCreated) then if ord(Step)<ord(frsOutDirCreated) then
CreateOutputDir; CreateOuputDir;
if ShowCmd then if ShowCmd then
begin begin
@ -505,7 +496,7 @@ begin
{$IFDEF MSWINDOWS}FPDocExe := ChangeFileExt(FPDocExe,'.exe');{$ENDIF} {$IFDEF MSWINDOWS}FPDocExe := ChangeFileExt(FPDocExe,'.exe');{$ENDIF}
if not FileInEnvPATH(FPDocExe) then if not FileInEnvPATH(FPDocExe) then
begin begin
WriteLn('Error: fpdoc ('+FPDocExe+') not found. Please add its location to the PATH', WriteLn('Error: fpdoc ('+FPDocExe+') cannot be found. Please add its location to the PATH ',
'or set it with --fpdoc path',PathDelim,'to',PathDelim,'fpdoc'{$IFDEF MSWINDOWS},'.exe'{$ENDIF}); 'or set it with --fpdoc path',PathDelim,'to',PathDelim,'fpdoc'{$IFDEF MSWINDOWS},'.exe'{$ENDIF});
Halt(1); Halt(1);
end; end;
@ -546,7 +537,7 @@ var
TargetXCTFile, SrcCHMFile, TargetCHMFile: String; TargetXCTFile, SrcCHMFile, TargetCHMFile: String;
begin begin
if ord(Step)>=ord(frsCopiedToXCTDir) then if ord(Step)>=ord(frsCopiedToXCTDir) then
raise Exception.Create('TFPDocRun.CopyToXCTDir alreay called'); raise Exception.Create('TFPDocRun.CopyToXCTDir not again');
if ord(Step)<ord(frsFPDocExecuted) then if ord(Step)<ord(frsFPDocExecuted) then
RunFPDoc; RunFPDoc;
@ -557,7 +548,7 @@ begin
if ShowCmd then if ShowCmd then
writeln('cp ',XCTFile,' ',TargetXCTFile) writeln('cp ',XCTFile,' ',TargetXCTFile)
else if not CopyFile(XCTFile,TargetXCTFile) then else if not CopyFile(XCTFile,TargetXCTFile) then
raise Exception.Create('Unable to copy xct file: "'+XCTFile+'" to "'+TargetXCTFile+'"'); raise Exception.Create('unable to copy xct file: "'+XCTFile+'" to "'+TargetXCTFile+'"');
writeln('Created ',TargetXCTFile); writeln('Created ',TargetXCTFile);
if OutFormat='chm' then if OutFormat='chm' then
begin begin
@ -566,7 +557,7 @@ begin
if ShowCmd then if ShowCmd then
writeln('cp ',SrcCHMFile,' ',TargetCHMFile) writeln('cp ',SrcCHMFile,' ',TargetCHMFile)
else if not CopyFile(SrcCHMFile,TargetCHMFile) then else if not CopyFile(SrcCHMFile,TargetCHMFile) then
raise Exception.Create('Unable to copy chm file: "'+SrcCHMFile+'" to "'+TargetCHMFile+'"'); raise Exception.Create('unable to copy chm file: "'+SrcCHMFile+'" to "'+TargetCHMFile+'"');
writeln('Created ',TargetCHMFile); writeln('Created ',TargetCHMFile);
end; end;
end; end;
@ -578,7 +569,7 @@ procedure TFPDocRun.Execute;
begin begin
writeln('==================================================================='); writeln('===================================================================');
if ord(Step)>=ord(frsComplete) then if ord(Step)>=ord(frsComplete) then
raise Exception.Create('TFPDocRun.Execute already called'); raise Exception.Create('TFPDocRun.Execute not again');
if ord(Step)<ord(frsCopiedToXCTDir) then if ord(Step)<ord(frsCopiedToXCTDir) then
CopyToXCTDir; CopyToXCTDir;
@ -587,76 +578,30 @@ end;
var var
Run: TFPDocRun; Run: TFPDocRun;
sLclFooter, sLazUtilsFooter: String;
sLclChmTitle, sLazUtilsChmTitle: String;
begin begin
ReadOptions; ReadOptions;
{
The Output format for LazUtils is built twice. This is done because LCL and LazUtils
are co-dependent; each file has links to topics in the other. Building LazUtils twice
ensures that the "chicken or the egg" problem with inter-file links is avoided.
Build LazUtils WITHOUT LCL links.
Build LCL with links to RTL, FCL, LazUtils.
Build LazUtils with links to RTL, FCL, LCL.
This approach is the simplest possible thing that actually works.
}
// build WITHOUT external links to LCL
Run:=TFPDocRun.Create('lazutils'); Run:=TFPDocRun.Create('lazutils');
Run.ExtraOptions:='-MObjFPC -Scghi'; // extra options from lazutils makefile. Run.ExtraOptions:='-MObjFPC -Scghi'; // extra options from in lazutils makefile.
Run.UsedPkgs.Add('rtl'); Run.UsedPkgs.Add('rtl');
Run.UsedPkgs.Add('fcl'); Run.UsedPkgs.Add('fcl');
Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lazutils'; Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lazutils';
Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'components'+PathDelim+'lazutils'; Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'components'+PathDelim+'lazutils';
// footer file pairs created by the build_chm.sh script
// locallclfooter.xml, localchmfooter.xml - for HTML format
// chmlclfooter.xml, chmlazutilsfooter.xml - for CHM format with link to online HTML
// an lcl variant is the specified command line argument or default value
sLclFooter := Run.FooterFilename;
sLazUtilsFooter := StringReplace(sLclFooter, 'lcl', 'lazutils', [rfIgnoreCase]);
// displayed in LHelp as the parent node in the TOC/navigation trees
sLclChmTitle := '(LCL) Lazarus Component Library';
sLazUtilsChmTitle := '(LazUtils) Lazarus Utilities';
// use the footer file and title for this package/build/release
Run.FooterFilename := sLazUtilsFooter;
Run.ChmTitle := sLazUtilsChmTitle;
Run.Execute; Run.Execute;
Run.Free; Run.Free;
// build with external links to LazUtils
Run:=TFPDocRun.Create('lcl'); Run:=TFPDocRun.Create('lcl');
Run.ExtraOptions:='-MObjFPC -Sic'; // extra options from LCL makefile. Run.ExtraOptions:='-MObjFPC -Sic'; // extra options from in LCL makefile.
Run.UsedPkgs.Add('rtl'); Run.UsedPkgs.Add('rtl');
Run.UsedPkgs.Add('fcl'); Run.UsedPkgs.Add('fcl');
Run.UsedPkgs.Add('lazutils'); Run.UsedPkgs.Add('lazutils');
Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lcl'+PathDelim; Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lcl'+PathDelim;
Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'lcl'+PathDelim; Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'lcl'+PathDelim;
Run.IncludePath := Run.PasSrcDir+PathDelim+'include'; Run.IncludePath := Run.PasSrcDir+PathDelim+'include';
// use the footer file and title for this package/build/release
Run.FooterFilename := sLclFooter;
Run.ChmTitle := sLclChmTitle;
Run.Execute;
Run.Free;
// build with external links to LCL
Run:=TFPDocRun.Create('lazutils');
Run.ExtraOptions:='-MObjFPC -Scghi'; // extra options from lazutils makefile.
Run.UsedPkgs.Add('rtl');
Run.UsedPkgs.Add('fcl');
Run.UsedPkgs.Add('lcl');
Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lazutils';
Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'components'+PathDelim+'lazutils';
// use the footer file and title for this package/build/release
Run.FooterFilename := sLazUtilsFooter;
Run.ChmTitle := sLazUtilsChmTitle;
Run.Execute; Run.Execute;
Run.Free; Run.Free;
if ShowCmd then if ShowCmd then
writeln('Not executed, simulation ended.'); writeln('Not executing, simulation ended. Stop');
end. end.

10
docs/html/chmlazutilsfooter.xml
View File

@ -1,10 +0,0 @@
<hr class='footer-sep'/>
<table class='footer'>
<tr>
<td class='footer-doc'>Lazarus Utilties (LazUtils)</td>
<td class='footer-ver'>Version 2.3.0 (2021-10-27)</td>
<td class='footer-date'>
<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>
</td>
</tr>
</table>

10
docs/html/chmlclfooter.xml
View File

@ -1,10 +0,0 @@
<hr class='footer-sep'/>
<table class='footer'>
<tr>
<td class='footer-doc'>Lazarus Component Library (LCL)</td>
<td class='footer-ver'>Version 2.3.0 (2021-10-27)</td>
<td class='footer-date'>
<a href="https://lazarus-ccr.sourceforge.io/docs/">HTML version (Online)</a>
</td>
</tr>
</table>

106
docs/html/fpdoc.css
View File

@ -1,129 +1,122 @@
/* /*
fpdoc.css $Id$
Modified for use with Lazarus LCL and LazUtils documentation
Default style sheet for FPDoc reference documentation
by Sebastian Guenther, sg@freepascal.org
Feel free to use this file as a template for your own style sheets.
*/ */
body { body {
background: white; background: white
color: black;
font-size: 11pt;
font-family: "San Francisco", "Roboto", "Open Sans", "Segoe UI", "Helvetica", "Arial", sans-serif;
} }
p, th, td, caption, h1, h2, h3, ul, ol, dl { body, p, th, td, caption, h1, h2, h3, ul, ol, dl {
font-family: "San Francisco", "Roboto", "Open Sans", "Segoe UI", "Helvetica", "Arial", sans-serif;
color: black; color: black;
font-family: sans-serif
} }
tt, span.kw, pre { tt, span.kw, pre {
font-family: "Menlo", "JetBrains Mono", "Roboto Mono", "Noto Sans Mono", "Inconsolata", "Courier New", Courier, monospace; font-family: "Courier New", Courier, monospace
font-size: 1em;
} }
p, th, td, caption, ul, ol, dl, tt, span.kw, pre { body, p, th, td, caption, ul, ol, dl, tt, span.kw, pre {
font-size: 1em; font-size: 14px
} }
A:link { A:link {
color: blue; color: blue
} }
A:visited { A:visited {
color: darkblue; color: darkblue
} }
A:active { A:active {
color: red; color: red
} }
A { A {
text-decoration: none; text-decoration: none
} }
A:hover { A:hover {
text-decoration: underline; text-decoration: underline
} }
h1, h2, td.h2 { h1, h2, td.h2 {
color: #005A9C; color: #005A9C
} }
/* Especially for Netscape on Linux: */ /* Especially for Netscape on Linux: */
h3, td.h3 { h3, td.h3 {
font-size: 1em; font-size: 12pt
} }
/* source fragments */ /* source fragments */
span.code { span.code {
white-space: nowrap; white-space: nowrap
} }
/* symbols in source fragments */ /* symbols in source fragments */
span.sym { span.sym {
color: darkred; color: darkred
} }
/* keywords in source fragments */ /* keywords in source fragments */
span.kw { span.kw {
font-weight: bold; font-weight: bold
} }
/* comments in source fragments */ /* comments in source fragments */
span.cmt { span.cmt {
color: darkcyan; color: darkcyan;
font-style: italic; font-style: italic
} }
/* directives in source fragments */ /* directives in source fragments */
span.dir { span.dir {
color: darkyellow; color: darkyellow;
font-style: italic; font-style: italic
} }
/* numbers in source fragments */ /* numbers in source fragments */
span.num { span.num {
color: darkmagenta; color: darkmagenta
} }
/* characters (#...) in source fragments */ /* characters (#...) in source fragments */
span.chr { span.chr {
color: darkcyan; color: darkcyan
} }
/* strings in source fragments */ /* strings in source fragments */
span.str { span.str {
color: blue; color: blue
} }
/* assembler passages in source fragments */ /* assembler passages in source fragments */
span.asm { span.asm {
color: green; color: green
} }
td {
vertical-align: baseline;
}
td.pre { td.pre {
white-space: pre; white-space: pre
}
table caption {
font-weight: bold;
} }
p.cmt { p.cmt {
color: gray; color: gray
} }
span.warning { span.warning {
color: red; color: red;
font-weight: bold; font-weight: bold
} }
/* !!!: How should we define this...? */ /* !!!: How should we define this...? */
span.file { span.file {
color: darkgreen; color: darkgreen
} }
table.remark { table.remark {
@ -134,47 +127,36 @@ table.bar {
background-color: #a0c0ff; background-color: #a0c0ff;
} }
table.footer {
margin-top: .5em;
width: 100%;
font-size: .875em;
/* font-style: italic; */
font-style: normal;
}
span.bartitle { span.bartitle {
font-weight: bold; font-weight: bold;
font-style: italic; font-style: italic;
color: darkblue; color: darkblue
} }
span.footer { span.footer {
font-style: italic; font-style: italic;
color: darkblue; color: darkblue
} }
/* definition list */ /* definition list */
dl { dl {
/* border: 2px solid #ccc; */ border: 3px double #ccc;
display: block; padding: 0.5em;
margin: 1em 0 1em 0;
} }
/* definition list: term */ /* definition list: term */
dt { dt {
/*
float: left; float: left;
clear: left; clear: left;
*/
width: auto; /* normally browsers default width of largest item */ width: auto; /* normally browsers default width of largest item */
/* padding-right: 1.25em; */ padding-right: 20px;
font-weight: bold; font-weight: bold;
color: darkgreen; color: darkgreen;
} }
/* definition list: description */ /* definition list: description */
dd { dd {
margin: 0 0 0 2em; margin: 0 0 0 110px;
padding: 0 0 0.5em 0; padding: 0 0 0.5em 0;
} }
@ -182,15 +164,3 @@ dd {
td p { td p {
margin: 0; margin: 0;
} }
var {
font-weight: bold;
}
hr.footer-sep {
margin-top: .667em;
}
td.footer-doc { width: 36%; text-align: left; font-weight: bold; color: Black; }
td.footer-ver { width: 34%; text-align: center; color: Gray; }
td.footer-date { width: 30%; text-align: right; color: Gray; }

8
docs/html/locallazutilsfooter.xml
View File

@ -1,8 +0,0 @@
<hr class='footer-sep'/>
<table class='footer'>
<tr>
<td class='footer-doc'>Lazarus Utilities (LazUtils)</td>
<td class='footer-ver'>Version 2.3.0-7530dcb21a</td>
<td class='footer-date'>Generated 2021-10-27</td>
</tr>
</table>

7
docs/html/locallclfooter.xml
View File

@ -1,8 +1,5 @@
<hr class='footer-sep'/> <table cellspacing="0" cellpadding="0" class="bar" width="100%">
<table class='footer'>
<tr> <tr>
<td class='footer-doc'>Lazarus Component Library (LCL)</td> <td valign="top" align="center"><span class="footer">The latest version of this document can be found at </span><a href="http://lazarus-ccr.sourceforge.net/docs/lcl">lazarus-ccr.sourceforge.net</a><span class="footer">.</span></td>
<td class='footer-ver'>Version 2.3.0-7530dcb21a</td>
<td class='footer-date'>Generated 2021-10-27</td>
</tr> </tr>
</table> </table>