diff --git a/docs/html/build_chm.bat b/docs/html/build_chm.bat index ce4f7f26ca..1104cad1c1 100644 --- a/docs/html/build_chm.bat +++ b/docs/html/build_chm.bat @@ -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= ./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="
" & echo.) > locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="" & echo.) >> locallclfooter.xml +echo|(set /p="
Lazarus Component Library (LCL)Version %verno%-%commit%Generated %dt%
" & echo.) >> locallclfooter.xml + +REM chm footer for releases (no commit info - assumes the tag is enough) +echo|(set /p="
" & echo.) > chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="" & echo.) >> chmlclfooter.xml +echo|(set /p="
Lazarus Component Library (LCL)Version %verno% (%dt%)" & echo.) >> chmlclfooter.xml +echo|(set /p="HTML version (Online)" & echo.) >> chmlclfooter.xml +echo|(set /p="
" & 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="
" & echo.) > locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="" & echo.) >> locallazutilsfooter.xml +echo|(set /p="
Lazarus Utilities (LazUtils)Version %verno%-%commit%Generated %dt%
" & echo.) >> locallazutilsfooter.xml + +REM chm footer (no commit info - assumes the tag is enough) +echo|(set /p="
" & echo.) > chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="
Lazarus Utilties (LazUtils)Version %verno% (%dt%)" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="HTML version (Online)" & echo.) >> chmlazutilsfooter.xml +echo|(set /p="
" & 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 diff --git a/docs/html/build_chm.sh b/docs/html/build_chm.sh index 1255e2bf26..1c4bc60e77 100755 --- a/docs/html/build_chm.sh +++ b/docs/html/build_chm.sh @@ -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 < ./locallclfooter.xml +
+ + + + + + +
Lazarus Component Library (LCL)Version $verno-$commitGenerated $dt
+EOT + +# chm footer for releases (no commit info - assumes the tag is enough) +cat < ./chmlclfooter.xml +
+ + + + + + +
Lazarus Component Library (LCL)Version $verno ($dt) + HTML version (Online) +
+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 < ./locallazutilsfooter.xml +
+ + + + + + +
Lazarus Utilities (LazUtils)Version $verno-$commitGenerated $dt
+EOT + +# chm footer for releases (no commit info - assumes the tag is enough) +cat < ./chmlazutilsfooter.xml +
+ + + + + + +
Lazarus Utilities (LazUtils)Version $verno ($dt) + HTML version (Online) +
+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 diff --git a/docs/html/build_html.bat b/docs/html/build_html.bat index 08e0711d03..33dd8244c2 100644 --- a/docs/html/build_html.bat +++ b/docs/html/build_html.bat @@ -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 \ No newline at end of file +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\ diff --git a/docs/html/build_html.sh b/docs/html/build_html.sh index bd08285f01..1c0227388c 100755 --- a/docs/html/build_html.sh +++ b/docs/html/build_html.sh @@ -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/ diff --git a/docs/html/build_lcl_docs.lpi b/docs/html/build_lcl_docs.lpi index 4673eb69b4..5db4dfdb9f 100644 --- a/docs/html/build_lcl_docs.lpi +++ b/docs/html/build_lcl_docs.lpi @@ -1,14 +1,17 @@ - + + + + + - </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 '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 'Lazarus Run Output' -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> @@ -60,5 +63,10 @@ <UseAnsiStrings Value="False"/> </SyntaxOptions> </Parsing> + <Linking> + <Debugging> + <GenerateDebugInfo Value="False"/> + </Debugging> + </Linking> </CompilerOptions> </CONFIG> diff --git a/docs/html/build_lcl_docs.lpr b/docs/html/build_lcl_docs.lpr index 52920d00c0..662ea3b8ff 100644 --- a/docs/html/build_lcl_docs.lpr +++ b/docs/html/build_lcl_docs.lpr @@ -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. - diff --git a/docs/html/chmlazutilsfooter.xml b/docs/html/chmlazutilsfooter.xml new file mode 100644 index 0000000000..2d615dd144 --- /dev/null +++ b/docs/html/chmlazutilsfooter.xml @@ -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> diff --git a/docs/html/chmlclfooter.xml b/docs/html/chmlclfooter.xml new file mode 100644 index 0000000000..0ea4fc5aef --- /dev/null +++ b/docs/html/chmlclfooter.xml @@ -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> diff --git a/docs/html/fpdoc.css b/docs/html/fpdoc.css index 6cb58a41b8..f28906ed57 100644 --- a/docs/html/fpdoc.css +++ b/docs/html/fpdoc.css @@ -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; } diff --git a/docs/html/locallazutilsfooter.xml b/docs/html/locallazutilsfooter.xml new file mode 100644 index 0000000000..4b182e4604 --- /dev/null +++ b/docs/html/locallazutilsfooter.xml @@ -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> diff --git a/docs/html/locallclfooter.xml b/docs/html/locallclfooter.xml index 8503e405d3..28d7d9aef5 100644 --- a/docs/html/locallclfooter.xml +++ b/docs/html/locallclfooter.xml @@ -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>