[Lazarus] Building help files: the nitty-gritty

classic Classic list List threaded Threaded
111 messages Options
123456
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mark Morgan Lloyd wrote:

>>> unpack. The .txt file says copy the files to docs/html which I'm
>>> assuming is wrong, so I end up with .chm (etc.) files in
>>> /usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks
>>> them up automatically.
>>
>> Yes, the paths are a little bit confusing.
>
> I've been working through this several times with the intention of
> putting Lazarus docs build (from source) plus FPC docs copy (from
> binaries) into my usual build/installation scripts, but am finding that
> the FPC (RTL etc.) stuff is only picked up intermittently. Is there a
> cache to be cleared somewhere or something comparable?

I see from the .txt file that RTL etc. help is supposed to not work in
the Lazarus IDE at present. But it doesn't not work all the time, on a
couple of occasions it's been fine but I can't pin down the conditions.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mark Morgan Lloyd
Mark Morgan Lloyd wrote:

> Graeme Geldenhuys wrote:
>
>>> [Nod] I suspect that we're not the only people asking for guidance.
>>
>> And it seems everybody is reluctant to give an answer. I guess LCL
>> based applications simply don't ship with help? Well, for the few LCL
>> based apps I have tried (excluding Lazarus IDE), that sure was the
>> case.
>>
>> I just remembered form years ago when I still used Delphi 5 & 7, we
>> used to use a product called HelpScribble to author our .HLP help
>> files. HelpScribble now supports .CHM authoring too. So I guess that
>> answers my own question. You need to purchase a proprietary CHM help
>> authoring tool to generate your own CHM help, and you'll probably be
>> limited to author those help files under Windows only.
>
> I didn't make a note of the URL, but I noticed a Debian bugtracker entry
> yesterday where somebody was requesting that chmcmd/chmls be packaged
> separately since they're the only free tools that do the job.
>
> The bottom line appears to be: generate either XML or HTML files, make a
> list of their names, and run the lot through chmcmd to produce a single
> indexed file. In principle, it should be possible to postprocess
> something like a .pdf to generate very simple context help entries (take
> any heading prefixed by e.g. ยง as a help keyword, and the following
> paragraph as the associated text).

OK, I can extract marked text from (plaintext derived from) a .pdf, save
entries as individual html files with a title tag in the header, and
build a .chm. Running chmls on the .chm produces sensible output.

So how do I integrate the .chm with a minimal Lazarus project to prove
it works?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
In reply to this post by Mark Morgan Lloyd


Mark Morgan Lloyd <[hidden email]> hat am 13. Juli 2012 um 10:54 geschrieben:

>[...]
> > I've been working through this several times with the intention of
> > putting Lazarus docs build (from source) plus FPC docs copy (from
> > binaries) into my usual build/installation scripts, but am finding that
> > the FPC (RTL etc.) stuff is only picked up intermittently. Is there a
> > cache to be cleared somewhere or something comparable?
>
> I see from the .txt file that RTL etc. help is supposed to not work in
> the Lazarus IDE at present. But it doesn't not work all the time, on a
> couple of occasions it's been fine but I can't pin down the conditions.

 

Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp will open them. Even links between them should work.

 

Mattias 


--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
In reply to this post by Mark Morgan Lloyd
On 13-7-2012 10:54, Mark Morgan Lloyd wrote:

> Mark Morgan Lloyd wrote:
>
>>>> unpack. The .txt file says copy the files to docs/html which I'm
>>>> assuming is wrong, so I end up with .chm (etc.) files in
>>>> /usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks
>>>> them up automatically.
>>>
>>> Yes, the paths are a little bit confusing.
>>
>> I've been working through this several times with the intention of
>> putting Lazarus docs build (from source) plus FPC docs copy (from
>> binaries) into my usual build/installation scripts, but am finding
>> that the FPC (RTL etc.) stuff is only picked up intermittently. Is
>> there a cache to be cleared somewhere or something comparable?
No idea...

Ludo's and my tool fpcup put the binary FPC docs chms and compile the
Lazarus chms in the old location (lazarus\docs\html) which seems to work
fine...
As (IIRC) Mattias explains elsewhere, using the CHM directory for chm
files is a relatively new addition to Lazarus and the html location is
also searched for compatibility's sake; our fpcup was running before
that ;) (We might look into changing that for consistency.)

There is of course the settings on where to find the chm files in
Lazarus tools/options/help options, CHM Help Viewer, HelpFilesPath.
I suppose if you don't set this, Lazarus will look in html and chm;
don't know if it also searches in chm and help you set this to a
different location.

> I see from the .txt file that RTL etc. help is supposed to not work in
> the Lazarus IDE at present. But it doesn't not work all the time, on a
> couple of occasions it's been fine but I can't pin down the conditions.
You mean this text file:
lazarus\docs\html\readmechm.txt
Can't seem to find that, only this:
"Note that Lazarus does not load ref.* at this moment, so (CHM) help
on keywords does not work yet."

BTW: perhaps that readme needs an update? It mentions various viewers
for chm files which is nice to know if you want to have alternatives,
but doesn't seem to mention lhelp at all - which should be available on
all Lazarus platforms and be the default chm viewer for Lazarus anyway,
right?

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mark Morgan Lloyd
Mattias wrote:

 >>> I've been working through this several times with the intention of
>>> putting Lazarus docs build (from source) plus FPC docs copy (from
>>> binaries) into my usual build/installation scripts, but am finding
>>> that the FPC (RTL etc.) stuff is only picked up intermittently. Is
>>> there a cache to be cleared somewhere or something comparable?
>>
>> I see from the .txt file that RTL etc. help is supposed to not work in
>> the Lazarus IDE at present. But it doesn't not work all the time, on a
>> couple of occasions it's been fine but I can't pin down the conditions.
 >
 > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
 > will open them. Even links between them should work.

lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
begin or {$i) doesn't. I get IDE popups like 'Help keyword
"FPCKeyword_begin" not found.

lazarus-trunk$ find . -iname '*chm'
./components/wiki/chm
./docs/chm
./docs/chm/toc.chm
./docs/chm/user.chm
./docs/chm/fpdoc.chm
./docs/chm/prog.chm
./docs/chm/fcl.chm
./docs/chm/rtl.chm
./docs/chm/ref.chm
./docs/html/lcl/lcl.chm

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Fri, 13 Jul 2012 12:32:40 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mattias wrote:
>
>  >>> I've been working through this several times with the intention of
> >>> putting Lazarus docs build (from source) plus FPC docs copy (from
> >>> binaries) into my usual build/installation scripts, but am finding
> >>> that the FPC (RTL etc.) stuff is only picked up intermittently. Is
> >>> there a cache to be cleared somewhere or something comparable?
> >>
> >> I see from the .txt file that RTL etc. help is supposed to not work in
> >> the Lazarus IDE at present. But it doesn't not work all the time, on a
> >> couple of occasions it's been fine but I can't pin down the conditions.
>  >
>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
>  > will open them. Even links between them should work.
>
> lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
> begin or {$i) doesn't. I get IDE popups like 'Help keyword
> "FPCKeyword_begin" not found.
>
> lazarus-trunk$ find . -iname '*chm'
> ./components/wiki/chm
> ./docs/chm
> ./docs/chm/toc.chm
> ./docs/chm/user.chm
> ./docs/chm/fpdoc.chm
> ./docs/chm/prog.chm
> ./docs/chm/fcl.chm
> ./docs/chm/rtl.chm
> ./docs/chm/ref.chm
> ./docs/html/lcl/lcl.chm

Add the ref.kwd file too.

Mattias
 

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

>>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
>>  > will open them. Even links between them should work.
>>
>> lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
>> begin or {$i) doesn't. I get IDE popups like 'Help keyword
>> "FPCKeyword_begin" not found.
>>
>> lazarus-trunk$ find . -iname '*chm'
>> ./components/wiki/chm
>> ./docs/chm
>> ./docs/chm/toc.chm
>> ./docs/chm/user.chm
>> ./docs/chm/fpdoc.chm
>> ./docs/chm/prog.chm
>> ./docs/chm/fcl.chm
>> ./docs/chm/rtl.chm
>> ./docs/chm/ref.chm
>> ./docs/html/lcl/lcl.chm
>
> Add the ref.kwd file too.

It's already there, I was only showing *chm to illustrate the overall
layout. The complete list of files is

docs/chm/fcl.chm
docs/chm/fcl.xct
docs/chm/fpdoc.chm
docs/chm/prog.chm
docs/chm/readmechm.txt
docs/chm/ref.chm
docs/chm/ref.kwd
docs/chm/rtl.chm
docs/chm/rtl.xct
docs/chm/toc.chm
docs/chm/user.chm

docs/html/build_chm.bat
docs/html/build_chm.sh
docs/html/build_gtkintf_html.sh
docs/html/build_html.bat
docs/html/build_html.sh
docs/html/build_lazutils_html.sh
docs/html/build_lcl_chm.sh
docs/html/build_lcl_docs
docs/html/build_lcl_docs.compiled
docs/html/build_lcl_docs.lpi
docs/html/build_lcl_docs.lpr
docs/html/build_lcl_docs.o
docs/html/build_lcl_html.sh
docs/html/fpdoc.css
docs/html/libpbuild_lcl_docs.a
docs/html/localfclfooter.xml
docs/html/locallclfooter.xml
docs/html/localrtlfooter.xml
docs/html/Makefile
docs/html/README.txt
docs/html/sourceforgefooter.xml

docs/html/lcl:
inputfile.txt
lcl.chm
lcl.xct

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Fri, 13 Jul 2012 13:13:07 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mattias Gaertner wrote:
>
> >>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
> >>  > will open them. Even links between them should work.
> >>
> >> lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
> >> begin or {$i) doesn't. I get IDE popups like 'Help keyword
> >> "FPCKeyword_begin" not found.
> >>
> >> lazarus-trunk$ find . -iname '*chm'
> >> ./components/wiki/chm
> >> ./docs/chm
> >> ./docs/chm/toc.chm
> >> ./docs/chm/user.chm
> >> ./docs/chm/fpdoc.chm
> >> ./docs/chm/prog.chm
> >> ./docs/chm/fcl.chm
> >> ./docs/chm/rtl.chm
> >> ./docs/chm/ref.chm
> >> ./docs/html/lcl/lcl.chm
> >
> > Add the ref.kwd file too.
>
> It's already there, I was only showing *chm to illustrate the overall
> layout. The complete list of files is
>
> docs/chm/fcl.chm
> docs/chm/fcl.xct
> docs/chm/fpdoc.chm
> docs/chm/prog.chm
> docs/chm/readmechm.txt
> docs/chm/ref.chm
> docs/chm/ref.kwd
> docs/chm/rtl.chm
> docs/chm/rtl.xct
> docs/chm/toc.chm
> docs/chm/user.chm

Please try the files from here:
http://www.stack.nl/~marcov/doc-chm.zip

Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

> On Fri, 13 Jul 2012 13:13:07 +0000
> Mark Morgan Lloyd <[hidden email]> wrote:
>
>> Mattias Gaertner wrote:
>>
>>>>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
>>>>  > will open them. Even links between them should work.
>>>>
>>>> lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
>>>> begin or {$i) doesn't. I get IDE popups like 'Help keyword
>>>> "FPCKeyword_begin" not found.

> Please try the files from here:
> http://www.stack.nl/~marcov/doc-chm.zip

RTL etc. keywords only work if Lazarus is started from the .chm
directory. LCL always OK.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mark Morgan Lloyd
Mark Morgan Lloyd wrote:

> OK, I can extract marked text from (plaintext derived from) a .pdf, save
> entries as individual html files with a title tag in the header, and
> build a .chm. Running chmls on the .chm produces sensible output.
>
> So how do I integrate the .chm with a minimal Lazarus project to prove
> it works?

I've added a few lines to
http://wiki.lazarus.freepascal.org/chm_backend_for_fpdoc about where a
list of options that may appear in a .hhp file may be found, and an
example of a minimal .hhp and .hhc TOC file. Together, that should be
enough for anybody determined to use chmcmd tp "roll his own"
documentation from an obscure documentation format or CMS repository.

Am I correct in that there isn't yet a .chm viewer that can be
integrated with a user-written app?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mark Morgan Lloyd
Mark Morgan Lloyd wrote:

> Mattias Gaertner wrote:
>> On Fri, 13 Jul 2012 13:13:07 +0000
>> Mark Morgan Lloyd <[hidden email]> wrote:
>>
>>> Mattias Gaertner wrote:
>>>
>>>>>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
>>>>>  > will open them. Even links between them should work.
>>>>>
>>>>> lhelp will open them manually, but keyword help in the IDE (e.g. F1
>>>>> on begin or {$i) doesn't. I get IDE popups like 'Help keyword
>>>>> "FPCKeyword_begin" not found.
>
>> Please try the files from here:
>> http://www.stack.nl/~marcov/doc-chm.zip
>
> RTL etc. keywords only work if Lazarus is started from the .chm
> directory. LCL always OK.

Should I Mantis this to make sure it's not overlooked?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Mon, 16 Jul 2012 13:19:44 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mark Morgan Lloyd wrote:
> > Mattias Gaertner wrote:
> >> On Fri, 13 Jul 2012 13:13:07 +0000
> >> Mark Morgan Lloyd <[hidden email]> wrote:
> >>
> >>> Mattias Gaertner wrote:
> >>>
> >>>>>  > Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp
> >>>>>  > will open them. Even links between them should work.
> >>>>>
> >>>>> lhelp will open them manually, but keyword help in the IDE (e.g. F1
> >>>>> on begin or {$i) doesn't. I get IDE popups like 'Help keyword
> >>>>> "FPCKeyword_begin" not found.
> >
> >> Please try the files from here:
> >> http://www.stack.nl/~marcov/doc-chm.zip
> >
> > RTL etc. keywords only work if Lazarus is started from the .chm
> > directory. LCL always OK.
>
> Should I Mantis this to make sure it's not overlooked?

Help on "begin" works fine under Linux.

Can it find ref.chm? (See debug log)
If not, what search paths do you see?

Mattias
 

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

>>> RTL etc. keywords only work if Lazarus is started from the .chm
>>> directory. LCL always OK.
>> Should I Mantis this to make sure it's not overlooked?
>
> Help on "begin" works fine under Linux.

Well it doesn't work reliably here. Debian x86 Linux, ablutions-standard
system.

> Can it find ref.chm? (See debug log)
> If not, what search paths do you see?

My test code fragment (with line numbers):

42 {$R *.res}
43
44 begin
45   Application.Initialize;

Hitting F1 on 'Application' console shows:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=6,y=45
TIDEHelpManager.ShowHelpForSourcePosition B Success 1
TIDEHelpManager.ShowHelpForSourcePosition C
/usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706
TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1
THelpDatabase.GetNodesForPascalContexts C
FileItem.ClassName=THelpDBISourceDirectory
Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1
TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1
NewNode.Title=LCL - Lazarus Component Library Units
NewNode.URL=file://index.html
TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms"
TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL=""
TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://"
THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html
URLType=lcl.chm URLPath=forms/application.html URLParams=
TChmHelpViewer.ShowNode Filename="lcl.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm"
Xlib:  extension "RANDR" missing on display "localhost:10.0".

Without killing lhelp, moving up to 'begin' and hitting F1:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=3,y=44

The left pane on lhelp is only showing the lcl entries.

Killing Lazarus and starting in /usr/local/share/lazarus-trunk/docs/chm
which contains

-rw-r--r-- 1 markMLl markMLl 19177753 Jul 14 12:45 doc-chm.zip
-rw-rw-r-- 1 root    root     1645513 Dec 28  2011 fcl.chm
-rw-rw-r-- 1 root    root      129232 Dec 28  2011 fcl.xct
-rw-rw-r-- 1 root    root      100171 Dec 28  2011 fpdoc.chm
-rw-rw-r-- 1 root    root      678206 Dec 29  2011 lazutils.chm
-rw-rw-r-- 1 root    root      100665 Dec 29  2011 lazutils.xct
-rw-rw-r-- 1 root    root    12740179 Dec 29  2011 lcl.chm
-rw-rw-r-- 1 root    root     1275258 Dec 29  2011 lcl.xct
-rw-rw-r-- 1 root    root      385677 Dec 28  2011 prog.chm
-rw-rw-r-- 1 root    root        3854 Dec 29  2011 readmechm.txt
-rw-rw-r-- 1 root    root      617137 Dec 28  2011 ref.chm
-rw-rw-r-- 1 root    root        5501 Dec 28  2011 ref.kwd
-rw-rw-r-- 1 root    root     3121967 Dec 28  2011 rtl.chm
-rw-rw-r-- 1 root    root      344321 Dec 28  2011 rtl.xct
-rw-rw-r-- 1 root    root        6907 Dec 28  2011 toc.chm
-rw-rw-r-- 1 root    root      631049 Dec 28  2011 user.chm

On 'Application':

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=9,y=45
TIDEHelpManager.ShowHelpForSourcePosition B Success 1
TIDEHelpManager.ShowHelpForSourcePosition C
/usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706
TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1
THelpDatabase.GetNodesForPascalContexts C
FileItem.ClassName=THelpDBISourceDirectory
Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1
TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1
NewNode.Title=LCL - Lazarus Component Library Units
NewNode.URL=file://index.html
TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms"
TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL=""
TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://"
THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html
URLType=lcl.chm URLPath=forms/application.html URLParams=
TChmHelpViewer.ShowNode Filename="lcl.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
Found="/usr/local/share/lazarus-trunk/docs/chm/lcl.chm"
Xlib:  extension "RANDR" missing on display "localhost:10.0".

Moving up to 'begin' and hitting F1, lhelp gains a reference guide
section and displays appropriate info, debug shows:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=3,y=44
TChmHelpViewer.ShowNode Filename="ref.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
Found="/usr/local/share/lazarus-trunk/docs/chm/ref.chm"

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Mon, 16 Jul 2012 14:41:12 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mattias Gaertner wrote:
>[...]
> 42 {$R *.res}
> 43
> 44 begin
> 45   Application.Initialize;
>
> Hitting F1 on 'Application' console shows:
>
> TIDEHelpManager.ShowHelpForSourcePosition A
> Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=6,y=45
> TIDEHelpManager.ShowHelpForSourcePosition B Success 1
> TIDEHelpManager.ShowHelpForSourcePosition C
> /usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706
> TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1
> THelpDatabase.GetNodesForPascalContexts C
> FileItem.ClassName=THelpDBISourceDirectory
> Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1
> TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1
> NewNode.Title=LCL - Lazarus Component Library Units
> NewNode.URL=file://index.html
> TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms"
> TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL=""
> TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://"
> THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html
> URLType=lcl.chm URLPath=forms/application.html URLParams=
> TChmHelpViewer.ShowNode Filename="lcl.chm"
> SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
> Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm"

It searched lcl identifier "Application.Initialize" and found lcl.chm.
Good.

>[...]
> Moving up to 'begin' and hitting F1, lhelp gains a reference guide
> section and displays appropriate info, debug shows:
>
> TIDEHelpManager.ShowHelpForSourcePosition A
> Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=3,y=44
> TChmHelpViewer.ShowNode Filename="ref.chm"
> SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
> Found="/usr/local/share/lazarus-trunk/docs/chm/ref.chm"

It searched keyword "begin" and found ref.chm. Good.

What do you expect?

Mattias
 

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

> On Mon, 16 Jul 2012 14:41:12 +0000
> Mark Morgan Lloyd <[hidden email]> wrote:
>
>> Mattias Gaertner wrote:
>> [...]
>> 42 {$R *.res}
>> 43
>> 44 begin
>> 45   Application.Initialize;
>>
>> Hitting F1 on 'Application' console shows:
>>
>> TIDEHelpManager.ShowHelpForSourcePosition A
>> Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=6,y=45
>> TIDEHelpManager.ShowHelpForSourcePosition B Success 1
>> TIDEHelpManager.ShowHelpForSourcePosition C
>> /usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706
>> TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1
>> THelpDatabase.GetNodesForPascalContexts C
>> FileItem.ClassName=THelpDBISourceDirectory
>> Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1
>> TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1
>> NewNode.Title=LCL - Lazarus Component Library Units
>> NewNode.URL=file://index.html
>> TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms"
>> TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL=""
>> TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://"
>> THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html
>> URLType=lcl.chm URLPath=forms/application.html URLParams=
>> TChmHelpViewer.ShowNode Filename="lcl.chm"
>> SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
>> Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm"
>
> It searched lcl identifier "Application.Initialize" and found lcl.chm.
> Good.
>
>> [...]
>> Moving up to 'begin' and hitting F1, lhelp gains a reference guide
>> section and displays appropriate info, debug shows:
>>
>> TIDEHelpManager.ShowHelpForSourcePosition A
>> Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=3,y=44
>> TChmHelpViewer.ShowNode Filename="ref.chm"
>> SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"
>> Found="/usr/local/share/lazarus-trunk/docs/chm/ref.chm"
>
> It searched keyword "begin" and found ref.chm. Good.
>
> What do you expect?

THAT IT WORKS!!! You've skipped the bit where after hitting F1 on
"Application" (which worked) I moved the cursor up one line and hit it
on "begin" which didn't, because during the first run I'd started from ~
rather than from the directory that contained the files I've listed.

OK, maybe I've been ambiguous. Go back to my earlier posting and read
the middle bit like

-----8<-----
Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm"
Xlib:  extension "RANDR" missing on display "localhost:10.0".

THAT WORKED, I'M HAPPY.

Without killing lhelp, moving up to 'begin' and hitting F1:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=3,y=44

THAT *DID* *NOT* WORK AND I'M NOT HAPPY.

The left pane on lhelp is only showing the lcl entries.

Killing Lazarus and starting in /usr/local/share/lazarus-trunk/docs/chm
which contains

-rw-r--r-- 1 markMLl markMLl 19177753 Jul 14 12:45 doc-chm.zip
----->8-----

So the question boils down to: where do I give a path to either the IDE
or to lhelp, so it knows where to find ref.chm etc.?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Mon, 16 Jul 2012 15:16:33 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mattias Gaertner wrote:
> > On Mon, 16 Jul 2012 14:41:12 +0000
> > Mark Morgan Lloyd <[hidden email]> wrote:
> >
> >> Mattias Gaertner wrote:
> >> [...]
> >> 42 {$R *.res}
> >> 43
> >> 44 begin
> >> 45   Application.Initialize;
> >>
> >> Hitting F1 on 'Application' console shows:
> >>
> >> TIDEHelpManager.ShowHelpForSourcePosition A
> >> Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr  x=6,y=45
> >> TIDEHelpManager.ShowHelpForSourcePosition B Success 1
> >> TIDEHelpManager.ShowHelpForSourcePosition C
> >> /usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706
> >> TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1
> >> THelpDatabase.GetNodesForPascalContexts C
> >> FileItem.ClassName=THelpDBISourceDirectory
> >> Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1
> >> TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1
> >> NewNode.Title=LCL - Lazarus Component Library Units
> >> NewNode.URL=file://index.html
> >> TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms"
> >> TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL=""
> >> TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://"
> >> THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html
> >> URLType=lcl.chm URLPath=forms/application.html URLParams=
> >> TChmHelpViewer.ShowNode Filename="lcl.chm"
> >> SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl"

On a second thought: not good.
It should be

SearchPath="/usr/local/share/lazarus-trunk/docs/html;/usr/local/share/lazarus-trunk/docs/html/lcl;/usr/local/share/lazarus-trunk/docs/chm"

Please check Tools / Options / Help / Help Options / Viewers / CHM Help
Viewer / HelpFilesPath.
It should be empty to use the default or contain $(LazarusDir)/docs/chm.

Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

> On a second thought: not good.
> It should be
>
> SearchPath="/usr/local/share/lazarus-trunk/docs/html;/usr/local/share/lazarus-trunk/docs/html/lcl;/usr/local/share/lazarus-trunk/docs/chm"
>
> Please check Tools / Options / Help / Help Options / Viewers / CHM Help
> Viewer / HelpFilesPath.
> It should be empty to use the default or contain $(LazarusDir)/docs/chm.

It's set to /usr/local/share/lazarus-trunk/docs/html/lcl/. Setting it
blank enables access to help for begin, $R etc. Thanks for that.

I'm sorry for getting slightly irritable but I spent a lot of time at
the end of last week trying to find what I was doing wrong with my build
scripts- it was only a day later that I realised that I'd had several
ssh sessions open and set to different directories.

However, the really annoying thing is that
http://wiki.freepascal.org/Installing_Help_in_the_IDE in the section "If
you are using Lazarus from Subversion"- which if course I am- explicitly
says '"HelpFilesPath" should be, where you put the CHM files': nothing
at all about the fact that in at least some cases it's better to leave
it blank because the IDE will "do the right thing".

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Marco van de Voort
In reply to this post by Mattias Gaertner
On Fri, Jul 13, 2012 at 02:38:53PM +0200, Mattias Gaertner wrote:

> >
> > lhelp will open them manually, but keyword help in the IDE (e.g. F1 on
> > begin or {$i) doesn't. I get IDE popups like 'Help keyword
> > "FPCKeyword_begin" not found.
> >
> > lazarus-trunk$ find . -iname '*chm'
> > ./components/wiki/chm
> > ./docs/chm
> > ./docs/chm/toc.chm
> > ./docs/chm/user.chm
> > ./docs/chm/fpdoc.chm
> > ./docs/chm/prog.chm
> > ./docs/chm/fcl.chm
> > ./docs/chm/rtl.chm
> > ./docs/chm/ref.chm
> > ./docs/html/lcl/lcl.chm
>
> Add the ref.kwd file too.

ref.kwd shouldn't be needed anymore since 2.4.2, since then the ref.kwd has
been processed into the ref.chm index.

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Marco van de Voort
In reply to this post by Graeme Geldenhuys
On Tue, Jul 10, 2012 at 05:39:05PM +0100, Graeme Geldenhuys wrote:
> My question still stands though. I don't know what is the
> recommendation for "application help" with LCL based applications. eg:
> I create a new project which is a new Programming Editor. I want to
> supply a end-user help file with my binary - like all good software
> does. What help file format do I use (as the developer of that
> product), and how do I create/edit that help file?

Since linux doesn't guarantee any helpsystem, any solution is going to be a
compromise.

> Now if you tell me CHM, that means I need to ship LHelp with my
> product because Linux & Mac users don't have CHM help viewers out of
> the box.

Both have several chm viewers available (kchmviewer, gnochm, xchm). If you
were so worried about that, I wonder why you didn't work towards integrating
them into lazarus and/or its applications.

Instead you created another solution .inf with the same problem (docview)
and a few extra (no compiler, and not even a non integrated helpfile).

Somehow your actions and problems don't seem to match :-)

>But what is the source help format for CHM, and what tools (help editor) do
> I use to edit that source format, and what tool do I use to "compile" that
> source help format into the end result CHM file?

The last time this came up, Michael said there was support in fpdoc for
general helpfiles. But afaik there are no examples.

In theory CHM files can be created with any html tool, can be organized with normal MS
html workshop, and then compiled using FPC's chmcmd (2.4.4 in theory, but
2.6.0's is better)

> Also, how does my product know where to find LHelp (or whatever CHM viewer
> I want to use)?

That's a *nix/Linux, not a Lazarus problem. If the OS is braindead and doesn't
support this, what's other option is there then to do it yourself?

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
Hi Marco,

Nice chatting to an old friend again. ;-)

On 16 July 2012 20:14, Marco van de Voort <[hidden email]> wrote:
>
> Since linux doesn't guarantee any helpsystem, any solution is going to be a
> compromise.

It's not about Linux not having a dedicated help system, it is about
what works with LCL-based applications. And more specifically about
context sensitive help in those applications. eg: I don't want my
users to press F1 and then be taken to the start page of the help
(this is how most Linux Gnome/KDE apps currently work, and that is
totally braindead!). I mean like the focus is in an edit field, and F1
will give help about that specific edit field, or fall-back to help
about that specific dialog. That is context sensitive help in
applications, and how help is supposed to work.

Incidentally, this is how all my fpGUI based apps work too, but I
simply couldn't find similar information or solutions for LCL-based
applications, hence my question here.


>> Now if you tell me CHM, that means I need to ship LHelp with my
>> product because Linux & Mac users don't have CHM help viewers out of
>> the box.
>
> Both have several chm viewers available (kchmviewer, gnochm, xchm). If you

As I told somebody in a earlier reply, I don't mind shipping the help
viewer - that is not a problem at all. I just don't want to leave it
up to chance... eg: maybe no CHM help viewer is installed, so then
application help doesn't work. Or, as is currently the case under
Linux, each CHM help viewer has vastly different features and
performance. I'd much rather use a specific help viewer, and know what
experience my end-users will have.


> The last time this came up, Michael said there was support in fpdoc for
> general helpfiles. But afaik there are no examples.

And I'll say that that is absolute rubbish. fpdoc was designed as a
source code documentation tool, and that is what it is good at. It
definitely doesn't have the design or features required for
application help.


> In theory CHM files can be created with any html tool, can be organized with normal MS
> html workshop, and then compiled using FPC's chmcmd (2.4.4 in theory, but
> 2.6.0's is better)

So where do you define the TOC or Index items? Inside the HTML files?
Is there documentation or a wiki page on the usage of chmcmd?

I searched the wiki and would these two useless pages:

   http://wiki.freepascal.org/htmlhelp_compiler
   http://wiki.freepascal.org/chmcmd

Neither describes how to actually create application help, define a
TOC or setup Index entries.

And this URL...
       http://wiki.freepascal.org/Add_Help_to_Your_Application
...explains a bit more, but uses plain HTML files located in a folder.
Still no TOC, Index or Search support, because they are simple HTML
files that will be viewer with a web browser, and not CHM help.

As I mentioned in a earlier post too. I remember using HelpScribble,
which is a commercial Windows product that we used in the Delphi 7
days to author application help. It now (for some time I guess)
supports CHM too, but the help source is in a proprietary format, and
magically generates a CHM file from that. You define the TOC and Index
items from within HelpScribble. What is the equivalent for LCL
application developers (eg: cross-platform application developers)?
HelpScribble is a Windows only tool, and uses the Microsoft help
compiler - but I guess it could possibly run under Linux WINE, but I
haven't tried.


>> Also, how does my product know where to find LHelp (or whatever CHM viewer
>> I want to use)?
>
> That's a *nix/Linux, not a Lazarus problem. If the OS is braindead and doesn't
> support this, what's other option is there then to do it yourself?

What are you talking about? Of course it is a Lazarus problem! How do
you tell your LCL program where to find the help viewer? How do you
tell LHelp (or any other CHM viewer) to load a specific CHM file, and
then display a specific help topic (like in the case of context
sensitive help)? Lazarus IDE does this for the RTL, FCL and LCL, but
how would you do this in LCL applications? In the IDE you have the
chmhelp package, you have a Help configuration dialog etc  Must you
design and build the same functionality into your LCL based apps, or
is there already something like that in LCL that developers can use?

eg:
In fpGUI it has a default location and file name it looks for to find
docview (the recommended help viewer). The developer can override the
helpviewer executable name and path. The fpGUI framework knows what
parameters docview supports, so knows how to call docview to display
specific help topics.  The fpgApplication instance has a HelpFile
property to specify where an applications specific INF help file is,
but docview also has a predefined location that it searches for help
files - again user configurable.  To create your own INF help, one
simply needs to edit a single plain-text file, with very easy markup,
which is much less verbose than HTML or XML. The markup language is
mnemonic, making it easy to associate them with their functions.The
TOC and Index items are define inside the single plain-text file. Then
simply compile the help source file with the supplied WIPFC help
compiler executable, and you have application help in the INF format.

Simple, easy and configurable. And this process is well documented in
the docview.inf file - supplied with DocView.

In seems LCL application help creation is just the opposite. The
Lazarus IDE is slowly but surely getting a help system working, but
none of that functionality translates to LCL based applications. LCL
application developers are still left behind - 10+ years into the
Lazarus project.

So maybe you can shed some light on this topic, seeing that you are
the creator of CHM tools in FPC & Lazarus. How do you add context
sensitive help in your LCL based application? Or do you simply not
ship help with your applications at all.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
123456