paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-05 18:18:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Modified files:

* docs/html/build_lcl_docs.lpi
*  docs/html/build_lcl_docs.lpr
Adds TFPDocRun.ChmTitle property for CHM title and text in the LHelp TOC navigation tree.
Sets the footer file for each of the output formats generated in the program. Allows CHM to have links to the online HTML version, while HTML does not.
Modifies logic used to generate links to external topics. Causes LazUtils (the smaller of the two outputs) to be created twice.

* docs/html/build_chm.bat
* docs/html/build_chm.sh
Adds logic to generate distinct footer files for CHM vs HTML. Footer files include document title, version information, and generation date.

* docs/html/build_html.bat
* docs/html/build_html.sh
Copies custom CSS file to the output directory.

* docs/html/chmlazutilsfooter.xml
* docs/html/chmlclfooter.xml
* docs/html/locallazutilsfooter.xml
* docs/html/locallclfooter.xml
Standardized footer files for CHM and HTML output formats. A separate footer file is used for LCL and LazUtils for each of the output formats.

* docs/html/fpdoc.css
Adds font family fallbacks for common default fonts on various platforms.
Modifies layout and borders for definition lists (DL, DT, DD tags). Removes the border around DL.
Adds style rules for tags, classes used in file footers.
This commit is contained in:
dsiders 2021-10-28 02:55:57 +01:00
parent 7530dcb21a
commit 8af9cd0918
11 changed files with 466 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/html/build_chm.bat
View File

@ -1,11 +1,107 @@
echo off
cls
REM ========================================================================
REM Builds LCL and LazUtils documentation in CHM format
REM
REM Builds all Lazarus docs and pack them in one .chm file
REM use the trunk version of fpdoc if possible:
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
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
PATH=D:\programming\fpc\bin\i386-win32\;%PATH%
build_lcl_docs.exe --outfmt chm
pause
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

105
docs/html/build_chm.sh
View File

@ -1,7 +1,102 @@
#!/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,11 +1,30 @@
echo off
cls
REM ========================================================================
REM Builds LCL and LazUtils documentation in HTML format
REM ========================================================================
REM
REM Builds all Lazarus docs
REM use the trunk version of fpdoc if possible:
REM --fpdoc \path\to\fpc\trunk\bin\x86_64-win64\fpdoc.exe
REM
REM Notes:
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 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
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\

19
docs/html/build_html.sh
View File

@ -1,12 +1,13 @@
#!/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,14 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<CONFIG>
<ProjectOptions>
<Version Value="11"/>
<Version Value="12"/>
<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">
@ -19,13 +22,13 @@
</PublishOptions>
<RunParams>
<local>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T 'Lazarus Run Output' -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T &apos;Lazarus Run Output&apos; -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
</local>
<FormatVersion Value="2"/>
<Modes Count="1">
<Mode0 Name="default">
<local>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T 'Lazarus Run Output' -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
<LaunchingApplication PathPlusParams="\usr\X11R6\bin\xterm -T &apos;Lazarus Run Output&apos; -e $(LazarusDir)\tools\runwait.sh $(TargetCmdLine)"/>
</local>
</Mode0>
</Modes>
@ -60,5 +63,10 @@
<UseAnsiStrings Value="False"/>
</SyntaxOptions>
</Parsing>
<Linking>
<Debugging>
<GenerateDebugInfo Value="False"/>
</Debugging>
</Linking>
</CompilerOptions>
</CONFIG>

161
docs/html/build_lcl_docs.lpr
View File

@ -1,7 +1,9 @@
program update_lcl_docs;
{ Runs FPC's fpdoc document generator to generate LCL documentation,
e.g. in CHM format }
{
Runs FPC's fpdoc document generator to generate LCL and LazUtils documentation
in CHM or HTML format
}
{$mode objfpc}{$H+}
{$IFDEF MSWINDOWS}
@ -22,7 +24,7 @@ var
DefaultXCTDir: String;
DefaultFPDocParams: string = '';
DefaultOutFormat: string = 'html';
DefaultFooterFilename: string = 'locallclfooter.xml'; // ToDo
DefaultFooterFilename: string = 'locallclfooter.xml';
type
TFPDocRunStep = (
@ -63,6 +65,8 @@ type
FXCTFile: string;
FXMLSrcDir: string;
FExtraOptions : String;
FChmTitle: String;
procedure SetCSSFile(AValue: String);
procedure SetFooterFilename(AValue: String);
procedure SetIncludePath(AValue: string);
@ -79,7 +83,7 @@ type
procedure InitVars;
procedure AddFilesToList(Dir: String; List: TStrings);
procedure FindSourceFiles;
procedure CreateOuputDir;
procedure CreateOutputDir;
procedure RunFPDoc;
procedure CopyToXCTDir;
procedure Execute;
@ -87,18 +91,19 @@ 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 path
property IncludePath: string read FIncludePath write SetIncludePath; // semicolon separated search paths
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'
property UsedPkgs: TStringList read FUsedPkgs; // e.g. 'rtl','fcl', 'lazutils', 'lcl'
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);
@ -205,7 +210,7 @@ begin
if DefaultOutFormat = '' then
begin
writeln('Error: Param outfmt wrong');
writeln('Error: outfmt parameter is missing');
PrintHelp;
end;
end;
@ -269,20 +274,21 @@ 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;
OutFormat := DefaultOutFormat;
FooterFilename := DefaultFooterFilename;
XCTDir := DefaultXCTDir;
ChmTitle := '';
FStep:=frsCreated;
FStep := frsCreated;
end;
destructor TFPDocRun.Destroy;
@ -296,8 +302,8 @@ var
Pkg, Prefix, IncludeDir, Param: String;
p: Integer;
begin
if ord(Step)>=ord(frsVarsInitialized) then
raise Exception.Create('TFPDocRun.InitVars not again');
if ord(Step) >= ord(frsVarsInitialized) then
raise Exception.Create('TFPDocRun.InitVars already called');
// add IncludePath to ParseParams
p:=1;
@ -338,7 +344,7 @@ begin
Params.Add(Param);
end;
end;
if OutFormat='chm' then
begin
Params.Add('--output='+ ChangeFileExt(PackageName, '.chm'));
@ -347,6 +353,8 @@ 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
@ -358,12 +366,13 @@ begin
if Verbosity>0 then
begin
writeln('Verbose Params: ------------------');
writeln('FPDocExe=',FPDocExe);
writeln('OutFormat=',OutFormat);
writeln('CSSFile=',CSSFile);
writeln('FooterFilename=',FooterFilename);
writeln('InputFile=',InputFile);
writeln('OutDir=',OutDir);
writeln('FPDocExe=', FPDocExe);
writeln('OutFormat=', OutFormat);
writeln('CSSFile=', CSSFile);
writeln('ChmTitle=', ChmTitle);
writeln('FooterFilename=', FooterFilename);
writeln('InputFile=', InputFile);
writeln('OutDir=', OutDir);
writeln('ParseParams=');
writeln(ParseParams);
writeln('FPDocParams=');
@ -404,9 +413,9 @@ var
I: Integer;
XMLFile, Filename: String;
begin
if ord(Step)>=ord(frsFilesGathered) then
raise Exception.Create('TFPDocRun.FindSourceFiles not again');
if ord(Step)<ord(frsVarsInitialized) then
if ord(Step) >= ord(frsFilesGathered) then
raise Exception.Create('TFPDocRun.FindSourceFiles already called');
if ord(Step) < ord(frsVarsInitialized) then
InitVars;
if Verbosity>0 then
@ -446,21 +455,21 @@ begin
FStep:=frsFilesGathered;
end;
procedure TFPDocRun.CreateOuputDir;
procedure TFPDocRun.CreateOutputDir;
var
TargetCSSFile: String;
begin
if ord(Step)>=ord(frsOutDirCreated) then
raise Exception.Create('TFPDocRun.CreateOuputDir not again');
if ord(Step) >= ord(frsOutDirCreated) then
raise Exception.Create('TFPDocRun.CreateOutputDir already called');
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
@ -469,7 +478,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;
@ -481,10 +490,10 @@ var
Process: TProcess;
CmdLine: String;
begin
if ord(Step)>=ord(frsFPDocExecuted) then
raise Exception.Create('TFPDocRun.Run not again');
if ord(Step)<ord(frsOutDirCreated) then
CreateOuputDir;
if ord(Step) >= ord(frsFPDocExecuted) then
raise Exception.Create('TFPDocRun.Run already called');
if ord(Step) < ord(frsOutDirCreated) then
CreateOutputDir;
if ShowCmd then
begin
@ -496,7 +505,7 @@ begin
{$IFDEF MSWINDOWS}FPDocExe := ChangeFileExt(FPDocExe,'.exe');{$ENDIF}
if not FileInEnvPATH(FPDocExe) then
begin
WriteLn('Error: fpdoc ('+FPDocExe+') cannot be found. Please add its location to the PATH ',
WriteLn('Error: fpdoc ('+FPDocExe+') not 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;
@ -536,9 +545,9 @@ procedure TFPDocRun.CopyToXCTDir;
var
TargetXCTFile, SrcCHMFile, TargetCHMFile: String;
begin
if ord(Step)>=ord(frsCopiedToXCTDir) then
raise Exception.Create('TFPDocRun.CopyToXCTDir not again');
if ord(Step)<ord(frsFPDocExecuted) then
if ord(Step) >= ord(frsCopiedToXCTDir) then
raise Exception.Create('TFPDocRun.CopyToXCTDir alreay called');
if ord(Step) < ord(frsFPDocExecuted) then
RunFPDoc;
if (foCopyToXCTDir in Options)
@ -548,7 +557,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
@ -557,7 +566,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;
@ -568,9 +577,9 @@ end;
procedure TFPDocRun.Execute;
begin
writeln('===================================================================');
if ord(Step)>=ord(frsComplete) then
raise Exception.Create('TFPDocRun.Execute not again');
if ord(Step)<ord(frsCopiedToXCTDir) then
if ord(Step) >= ord(frsComplete) then
raise Exception.Create('TFPDocRun.Execute already called');
if ord(Step) < ord(frsCopiedToXCTDir) then
CopyToXCTDir;
FStep:=frsComplete;
@ -578,30 +587,76 @@ 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 in lazutils makefile.
Run.ExtraOptions:='-MObjFPC -Scghi'; // extra options from 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 in LCL makefile.
Run.ExtraOptions:='-MObjFPC -Sic'; // extra options from 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 executing, simulation ended. Stop');
writeln('Not executed, simulation ended.');
end.

10
docs/html/chmlazutilsfooter.xml Normal file
View File

@ -0,0 +1,10 @@
<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 Normal file
View File

@ -0,0 +1,10 @@
<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,122 +1,129 @@
/*
$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.
fpdoc.css
Modified for use with Lazarus LCL and LazUtils documentation
*/
body {
background: white
background: white;
color: black;
font-size: 11pt;
font-family: "San Francisco", "Roboto", "Open Sans", "Segoe UI", "Helvetica", "Arial", sans-serif;
}
body, p, th, td, caption, h1, h2, h3, ul, ol, dl {
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;
font-family: sans-serif
}
tt, span.kw, pre {
font-family: "Courier New", Courier, monospace
font-family: "Menlo", "JetBrains Mono", "Roboto Mono", "Noto Sans Mono", "Inconsolata", "Courier New", Courier, monospace;
font-size: 1em;
}
body, p, th, td, caption, ul, ol, dl, tt, span.kw, pre {
font-size: 14px
p, th, td, caption, ul, ol, dl, tt, span.kw, pre {
font-size: 1em;
}
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: 12pt
font-size: 1em;
}
/* 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
white-space: pre;
}
table caption {
font-weight: bold;
}
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 {
@ -127,36 +134,47 @@ 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: 3px double #ccc;
padding: 0.5em;
/* border: 2px solid #ccc; */
display: block;
margin: 1em 0 1em 0;
}
/* definition list: term */
dt {
/*
float: left;
clear: left;
*/
width: auto; /* normally browsers default width of largest item */
padding-right: 20px;
/* padding-right: 1.25em; */
font-weight: bold;
color: darkgreen;
}
/* definition list: description */
dd {
margin: 0 0 0 110px;
margin: 0 0 0 2em;
padding: 0 0 0.5em 0;
}
@ -164,3 +182,15 @@ 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 Normal file
View File

@ -0,0 +1,8 @@
<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>

13
docs/html/locallclfooter.xml
View File

@ -1,5 +1,8 @@
<table cellspacing="0" cellpadding="0" class="bar" width="100%">
<tr>
<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>
<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-7530dcb21a</td>
<td class='footer-date'>Generated 2021-10-27</td>
</tr>
</table>