mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-04-06 06:38:03 +02:00
Docs: build_lcl_docs. Fixes an incompatibility with FPDoc 3.3.x.
* FPDoc 3.3.X changed the syntax for the --footer argument. It uses an ''@' prefix for file names and treats anythine else as text for the footer.. build_lcl_docs did not handle that syntax. Since we do not know which version of FPDoc will be used, we must handle both. * Accepts --footer=filename.ext for 3.2.X. * Accepts --footer=@filename.ext for 3.3.X. * Accepts --footer="Your text here" for 3.3.X. * File name expansion and validation occurs in the setter for TFPDocRun.FooterFilename. * Modifies README.txt and all of the script files (.bat, .sh) to document requirements and usage.
This commit is contained in:
dsiders
parent
5e581ce962
commit
2f59545512
@ -1,23 +1,79 @@
|
||||
HTML documentation of Lazarus
|
||||
=============================
|
||||
CHM and HTML Documentation for Lazarus
|
||||
======================================
|
||||
|
||||
This directory contains the tools to create the HTML and CHM documentation for
|
||||
Lazarus. The documentation is stored in fpdoc format in the docs/xml/ directory.
|
||||
|
||||
The build_lcl_docs program requires a docs/chm directory which contains rtl.xct
|
||||
and fcl.xct. The process fails if either the directory or the files are missing.
|
||||
The process creates lcl and lazutils subdirectories for output.
|
||||
Update the content in locallclfooter.xml before starting the script.
|
||||
|
||||
Scripts contain a path to the FPDoc program which may need to be updated
|
||||
to match your local installation. This allows either FPDoc version 3.2.X or
|
||||
3.3.X to be used to generate documentation formats.
|
||||
|
||||
Note: It is recommended to use the FPDoc version from FPC trunk (main).
|
||||
If you are unlucky and got a buggy revision, you can try with the released
|
||||
FPDoc program.
|
||||
|
||||
|
||||
For UNIXes:
|
||||
|
||||
The script build_html.sh will automatically create the whole HTML
|
||||
documentation.
|
||||
Build build_lcl_docs.lpi
|
||||
../../lazbuild build_lcl_docs.lpi
|
||||
build_html.sh and build_chm.sh will automatically create the documentation for the
|
||||
output formats.
|
||||
|
||||
./build_lcl_docs --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc --fpcdocs=../chm --outfmt chm --footer locallclfooter.xml
|
||||
Build build_lcl_docs.lpi:
|
||||
../../lazbuild build_lcl_docs.lpi
|
||||
|
||||
Update the PATH environment variable in build_chm.bat and build_html.bat for
|
||||
your local installation. Run the script(s), or run build_lcl_docs.exe directly.
|
||||
|
||||
Run a script:
|
||||
./build_chm.sh
|
||||
./build_html.sh
|
||||
|
||||
Run the program:
|
||||
./build_lcl_docs --fpdoc /path/to/trunk/fpdoc/fpdoc --fpcdocs=../chm --outfmt chm --footer locallclfooter.xml
|
||||
|
||||
Note: It is recommened to use the fpdoc from fpc trunk. If you are unlucky and got a buggy revision, you can try with the released fpdoc.
|
||||
|
||||
For Windows:
|
||||
|
||||
Build the project build_lcl_docs.lpi, fix the PATH in the build_html.bat batch
|
||||
script to your local installation and then run the script, or run
|
||||
build_lcl_docs.exe directly.
|
||||
build_html.bat and build_chm.bat will automatically create the documentation for the
|
||||
output formats.
|
||||
|
||||
Build build_lcl_docs.lpi:
|
||||
..\..\lazbuild.exe build_lcl_docs.lpi
|
||||
|
||||
Update the PATH environment variable in build_chm.bat and build_html.bat for
|
||||
your local installation. Run the script(s), or run build_lcl_docs.exe directly.
|
||||
|
||||
Run a script:
|
||||
.\build_chm.bat
|
||||
.\build_html.bat
|
||||
|
||||
Run the program:
|
||||
.\build_lcl_docs.exe --fpdoc \path\to\trunk\fpdoc --fpcdocs=..\chm --outfmt chm --footer locallclfooter.xml
|
||||
.\build_lcl_docs.exe --fpdoc \path\to\trunk\fpdoc --fpcdocs=..\chm --outfmt html --footer locallclfooter.xml
|
||||
|
||||
|
||||
FPDoc Version Differences
|
||||
|
||||
When using FPDoc 3.3.1 or higher, the syntax for the --footer argument was changed.
|
||||
|
||||
For FPDoc version 3.2.X, the syntax is:
|
||||
|
||||
--footer=path/to/filename.ext
|
||||
|
||||
For FPDoc verions 3.3.X, the syntax requires an @ symbol as a prefix for the file
|
||||
name. For example:
|
||||
|
||||
--footer=@path/to/filename.ext
|
||||
|
||||
FPDoc verions 3.3.X allows a string of text to used as the footer. For example:
|
||||
|
||||
--footer="(c) 2022. All rights reserved."
|
||||
|
||||
|
||||
All of the scripts have a commented version of the various command using the FPDoc 3.3.X
|
||||
syntax. Use the one needed for your system and FPDoc version.
|
||||
|
||||
@ -1,11 +1,31 @@
|
||||
REM
|
||||
REM Builds all Lazarus docs and pack them in one .chm file
|
||||
REM Builds Lazarus documentation for LCL and LazUtils in CHM format.
|
||||
REM
|
||||
REM Requires a $(LazarusDir)\docs\chm directory which contains rtl.xct and fcl.xct.
|
||||
REM Process fails if either the directory or the files are missing.
|
||||
REM Process creates .\lcl and .\lazutils subdirectories for CHM output.
|
||||
REM Update the content in locallclfooter.xml before starting the script.
|
||||
REM
|
||||
REM Notes:
|
||||
REM
|
||||
REM 1 - If necessary, please fix the path so it finds fpdoc.exe (normally in your fpc compiler dir)
|
||||
REM 2 - Before running this file, first compile the project build_lcl_docs.lpi
|
||||
REM ..\..\lazbuild.exe build_lcl_docs.lpi
|
||||
REM
|
||||
PATH=D:\programming\fpc\bin\i386-win32\;%PATH%
|
||||
build_lcl_docs.exe --outfmt chm
|
||||
|
||||
REM PATH=C:\lazarus\fpc\3.2.2\bin\x86_64-win64;%PATH%
|
||||
PATH=C:\fpc331\fpc\bin\x86_64-win64;%PATH%
|
||||
|
||||
REM build chm output without footers
|
||||
.\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm
|
||||
|
||||
REM For FPDoc 3.2.X: build chm output with footers in locallclfooter.xml
|
||||
REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer=locallclfooter.xml
|
||||
|
||||
REM For FPDoc 3.3.X: build chm output with footers in locallclfooter.xml
|
||||
REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer=@locallclfooter.xml
|
||||
|
||||
REM For FPDoc 3.3.X: build chm output with footer text
|
||||
REM .\build_lcl_docs.exe --outfmt=chm --fpcdocs=..\chm --footer="(c) 2022. All rights reserved."
|
||||
|
||||
pause
|
||||
|
||||
@ -1,7 +1,30 @@
|
||||
#!/bin/bash
|
||||
# Builds all Lazarus docs and pack them in one .chm file
|
||||
#
|
||||
../../lazbuild build_lcl_docs.lpi
|
||||
./build_lcl_docs --outfmt chm --fpcdocs=../chm --footer locallclfooter.xml
|
||||
|
||||
# Preferably: use trunk fpdoc: --fpdoc /path/to/fpc/trunk/utils/fpdoc/fpdoc
|
||||
#
|
||||
# Builds Lazarus documentaiton for LCL and LazUtils in CHM format.
|
||||
# Requires a $(LazarusDir)/docs/chm directory which contains rtl.xct and fcl.xct.
|
||||
# Process fails if either the directory or the files are missing.
|
||||
# Process creates ./lcl and ./lazutils subdirectories for CHM output.
|
||||
# Update the content in locallclfooter.xml if needed before starting the script.
|
||||
#
|
||||
|
||||
# Path to the fpdoc program
|
||||
# The trunk (main) version of fpdoc is recommended.
|
||||
# CHANGE THIS TO A PATH VALID FOR YOUR SYSTEM AND FPDOC VERSION.
|
||||
#fpdocpath="../../fpc/3.2.2/bin/x86_64-win64"
|
||||
fpdocpath="../../../fpc331/fpc/bin/x86_64-win64"
|
||||
|
||||
# rebuild if needed
|
||||
#../../lazbuild build_lcl_docs.lpi
|
||||
|
||||
# build chm output without footers
|
||||
./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc
|
||||
|
||||
# For FPDoc 3.2.X: build chm output with footers in locallclfooter.xml
|
||||
#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=locallclfooter.xml
|
||||
|
||||
# For FPDoc 3.3.X: build chm output with footers in locallclfooter.xml
|
||||
#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=@locallclfooter.xml
|
||||
|
||||
# For FPDoc 3.3.X: build chm output with footer text
|
||||
#./build_lcl_docs --outfmt=chm --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer="(c) Copyright 2022. All rights reserved."
|
||||
|
||||
@ -1,11 +1,31 @@
|
||||
REM
|
||||
REM Builds all Lazarus docs
|
||||
REM Builds Lazarus documentation for LCL and LazUtils in HTML format.
|
||||
REM
|
||||
REM Requires a $(LazarusDir)\docs\chm directory which contains rtl.xct and fcl.xct.
|
||||
REM Process fails if either the directory or the files are missing.
|
||||
REM Process creates .\lcl and .\lazutils subdirectories for HTML output.
|
||||
REM Update the content in locallclfooter.xml before starting the script.
|
||||
REM
|
||||
REM Notes:
|
||||
REM
|
||||
REM 1 - If necessary, please fix the path so it finds fpdoc.exe (normally in your fpc compiler dir)
|
||||
REM 2 - Before running this file, first compile the project build_lcl_docs.lpi
|
||||
REM ..\..\lazbuild.exe build_lcl_docs.lpi
|
||||
REM
|
||||
PATH=C:\Programas\lazarus22\fpc\2.2.0\bin\i386-win32;%PATH%
|
||||
build_lcl_docs.exe
|
||||
pause
|
||||
|
||||
REM PATH=C:\lazarus\fpc\3.2.2\bin\x86_64-win64;%PATH%
|
||||
PATH=C:\fpc331\fpc\bin\x86_64-win64;%PATH%
|
||||
|
||||
REM build html output without footers
|
||||
REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm
|
||||
|
||||
REM For FPDoc 3.2.X: build html output with footers in locallclfooter.xml
|
||||
REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer=locallclfooter.xml
|
||||
|
||||
REM For FPDoc 3.3.X: build html output with footers in locallclfooter.xml
|
||||
.\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer=@locallclfooter.xml
|
||||
|
||||
REM For FPDoc 3.3.X: build html output with footer text
|
||||
REM .\build_lcl_docs.exe --outfmt=html --fpcdocs=..\chm --footer="(c) 2022. All rights reserved."
|
||||
|
||||
pause
|
||||
|
||||
@ -1,14 +1,30 @@
|
||||
#!/bin/bash
|
||||
# Builds all Lazarus docs and pack them in one .chm file
|
||||
#
|
||||
# Notes:
|
||||
#
|
||||
# Before running this file, first compile the project build_lcl_docs.lpi
|
||||
#
|
||||
# In order to link to RTL and FCL, place rtl.xct and fcl.xct in ../chm/
|
||||
#
|
||||
# This uses the fpdoc in PATH. See README.txt
|
||||
#
|
||||
./build_lcl_docs --fpcdocs=../chm --outfmt html
|
||||
|
||||
#
|
||||
# Builds Lazarus documentaiton for LCL and LazUtils in HTML format.
|
||||
# Requires a $(LazarusDir)/docs/chm directory which contains rtl.xct and fcl.xct.
|
||||
# Process fails if either the directory or the files are missing.
|
||||
# Process creates ./lcl and ./lazutils subdirectories for HTML output.
|
||||
# Update the content in locallclfooter.xml if needed before starting the script.
|
||||
#
|
||||
|
||||
# Path to the fpdoc program
|
||||
# The trunk (main) version of fpdoc is recommended.
|
||||
# CHANGE THIS TO A PATH VALID FOR YOUR SYSTEM AND FPDOC VERSION.
|
||||
#fpdocpath="../../fpc/3.2.2/bin/x86_64-win64"
|
||||
fpdocpath="../../../fpc331/fpc/bin/x86_64-win64"
|
||||
|
||||
# rebuild if needed
|
||||
#../../lazbuild build_lcl_docs.lpi
|
||||
|
||||
# build html output without footers
|
||||
./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc
|
||||
|
||||
# For FPDoc 3.2.X: build html output with footers in locallclfooter.xml
|
||||
#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=locallclfooter.xml
|
||||
|
||||
# For FPDoc 3.3.X: build html output with footers in locallclfooter.xml
|
||||
#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer=@locallclfooter.xml
|
||||
|
||||
# For FPDoc 3.3.X: build html output with footer text
|
||||
#./build_lcl_docs --outfmt=html --fpcdocs=../chm --fpdoc=$fpdocpath/fpdoc --footer="(c) Copyright 2022. All rights reserved."
|
||||
|
||||
@ -239,11 +239,41 @@ begin
|
||||
FCSSFile:=AValue;
|
||||
end;
|
||||
|
||||
{ Handles fpdoc 3.3.1 changed usage of the --footer argument. It can be
|
||||
either a string with the content for the footer, or a file name when
|
||||
prefixed with @. Handles both old and new syntax.
|
||||
@ cannot be included in the call to TrimAndExpandFilename.
|
||||
All file name validation occurs here. }
|
||||
procedure TFPDocRun.SetFooterFilename(AValue: String);
|
||||
var
|
||||
vFilename: String;
|
||||
begin
|
||||
AValue:=TrimAndExpandFilename(AValue);
|
||||
if FFooterFilename=AValue then Exit;
|
||||
FFooterFilename:=AValue;
|
||||
vFileName := '';
|
||||
if (AValue <> '') then
|
||||
begin
|
||||
// check for fpdoc 3.3.1 file name with @ prefix
|
||||
if (AValue[1] = '@') then
|
||||
begin
|
||||
vFilename := TrimAndExpandFilename(Copy(AValue, 2, Length(AValue)-1));
|
||||
if not FileExistsUTF8(vFileName) then
|
||||
AValue := '"Footer file not found: @' + vFileName + '"'
|
||||
else
|
||||
AValue := '@' + vFilename;
|
||||
end
|
||||
// wrap anything with spaces in Quote characters when needed
|
||||
else if (Pos(' ', AValue) <> 0) and (aValue[1] <> '"') then
|
||||
begin
|
||||
AValue :='"' + AValue + '"';
|
||||
end
|
||||
// expand and validate file name without the @ prefix
|
||||
else
|
||||
begin
|
||||
vFilename := TrimAndExpandFilename(AValue);
|
||||
if FileExistsUTF8(vFileName) then AValue := vFilename;
|
||||
end;
|
||||
end;
|
||||
if FFooterFilename = AValue then Exit;
|
||||
FFooterFilename := AValue;
|
||||
end;
|
||||
|
||||
procedure TFPDocRun.SetPasSrcDir(AValue: string);
|
||||
@ -349,7 +379,10 @@ begin
|
||||
Params.Add('--css-file='+ExtractFileName(CSSFile)); // the css file is copied to the OutDir
|
||||
end;
|
||||
|
||||
if (FooterFilename<>'') and FileExistsUTF8(FooterFilename) then
|
||||
{ In fpdoc 3.3.1 footerfilename is no longer just a file name. It can be the
|
||||
footer text or a file name when prefixed with @.
|
||||
Validation and quoting handled in the property setter. }
|
||||
if (FooterFilename<>'') then // and FileExistsUTF8(FooterFilename) then
|
||||
Params.Add('--footer='+FooterFilename);
|
||||
|
||||
if EnvParams<>'' then
|
||||
|
||||
Loading…
Reference in New Issue
Block a user