FpDoc images in .chm (?)
lazarus / 8-Other

----------------------------------------------------------------------
PaulANormanNZ · 2020-06-24 13:12

Hi,

My CHM is making up overall very nicely, fpdoc is an amazing pices of
software :-)

CSS is including nicely

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i --css-file=
G:/LaTeXPortable/LatexUtils/TeXworks/0-4-5/config/scripts/Trials/blah
... blah/Lazarus/LazDE/fpdoc.css
However I am obviously missing something so basic about incorporationg
images.

I have been trying to include images in my CHM.
"blah ... blah" -- in the file paths below is only an abbreviation.

I have tried under both Lazarus
fpc 3.0.4

And a seperate fpc installation...
FPC 3.2.0

I read in the dos shell help for fpdoc ...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i Output
format "chm" supports the following options: --image-url=url         
     Prefix image URLs with url
I read on

https://www.freepascal.org/docs-
html/current/fpdoc/fpdocsu17.html#x29-280003.2.17

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i 3.2.17
image-url This option tells the HTML backend where the images are
located: the argument must be an absolute URL. By default, the images
are assumed to be in a images directory below the package directory.
Note that the URL must be absolute, i.e. if it is provided, the link
to the image will be composed from the argument of this option with
the filename. Example:--image-url=http://www.mysite.org/docs/pictures/
So I have my images in a directory images below the package directory.

And in a <description> tag in my XML I have:

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i <img
file="Tform_main.btn_Open.png" caption="Get Source Text"/>
And in my BUILD / Other Options in the Lazarus Documentation Editor I
have tried among other  options...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://0.0.0.0:8000/
And

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://localhost:8000/
I am sucessfully running a PHP server in the images directory ...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i
G:\LaTeXPortable\LatexUtils\TeXworks\0-4-5\config\scripts\Trials\blah
... blah\Lazarus\LazDE\images>php -S localhost:8000PHP 5.5.10
Development Server started at Thu Jun 25 00:21:56 2020Listening on
http://localhost:8000 
I have confimred the setup as I can sucessfully see the image in a
browser on the local machine:

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i
http://localhost:8000/TForm_main.btn_Open.png

However my CHM never shows anything other than a black square with a
white cross in it where the image ought appear, and right mouse
properties for that square says...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  mk:@MSITSt
ore:G:\LaTeXPortable\LatexUtils\TeXworks\0-4-
5\config\scripts\\Trials\blah ... blah\Lazarus\LazDE\KJVwords.chm::/ht
tp://localhost:8000/Tform_main.btn_Open.png
I even tried removing the

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://localhost:8000/
But of course that fails too.

Any pointers on how to get images showing in CHMs would be greatly
appreciated please.

What am I missing?

TIA
Paul

----------------------------------------------------------------------
marcov · 2020-06-24 13:21

First, the html document is not entirely the same as the CHM backend,
specially when access to remote (outside current chm) resources is
meant.

The default solution is simply add the files to the CHM project, and
reference them with a relative path in the html.

It doesn't make sense having offline help referring to online images.

----------------------------------------------------------------------
PaulANormanNZ · 2020-06-24 23:22

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i First, the
html document is not entirely the same as the CHM backend, specially
when access to remote (outside current chm) resources is meant.
I am just endeavouring to follow the official documentation and --help
provided for fpdoc.

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i The default
solution is simply add the files to the CHM project, and reference
them with a relative path in the html.
Thanks. When using fpdoc you do not directly write any html files
themselves, nor can you directly include images or other files. You
are by whatever means writing a neutral XML file, which then can be
utilised to produce latex, text, html,, chm etc...
It is not the same as say using Microsoft's help workshop, you have no
project file for hh.exe etc to work on.

It is a novel and totally Free Pascal solution to documentation and
help making.

It's amazingly all done in memory streams with only the finished
products ever touching the harddrive. So it's very fast in publishing
the project (CHM) or whatever you elect to produce.

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i It doesn't
make sense having offline help referring to online images. 
I don't offer any comment on the sense or otherwise of it, I am just
trying to follow the only solution that the documentation so far gives
for including images in a CHM.

fpdoc, with it's close tie in to Lazarus for authoring the main XML is
a great solution which I wish to follow as it does closely tie into
the Lazarus editor, and with LAZde the main XML can be edited to
provide documentstiin both for the developer and help for the end
user.

----------------------------------------------------------------------
dsiders · 2020-06-25 01:57

Quote from: PaulANormanNZ on June 24, 2020, 03:12:13 pmHowever I am
obviously missing something so basic about incorporationg images.

...

I read in the dos shell help for fpdoc ...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i Output
format "chm" supports the following options:--image-url=url          
    Prefix image URLs with url
I read on

https://www.freepascal.org/docs-
html/current/fpdoc/fpdocsu17.html#x29-280003.2.17

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i 3.2.17
image-url This option tells the HTML backend where the images are
located: the argument must be an absolute URL. By default, the images
are assumed to be in a images directory below the package directory.
Note that the URL must be absolute, i.e. if it is provided, the link
to the image will be composed from the argument of this option with
the filename. Example:--image-url=http://www.mysite.org/docs/pictures/
So I have my images in a directory images below the package directory.

And in a <description> tag in my XML I have:

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i <img
file="Tform_main.btn_Open.png" caption="Get Source Text"/>
And in my BUILD / Other Options in the Lazarus Documentation Editor I
have tried among other  options...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://0.0.0.0:8000/
And

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://localhost:8000/
I am sucessfully running a PHP server in the images directory ...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i
G:\LaTeXPortable\LatexUtils\TeXworks\0-4-5\config\scripts\Trials\blah
... blah\Lazarus\LazDE\images>php -S localhost:8000PHP 5.5.10
Development Server started at Thu Jun 25 00:21:56 2020Listening on
http://localhost:8000 
I have confimred the setup as I can sucessfully see the image in a
browser on the local machine:

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i
http://localhost:8000/TForm_main.btn_Open.png

However my CHM never shows anything other than a black square with a
white cross in it where the image ought appear, and right mouse
properties for that square says...

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  mk:@MSITSt
ore:G:\LaTeXPortable\LatexUtils\TeXworks\0-4-
5\config\scripts\\Trials\blah ... blah\Lazarus\LazDE\KJVwords.chm::/ht
tp://localhost:8000/Tform_main.btn_Open.png
I even tried removing the

Code: Text  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  --image-
url=http://localhost:8000/
But of course that fails too.

Any pointers on how to get images showing in CHMs would be greatly
appreciated please.

What am I missing?

TIA
Paul

There is an Code: Bash  [Select][+][-]window.onload = function(){var
x1 = document.getElementById("main_content_section"); if (x1) { var x
= document.getElementsByClassName("geshi");for (var i = 0; i --image-
dir command line option according tp fpdoc.chm. It is not listed in
the help options for the fpdoc executable.

If your target is CHM, I would not expect to use a URL. Neither option
should be required if your graphic files are stored in ./images/ under
the project directory.

Just change your fpdoc tagging to:

Code: XML  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i <img
file="filename.png"/>
If you want to override the location of the images directory, then use
the Code: Bash  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i --image-
dir=/path/to/images/  notation.

Hope that helps...

----------------------------------------------------------------------
PaulANormanNZ · 2020-06-25 07:03

Thanks for that, I had unsuccessfully tried it earlier, then
discovered that the command line options can list what is available
for the specific --format you are using, you type

>fpdoc --format=chm --help

And it does not show  --image-dir= option as available for chm

Code: Bash  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i >fpdoc
--format=latex --help
—Does show the image-dir option as available for the LaTeX format—

Code: Bash  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i --image-
dir=dir                Specify the directory where the images are
stored

There is another command line help option which shows when you specify
fpdoc --format=chm --help :-

Code: Bash  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i --other-
files                  "A txt file containing a list of files to be
added relative to the working directory."
Where is: "The files should be in a subfolder of: the working
directory"?

In the FPDoc documentation we can read:

Quote3.2.25 other-files

This option specifies a text file with one filename per line to be
included in the chm.
You can include any type of file you want; it does not have to be a
html file.
For instance you can include images that you have linked to in the xml
descr files.
The files should be in a subfolder of the working directory
and within their own folder to avoid naming conflicts with the auto
generated files.
This option only applies to the chm backend.
I gave that a go.
I had to use fully qualified paths both for

--other-files=G:/LaTeXPortable/LatexUtils/TeXworks/0-4-
5/config/scripts/Trials/ <blah ... blah>
/Lazarus/LazDE/images/filelist.txt

and for the files listed in my filelist.txt
otherwise I got error messages about files not found during the Build
process.

The chm Builds with no errors...

QuoteVersion 3.2.0 [2020/06/04]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,
sg@freepascal.org
(c) 2005 - 2012 various FPC contributors


Writing 50 pages...
HTML Files written. Collecting other files and compressing...this
could take some time
Generating Table of contents...
Generating Index...
Finishing compressing...
Done.
Documentation successfully built.

But no images appear in the CHM

I opened the CHM in 7zip and there are no files included from
filelist.txt anywhere.

I created a simple "Hello World" test.txt and tried to include that
via filelist.txt and it was not added either according to 7zip later.

Without error messages I am not sure where to go next?

The phrase "The files should be in a subfolder of the working
directory" was a bit puzzling so I tried moving my images folder into
the folder where my Lazarus main.pas is—that I have fpdoc focussing
on.

Adjusting the full paths in the filelist.txt file, all again compiles
with no errors - but also without adding in any files from the
filelist.

Where is: "The files should be in a subfolder of: the working
directory"?

Is it the LazDE folder setting for "Description", "Output", "Sources",
or some other Directory?

I'm on Windows 8.1 Pro. and as stated earlier, trying FPdoc under both
Lazarus 2.0.8
fpc 3.0.4  and a separate fpc installation... FPC 3.2.0)

My last Build output (reformatted for readability) in case some one
can spot any error on my part—

Quote
Building docs using command:

E:\FPC\3.2.0\bin\i386-win32\fpdoc.exe
--package=LISTwords
--output=G:\LaTeXPortable\LatexUtils\TeXworks\0-4-
5\config\scripts\Trials\ < ... blahh blahh ..
>\Lazarus\LazDE\LISTwords.chm
--format=chm
--auto-toc
--auto-index
--make-searchable
--content
--descr=G:\LaTeXPortable\LatexUtils\TeXworks\0-4-
5\config\scripts\Trials\ < ... blahh blahh .. >\Lazarus\LazDE\main.xml
--input=G:\LaTeXPortable\LatexUtils\TeXworks\0-4-
5\config\scripts\Trials\ < ... blahh blahh .. >\Lazarus\main.pas
--dont-trim 
--footer-date=mmm-dd-yyyy 
--other-files=G:/LaTeXPortable/LatexUtils/TeXworks/0-4-
5/config/scripts/Trials/ < ... blahh blahh .. >/Lazarus/filelist.txt
--css-
file=G:/LaTeXPortable/LatexUtils/TeXworks/0-4-5/config/scripts/Trials/
< ... blahh blahh .. >/Lazarus/LazDE/fpdoc.css

FPDoc - Free Pascal Documentation Tool
Version 3.2.0 [2020/06/04]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,
sg@freepascal.org
(c) 2005 - 2012 various FPC contributors

Writing 50 pages...
HTML Files written. Collecting other files and compressing...this
could take some time
Generating Table of contents...
Generating Index...
Finishing compressing...
Done.
Documentation successfully built.
— I might next try to make a very minimalistic MWE Lazarus/fpdoc
project just testing incorporating one image in the CHM, if necessary.

I still feel FPdoc is excellent and would like to know how to get all
this working please.

----------------------------------------------------------------------
wp · 2020-06-25 08:37

I suggest to post this question on the Lazarus mailing list. Michael
Van Canneyt who, to my knowledge, is the author of fpdoc does not read
the forum, but the mailing list. If you're not yet registered,
register here: https://lists.lazarus-ide.org/listinfo/lazarus

----------------------------------------------------------------------
PaulANormanNZ · 2020-06-25 09:43

QuoteI suggest to post this question on the Lazarus mailing list.
Michael Van Canneyt who, to my knowledge, is the author of fpdoc does
not read the forum, but the mailing list. ...
Yes I may need to do that for --include-files=filelist.txt

Bearing the phrase "Working Directory" in mind and thinking of old DOS
days, I found that by launching LazDE from a batch file in a dos shell
opened on the Lazarus project directory with a sub folder images under
it, FPdoc picks out the <img file= references in any description tag,

Code: XML  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i  e.g. <img
file="images/Tform_main.btn_Open.png" caption="Get Source Text"/>
And incorporates them (only) in an images directory within the CHM.

This makes sense when reading the FpDoc chm help entry for  3.2.17
--image-url=

QuoteThis option tells the HTML backend where the images are located:
the argument must be an absolute URL. By default, the images are
assumed to be in a images directory below the package directory. Note
that the URL must be absolute, i.e. if it is provided, the link to the
image will be composed from the argument of this option with the
filename.

Although out of context to a discussion for urls

QuoteExample:
--image-url=http://www.mysite.org/docs/pictures/
Code: Bash  [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i By default,
the images are assumed to be in a images directory below the package
directory
Suggests that by default fpDoc when building a CHM will look for any
images referenced by <img file= tags in  the working directory's sub-
directory called images.

And so it appears to do.

--image-dir= is not available for setting under --format=chm


Still have to get to the bottom of the 3.2.25 --other-files =

fpDoc recognises a relative path down from my main Lazarus project
directory now in my filelist.txt, and as expected (a test:) reports an
error if I change a  file name in there, but when all the names are
correct, it Builds with out errors, but still does not drag any of the
filelist.txt named files into the CHM.

If/When I get this sorted I might write up a Wiki as one an approach
for easily using it all for both  Developer and End User integrated
CHMs etc..

----------------------------------------------------------------------
marcov · 2020-06-25 10:57

Please make a small code/fpdoc example project, attach it to a bug in
the bugtracker along with your fpdoc commandline.