paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-08-10 20:56:14 +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 use the trunk version of fpdoc if possible:
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
REM Builds all Lazarus docs and pack them in one .chm file
REM
REM Adjust any paths used in the batch file for use on your system.
REM If needed, compile the build_lcl_docs.lpi project before running this script.
REM ========================================================================
REM ========================================================================
REM creates and uses version.inc, commit.inc, date.inc for values used in footers
REM git describe doesn't return a usable branch or tag name like 2.3.0
REM main-2_3 and fixes_2_2 are not what is needed for the doc files
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
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
PATH=D:\programming\fpc\bin\i386-win32\;%PATH%
build_lcl_docs.exe --outfmt chm
pause

105
docs/html/build_chm.sh
View File

@ -1,102 +1,7 @@
#!/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
#==============================================================
# 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
# Preferably: use trunk fpdoc: --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc

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 use the trunk version of fpdoc if possible:
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
REM Builds all Lazarus docs
REM
REM Adjust any paths used in the batch file for use on your system.
REM If needed, compile the build_lcl_docs.lpi project before running this script.
REM Notes:
REM
REM Run build_chm.bat first. It (re-)generates the footer files with version and revision info.
REM ========================================================================
REM path to the fpdoc executable
set fpdocpath="c:\lazarus\fpc\3.2.0\bin\x86_64-win64"
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\
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
PATH=C:\Programas\lazarus22\fpc\2.2.0\bin\i386-win32;%PATH%
build_lcl_docs.exe
pause

19
docs/html/build_html.sh
View File

@ -1,13 +1,12 @@
#!/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"?>
<CONFIG>
<ProjectOptions>
<Version Value="12"/>
<Version Value="11"/>
<PathDelim Value="\"/>
<General>
<Flags>
<MainUnitHasCreateFormStatements Value="False"/>
<MainUnitHasTitleStatement Value="False"/>
<MainUnitHasScaledStatement Value="False"/>
<LRSInOutputDirectory Value="False"/>
<CompatibilityMode Value="True"/>
</Flags>
<SessionStorage Value="InIDEConfig"/>
<MainUnit Value="0"/>
<Title Value="build_lcl_docs"/>
</General>
<BuildModes Count="1">
@ -22,13 +19,13 @@
</PublishOptions>
<RunParams>
<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>
<FormatVersion Value="2"/>
<Modes Count="1">
<Mode0 Name="default">
<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>
</Mode0>
</Modes>
@ -63,10 +60,5 @@
<UseAnsiStrings Value="False"/>
</SyntaxOptions>
</Parsing>
<Linking>
<Debugging>
<GenerateDebugInfo Value="False"/>
</Debugging>
</Linking>
</CompilerOptions>
</CONFIG>

159
docs/html/build_lcl_docs.lpr
View File

@ -1,9 +1,7 @@
program update_lcl_docs;
{
Runs FPC's fpdoc document generator to generate LCL and LazUtils documentation
in CHM or HTML format
}
{ Runs FPC's fpdoc document generator to generate LCL documentation,
e.g. in CHM format }
{$mode objfpc}{$H+}
{$IFDEF MSWINDOWS}
@ -24,7 +22,7 @@ var
DefaultXCTDir: String;
DefaultFPDocParams: string = '';
DefaultOutFormat: string = 'html';
DefaultFooterFilename: string = 'locallclfooter.xml';
DefaultFooterFilename: string = 'locallclfooter.xml'; // ToDo
type
TFPDocRunStep = (
@ -65,8 +63,6 @@ type
FXCTFile: string;
FXMLSrcDir: string;
FExtraOptions : String;
FChmTitle: String;
procedure SetCSSFile(AValue: String);
procedure SetFooterFilename(AValue: String);
procedure SetIncludePath(AValue: string);
@ -83,7 +79,7 @@ type
procedure InitVars;
procedure AddFilesToList(Dir: String; List: TStrings);
procedure FindSourceFiles;
procedure CreateOutputDir;
procedure CreateOuputDir;
procedure RunFPDoc;
procedure CopyToXCTDir;
procedure Execute;
@ -91,19 +87,18 @@ type
property CSSFile: String read FCSSFile write SetCSSFile;
property FooterFilename: String read FFooterFilename write SetFooterFilename;
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 OutDir: string read FOutDir write SetOutDir;
property OutFormat: String read FOutFormat write FOutFormat;
property PackageName: string read FPackageName;
property PasSrcDir: string read FPasSrcDir write SetPasSrcDir;
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 XMLSrcDir: string read FXMLSrcDir write SetXMLSrcDir;
property XCTFile: string read FXCTFile;
property ExtraOptions : string read FExtraOptions write FExtraOptions;
property ChmTitle: String read FChmTitle write FChmTitle; // added for LHelp compatibility
end;
procedure GetEnvDef(var S: String; DefaultValue: String; EnvName: String);
@ -210,7 +205,7 @@ begin
if DefaultOutFormat = '' then
begin
writeln('Error: outfmt parameter is missing');
writeln('Error: Param outfmt wrong');
PrintHelp;
end;
end;
@ -274,21 +269,20 @@ end;
constructor TFPDocRun.Create(aPackageName: string);
begin
FPackageName := aPackageName;
FOptions := DefaultFPDocRunOptions;
fUsedPkgs := TStringList.Create;
FPackageName:=aPackageName;
FOptions:=DefaultFPDocRunOptions;
fUsedPkgs:=TStringList.Create;
InputFile := 'inputfile.txt';
OutDir := PackageName;
FPDocExe := TrimFilename(DefaultFPDocExe);
CSSFile := DefaultCSSFile;
Params := TStringList.Create;
OutDir:=PackageName;
FPDocExe:=TrimFilename(DefaultFPDocExe);
CSSFile:=DefaultCSSFile;
Params:=TStringList.Create;
SplitCmdLineParams(DefaultFPDocParams,Params);
OutFormat := DefaultOutFormat;
FooterFilename := DefaultFooterFilename;
XCTDir := DefaultXCTDir;
ChmTitle := '';
OutFormat:=DefaultOutFormat;
FooterFilename:=DefaultFooterFilename;
XCTDir:=DefaultXCTDir;
FStep := frsCreated;
FStep:=frsCreated;
end;
destructor TFPDocRun.Destroy;
@ -302,8 +296,8 @@ var
Pkg, Prefix, IncludeDir, Param: String;
p: Integer;
begin
if ord(Step) >= ord(frsVarsInitialized) then
raise Exception.Create('TFPDocRun.InitVars already called');
if ord(Step)>=ord(frsVarsInitialized) then
raise Exception.Create('TFPDocRun.InitVars not again');
// add IncludePath to ParseParams
p:=1;
@ -353,8 +347,6 @@ begin
Params.Add('--make-searchable');
if CSSFile<>'' then
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;
if (FooterFilename<>'') and FileExistsUTF8(FooterFilename) then
@ -366,13 +358,12 @@ begin
if Verbosity>0 then
begin
writeln('Verbose Params: ------------------');
writeln('FPDocExe=', FPDocExe);
writeln('OutFormat=', OutFormat);
writeln('CSSFile=', CSSFile);
writeln('ChmTitle=', ChmTitle);
writeln('FooterFilename=', FooterFilename);
writeln('InputFile=', InputFile);
writeln('OutDir=', OutDir);
writeln('FPDocExe=',FPDocExe);
writeln('OutFormat=',OutFormat);
writeln('CSSFile=',CSSFile);
writeln('FooterFilename=',FooterFilename);
writeln('InputFile=',InputFile);
writeln('OutDir=',OutDir);
writeln('ParseParams=');
writeln(ParseParams);
writeln('FPDocParams=');
@ -413,9 +404,9 @@ var
I: Integer;
XMLFile, Filename: String;
begin
if ord(Step) >= ord(frsFilesGathered) then
raise Exception.Create('TFPDocRun.FindSourceFiles already called');
if ord(Step) < ord(frsVarsInitialized) then
if ord(Step)>=ord(frsFilesGathered) then
raise Exception.Create('TFPDocRun.FindSourceFiles not again');
if ord(Step)<ord(frsVarsInitialized) then
InitVars;
if Verbosity>0 then
@ -455,21 +446,21 @@ begin
FStep:=frsFilesGathered;
end;
procedure TFPDocRun.CreateOutputDir;
procedure TFPDocRun.CreateOuputDir;
var
TargetCSSFile: String;
begin
if ord(Step) >= ord(frsOutDirCreated) then
raise Exception.Create('TFPDocRun.CreateOutputDir already called');
if ord(Step)>=ord(frsOutDirCreated) then
raise Exception.Create('TFPDocRun.CreateOuputDir not again');
if Not DirectoryExistsUTF8(OutDir) then
begin
writeln('Creating directory "',OutDir,'"');
if not CreateDirUTF8(OutDir) then
raise Exception.Create('Unable to create directory "'+OutDir+'"');
raise Exception.Create('unable to create directory "'+OutDir+'"');
end;
if ord(Step) < ord(frsFilesGathered) then
if ord(Step)<ord(frsFilesGathered) then
FindSourceFiles;
if (OutFormat='chm') and (CSSFile<>'') then
@ -478,7 +469,7 @@ begin
if CompareFilenames(TargetCSSFile,CSSFile)<>0 then
begin
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;
@ -490,10 +481,10 @@ var
Process: TProcess;
CmdLine: String;
begin
if ord(Step) >= ord(frsFPDocExecuted) then
raise Exception.Create('TFPDocRun.Run already called');
if ord(Step) < ord(frsOutDirCreated) then
CreateOutputDir;
if ord(Step)>=ord(frsFPDocExecuted) then
raise Exception.Create('TFPDocRun.Run not again');
if ord(Step)<ord(frsOutDirCreated) then
CreateOuputDir;
if ShowCmd then
begin
@ -505,7 +496,7 @@ begin
{$IFDEF MSWINDOWS}FPDocExe := ChangeFileExt(FPDocExe,'.exe');{$ENDIF}
if not FileInEnvPATH(FPDocExe) then
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});
Halt(1);
end;
@ -545,9 +536,9 @@ procedure TFPDocRun.CopyToXCTDir;
var
TargetXCTFile, SrcCHMFile, TargetCHMFile: String;
begin
if ord(Step) >= ord(frsCopiedToXCTDir) then
raise Exception.Create('TFPDocRun.CopyToXCTDir alreay called');
if ord(Step) < ord(frsFPDocExecuted) then
if ord(Step)>=ord(frsCopiedToXCTDir) then
raise Exception.Create('TFPDocRun.CopyToXCTDir not again');
if ord(Step)<ord(frsFPDocExecuted) then
RunFPDoc;
if (foCopyToXCTDir in Options)
@ -557,7 +548,7 @@ begin
if ShowCmd then
writeln('cp ',XCTFile,' ',TargetXCTFile)
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);
if OutFormat='chm' then
begin
@ -566,7 +557,7 @@ begin
if ShowCmd then
writeln('cp ',SrcCHMFile,' ',TargetCHMFile)
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);
end;
end;
@ -577,9 +568,9 @@ end;
procedure TFPDocRun.Execute;
begin
writeln('===================================================================');
if ord(Step) >= ord(frsComplete) then
raise Exception.Create('TFPDocRun.Execute already called');
if ord(Step) < ord(frsCopiedToXCTDir) then
if ord(Step)>=ord(frsComplete) then
raise Exception.Create('TFPDocRun.Execute not again');
if ord(Step)<ord(frsCopiedToXCTDir) then
CopyToXCTDir;
FStep:=frsComplete;
@ -587,76 +578,30 @@ end;
var
Run: TFPDocRun;
sLclFooter, sLazUtilsFooter: String;
sLclChmTitle, sLazUtilsChmTitle: String;
begin
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.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('fcl');
Run.XMLSrcDir := '..'+PathDelim+'xml'+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.Free;
// build with external links to LazUtils
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('fcl');
Run.UsedPkgs.Add('lazutils');
Run.XMLSrcDir := '..'+PathDelim+'xml'+PathDelim+'lcl'+PathDelim;
Run.PasSrcDir := '..'+PathDelim+'..'+PathDelim+'lcl'+PathDelim;
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.Free;
if ShowCmd then
writeln('Not executed, simulation ended.');
writeln('Not executing, simulation ended. Stop');
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
Modified for use with Lazarus LCL and LazUtils documentation
$Id$
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 {
background: white;
color: black;
font-size: 11pt;
font-family: "San Francisco", "Roboto", "Open Sans", "Segoe UI", "Helvetica", "Arial", sans-serif;
background: white
}
p, th, td, caption, h1, h2, h3, ul, ol, dl {
font-family: "San Francisco", "Roboto", "Open Sans", "Segoe UI", "Helvetica", "Arial", sans-serif;
body, p, th, td, caption, h1, h2, h3, ul, ol, dl {
color: black;
font-family: sans-serif
}
tt, span.kw, pre {
font-family: "Menlo", "JetBrains Mono", "Roboto Mono", "Noto Sans Mono", "Inconsolata", "Courier New", Courier, monospace;
font-size: 1em;
font-family: "Courier New", Courier, monospace
}
p, th, td, caption, ul, ol, dl, tt, span.kw, pre {
font-size: 1em;
body, p, th, td, caption, ul, ol, dl, tt, span.kw, pre {
font-size: 14px
}
A:link {
color: blue;
color: blue
}
A:visited {
color: darkblue;
color: darkblue
}
A:active {
color: red;
color: red
}
A {
text-decoration: none;
text-decoration: none
}
A:hover {
text-decoration: underline;
text-decoration: underline
}
h1, h2, td.h2 {
color: #005A9C;
color: #005A9C
}
/* Especially for Netscape on Linux: */
h3, td.h3 {
font-size: 1em;
font-size: 12pt
}
/* source fragments */
span.code {
white-space: nowrap;
white-space: nowrap
}
/* symbols in source fragments */
span.sym {
color: darkred;
color: darkred
}
/* keywords in source fragments */
span.kw {
font-weight: bold;
font-weight: bold
}
/* comments in source fragments */
span.cmt {
color: darkcyan;
font-style: italic;
font-style: italic
}
/* directives in source fragments */
span.dir {
color: darkyellow;
font-style: italic;
font-style: italic
}
/* numbers in source fragments */
span.num {
color: darkmagenta;
color: darkmagenta
}
/* characters (#...) in source fragments */
span.chr {
color: darkcyan;
color: darkcyan
}
/* strings in source fragments */
span.str {
color: blue;
color: blue
}
/* assembler passages in source fragments */
span.asm {
color: green;
color: green
}
td {
vertical-align: baseline;
}
td.pre {
white-space: pre;
}
table caption {
font-weight: bold;
white-space: pre
}
p.cmt {
color: gray;
color: gray
}
span.warning {
color: red;
font-weight: bold;
font-weight: bold
}
/* !!!: How should we define this...? */
span.file {
color: darkgreen;
color: darkgreen
}
table.remark {
@ -134,47 +127,36 @@ table.bar {
background-color: #a0c0ff;
}
table.footer {
margin-top: .5em;
width: 100%;
font-size: .875em;
/* font-style: italic; */
font-style: normal;
}
span.bartitle {
font-weight: bold;
font-style: italic;
color: darkblue;
color: darkblue
}
span.footer {
font-style: italic;
color: darkblue;
color: darkblue
}
/* definition list */
dl {
/* border: 2px solid #ccc; */
display: block;
margin: 1em 0 1em 0;
border: 3px double #ccc;
padding: 0.5em;
}
/* definition list: term */
dt {
/*
float: left;
clear: left;
*/
width: auto; /* normally browsers default width of largest item */
/* padding-right: 1.25em; */
padding-right: 20px;
font-weight: bold;
color: darkgreen;
}
/* definition list: description */
dd {
margin: 0 0 0 2em;
margin: 0 0 0 110px;
padding: 0 0 0.5em 0;
}
@ -182,15 +164,3 @@ dd {
td p {
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 class='footer'>
<table cellspacing="0" cellpadding="0" class="bar" width="100%">
<tr>
<td class='footer-doc'>Lazarus Component Library (LCL)</td>
<td class='footer-ver'>Version 2.3.0-7530dcb21a</td>
<td class='footer-date'>Generated 2021-10-27</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>
</tr>
</table>