Building help files: the nitty-gritty

[Mark Morgan Lloyd]

I normally build Lazarus from svn, targeting bigide, so I'm not sure
that instructions that tell me to download prebuilt binary .chm files
are relevant to me. However, if I could ask two questions here about the
mechanics:

a) Assuming that ChmHelpPkg is loaded but lhelp is not compiled. Since
the new version of Lazarus might not yet have been run, is there an
idiot-proof way of telling lazbuild what Lazarus directory etc. is to be
used when building lhelp.lpi?

b) What is the easiest way of integrating .chm files for the RTL etc.,
to the extent that context-sensitive help works for things like
Format()? Again, if I'm building FPC from source I presume it makes more
sense to generate these locally (unless it expects lots of Latex
handling or equivalent).

Finally, if I just want to add a few lines of plain text as
context-sensitive help for a control or form, with the main
documentation having been prepared by e.g. Lyx and saved as a .pdf,
what's the way to do this?

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

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

--

[Graeme Geldenhuys]

On 10 July 2012 14:52, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
> I normally build Lazarus from svn, targeting bigide, so I'm not sure that
> instructions that tell me to download prebuilt binary .chm files are
> relevant to me.

I may be wrong, but as far as I know doing a 'make bigide' will not
build the help files, just the LCL and IDE. Well that is how it works
here with 0.9.30.x - I don't know if Lazarus Trunk has changed this.


> b) What is the easiest way of integrating .chm files for the RTL etc., to
> the extent that context-sensitive help works for things like Format()?

See, that is where CHM help lags behind, and why I mentioned INF some
time back. The way DocView integrates in the IDE (via the External
Tools menu, and not as a compiled in help-interface to the IDE), I can
get Object Pascal language help no problem. The CHM help (and the
other compiled help-interface addons to Lazarus IDE) only works well
for class / API help. The built-in Indexing and Full Text Search of
INF help makes in a no-brainer to find the correct help topic from a
keyword search.

You must remember that there is a difference between FPC's Language
Syntax help (built from LaTex and primarily targets PDF output) and
the Class / API help (built from XML files).


> Finally, if I just want to add a few lines of plain text as
> context-sensitive help for a control or form, with the main documentation

Which one is it? Control or Form? If it's a Control, then it falls
under the Class / API help, which means XML files must be edited. If
it is a Form (as in application help describing a dialog in your
application), then it's something else. For the latter case, I don't
actually know what is the recommendation for application help with LCL
based applications. For fpGUI based applications, it is an IPF
plain-text file (the help source which gets compiled into binary INF
help).

If you are referring to the help viewer, then again, that is where
LHelp lags behind. DocView allows you to annotate (add inline
comments) any INF files. Those annotations are stored in a separate
file (<helpfile>.notes), which you can move around or copy with the
INF file to a new computer if you want. LHelp has no such
functionality.



--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> On 10 July 2012 14:52, Mark Morgan Lloyd
> <***@telemetry.co.uk> wrote:
>> I normally build Lazarus from svn, targeting bigide, so I'm not sure that
>> instructions that tell me to download prebuilt binary .chm files are
>> relevant to me.
>
> I may be wrong, but as far as I know doing a 'make bigide' will not
> build the help files, just the LCL and IDE. Well that is how it works
> here with 0.9.30.x - I don't know if Lazarus Trunk has changed this.

You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
understand things correctly, the various viewers) while "all" doesn't.

>> b) What is the easiest way of integrating .chm files for the RTL etc., to
>> the extent that context-sensitive help works for things like Format()?
>
> See, that is where CHM help lags behind, and why I mentioned INF some
> time back. The way DocView integrates in the IDE (via the External
> Tools menu, and not as a compiled in help-interface to the IDE), I can
> get Object Pascal language help no problem. The CHM help (and the
> other compiled help-interface addons to Lazarus IDE) only works well
> for class / API help. The built-in Indexing and Full Text Search of
> INF help makes in a no-brainer to find the correct help topic from a
> keyword search.

Right, so stop crowing about it FFS and just say HOW TO DO IT. Then
somebody else can come along and demonstrate that a .chm is no more
difficult.

>> Finally, if I just want to add a few lines of plain text as
>> context-sensitive help for a control or form, with the main documentation
>
> Which one is it? Control or Form? If it's a Control, then it falls
> under the Class / API help, which means XML files must be edited.

So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

> If it is a Form (as in application help describing a dialog in your
> application), then it's something else. For the latter case, I don't
> actually know what is the recommendation for application help with LCL
> based applications. For fpGUI based applications, it is an IPF
> plain-text file (the help source which gets compiled into binary INF
> help).

Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
please don't act all surprised :-)

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

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

--

[Graeme Geldenhuys]

Hi,

On 10 July 2012 16:40, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
>
> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
> understand things correctly, the various viewers) while "all" doesn't.

As far as I understand it, that simply registers CHM help with the
IDE, and gives the IDE a default location of where to find LHelp. And
with newer Lazarus IDE versions, the IDE will automatically try to
compile LHelp if the executable doesn't exist. This still doesn't
compile/generate any of the CHM help files themselves.


> Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody
> else can come along and demonstrate that a .chm is no more difficult.

:-) I've explained this many times before, and then created a web
page to stop repeating myself.

http://fpgui.sourceforge.net/docview_ide_integration.shtml

I have to add that when DocView does a keyword search, it uses an
advanced search result algorithm and rating system, to try and make a
"best match". It even does spelling variations to the keyword. So I
believe this helps a lot in the result DocView gives after pressing
F1.


> So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

Correct. But remember, that when you add comments, they become part of
the documentation. You cannot disable or switch off "user added
comments" at a later date.


> Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
> please don't act all surprised :-)

I know that all too well. :)

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?

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. 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?
Also, how does my product know where to find LHelp (or whatever CHM
viewer I want to use)?


--
Regards,
- Graeme -


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

--

[Mattias Gaertner]

On Tue, 10 Jul 2012 17:39:05 +0100
Graeme Geldenhuys <***@gmail.com> wrote:

> Hi,
>
> On 10 July 2012 16:40, Mark Morgan Lloyd
> <***@telemetry.co.uk> wrote:
> >
> > You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
> > understand things correctly, the various viewers) while "all" doesn't.

make bigide does not include chmhelppkg. You have to pass
OPT=-dUseCHMHelp to do that.


> As far as I understand it, that simply registers CHM help with the
> IDE, and gives the IDE a default location of where to find LHelp. And
> with newer Lazarus IDE versions, the IDE will automatically try to
> compile LHelp if the executable doesn't exist. This still doesn't
> compile/generate any of the CHM help files themselves.

Correct.
The docs have references to the RTL+FCL docs, which are outside the
Lazarus sources and have references to programmers guide, which
requires latex. The whole doc build chain has too many dependencies and
need several minutes to build. That's not feasible for a simple make
command.


>[...]
> > So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?
>
> Correct. But remember, that when you add comments, they become part of
> the documentation. You cannot disable or switch off "user added
> comments" at a later date.

There is a feature request to hide comments when there is an fpdoc
entry.
And there is a feature request to support the new fpdoc notes.
I don't know the state of the annotation system.


> > Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
> > please don't act all surprised :-)
>
> I know that all too well. :)
>
> 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?
>
> 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. 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?
> Also, how does my product know where to find LHelp (or whatever CHM
> viewer I want to use)?

I can't help you there.
Same for what image format to use, what installer to use, what version
control system or what upgrade system.

Mattias

--

[Mark Morgan Lloyd]

Mattias Gaertner wrote:
> On Tue, 10 Jul 2012 17:39:05 +0100
> Graeme Geldenhuys <***@gmail.com> wrote:
>
>> Hi,
>>
>> On 10 July 2012 16:40, Mark Morgan Lloyd
>> <***@telemetry.co.uk> wrote:
>>> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
>>> understand things correctly, the various viewers) while "all" doesn't.
>
> make bigide does not include chmhelppkg. You have to pass
> OPT=-dUseCHMHelp to do that.

I made using bigide, and the package was in the installed list. I still
had to build lhelp manually.

>> As far as I understand it, that simply registers CHM help with the
>> IDE, and gives the IDE a default location of where to find LHelp. And
>> with newer Lazarus IDE versions, the IDE will automatically try to
>> compile LHelp if the executable doesn't exist. This still doesn't
>> compile/generate any of the CHM help files themselves.
>
> Correct.
> The docs have references to the RTL+FCL docs, which are outside the
> Lazarus sources and have references to programmers guide, which
> requires latex. The whole doc build chain has too many dependencies and
> need several minutes to build. That's not feasible for a simple make
> command.

So what's best to do here: download them as binaries and install where/how?

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

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

--

[Mattias Gaertner]

On Tue, 10 Jul 2012 19:45:46 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> wrote:

>[...]
> > make bigide does not include chmhelppkg. You have to pass
> > OPT=-dUseCHMHelp to do that.
>
> I made using bigide, and the package was in the installed list.

See ide/lazarus.pp
Maybe you are confusing "installed" lists?


> I still had to build lhelp manually.

Check if you have local modifications. In trunk the makefile target
bigide includes lhelp.


> >> As far as I understand it, that simply registers CHM help with the
> >> IDE, and gives the IDE a default location of where to find LHelp. And
> >> with newer Lazarus IDE versions, the IDE will automatically try to
> >> compile LHelp if the executable doesn't exist. This still doesn't
> >> compile/generate any of the CHM help files themselves.
> >
> > Correct.
> > The docs have references to the RTL+FCL docs, which are outside the
> > Lazarus sources and have references to programmers guide, which
> > requires latex. The whole doc build chain has too many dependencies and
> > need several minutes to build. That's not feasible for a simple make
> > command.
>
> So what's best to do here: download them as binaries and install where/how?

Download the chm files and put them into "yourlazarus/docs/chm/".

Mattias


--

[Mark Morgan Lloyd]

Mattias Gaertner wrote:
> On Tue, 10 Jul 2012 19:45:46 +0000
> Mark Morgan Lloyd <***@telemetry.co.uk> wrote:
>
>> [...]
>>> make bigide does not include chmhelppkg. You have to pass
>>> OPT=-dUseCHMHelp to do that.
>> I made using bigide, and the package was in the installed list.
>
> See ide/lazarus.pp
> Maybe you are confusing "installed" lists?

I mean in the sense of the "If you are using Lazarus from Subversion" in
the
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE
page which is cited by the trunk IDE's Help -> Online Help page: the
instructions are accurate (it's only page and link organisation that
I've been querying).

>> I still had to build lhelp manually.
>
> Check if you have local modifications. In trunk the makefile target
> bigide includes lhelp.

Same applies.

>>> The docs have references to the RTL+FCL docs, which are outside the
>>> Lazarus sources and have references to programmers guide, which
>>> requires latex. The whole doc build chain has too many dependencies and
>>> need several minutes to build. That's not feasible for a simple make
>>> command.
>> So what's best to do here: download them as binaries and install where/how?
>
> Download the chm files and put them into "yourlazarus/docs/chm/".

OK, so I get
ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
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.

Congratulations and thanks to everybody who's worked hard to get the IDE
to this point (and who's put up with my occasionally bull-headed questions).

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

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

--

[Mattias Gaertner]

On Wed, 11 Jul 2012 08:47:20 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> wrote:

> Mattias Gaertner wrote:
> > On Tue, 10 Jul 2012 19:45:46 +0000
> > Mark Morgan Lloyd <***@telemetry.co.uk> wrote:
> >
> >> [...]
> >>> make bigide does not include chmhelppkg. You have to pass
> >>> OPT=-dUseCHMHelp to do that.
> >> I made using bigide, and the package was in the installed list.
> >
> > See ide/lazarus.pp
> > Maybe you are confusing "installed" lists?
>
> I mean in the sense of the "If you are using Lazarus from Subversion" in
> the
> http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE
> page which is cited by the trunk IDE's Help -> Online Help page: the
> instructions are accurate (it's only page and link organisation that
> I've been querying).

It is true that the chmhelppkg was included with some binaries and
therefore many users had it preinstalled. But afaik it was never
enabled by default in target bigide.

Try this:
make clean bigide
./lazarus --pcp=testconfig


> >> I still had to build lhelp manually.
> >
> > Check if you have local modifications. In trunk the makefile target
> > bigide includes lhelp.
>
> Same applies.

If you don't have a components/chmhelp/lhelp/lhelp after doing a "make
bigide", then please report the bug.


> >>> The docs have references to the RTL+FCL docs, which are outside the
> >>> Lazarus sources and have references to programmers guide, which
> >>> requires latex. The whole doc build chain has too many dependencies and
> >>> need several minutes to build. That's not feasible for a simple make
> >>> command.
> >> So what's best to do here: download them as binaries and install where/how?
> >
> > Download the chm files and put them into "yourlazarus/docs/chm/".
>
> OK, so I get
> ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
> 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.

Historically the default search path for chm files was docs/html. But
this is a source directory. Mixing svn files and downloaded files is
confusing. It is cleaner to put all downloaded files into a directory if
its own (docs/chm).
The docs/html directory is still in the search path for
compatibility.


> Congratulations and thanks to everybody who's worked hard to get the IDE
> to this point (and who's put up with my occasionally bull-headed questions).

:)

Mattias

--

[Mark Morgan Lloyd]

Mattias Gaertner wrote:

>>>> I still had to build lhelp manually.
>>> Check if you have local modifications. In trunk the makefile target
>>> bigide includes lhelp.
>> Same applies.
>
> If you don't have a components/chmhelp/lhelp/lhelp after doing a "make
> bigide", then please report the bug.

I'll revisit that on a clean system as soon as I'm able.

>>>>> The docs have references to the RTL+FCL docs, which are outside the
>>>>> Lazarus sources and have references to programmers guide, which
>>>>> requires latex. The whole doc build chain has too many dependencies and
>>>>> need several minutes to build. That's not feasible for a simple make
>>>>> command.
>>>> So what's best to do here: download them as binaries and install where/how?
>>> Download the chm files and put them into "yourlazarus/docs/chm/".
>> OK, so I get
>> ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
>> 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?

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

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

--

[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]

--

[Mattias Gaertner]

Mark Morgan Lloyd <***@telemetry.co.uk> 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

[Reinier Olislagers]

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?

--

[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]

--

[Mattias Gaertner]

On Fri, 13 Jul 2012 12:32:40 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> 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


--

[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]

--

[Mattias Gaertner]

On Fri, 13 Jul 2012 13:13:07 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> 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

--

[Mark Morgan Lloyd]

Mattias Gaertner wrote:
> On Fri, 13 Jul 2012 13:13:07 +0000
> Mark Morgan Lloyd <***@telemetry.co.uk> 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]

--

[Mark Morgan Lloyd]

Mark Morgan Lloyd wrote:
> Mattias Gaertner wrote:
>> On Fri, 13 Jul 2012 13:13:07 +0000
>> Mark Morgan Lloyd <***@telemetry.co.uk> 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]

--

[Mattias Gaertner]

On Mon, 16 Jul 2012 13:19:44 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> wrote:

> Mark Morgan Lloyd wrote:
> > Mattias Gaertner wrote:
> >> On Fri, 13 Jul 2012 13:13:07 +0000
> >> Mark Morgan Lloyd <***@telemetry.co.uk> 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


--

[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]

--

[Mattias Gaertner]

On Mon, 16 Jul 2012 14:41:12 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> 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


--

[Mark Morgan Lloyd]

Mattias Gaertner wrote:
> On Mon, 16 Jul 2012 14:41:12 +0000
> Mark Morgan Lloyd <***@telemetry.co.uk> 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]

--

[Mattias Gaertner]

On Mon, 16 Jul 2012 15:16:33 +0000
Mark Morgan Lloyd <***@telemetry.co.uk> wrote:

> Mattias Gaertner wrote:
> > On Mon, 16 Jul 2012 14:41:12 +0000
> > Mark Morgan Lloyd <***@telemetry.co.uk> 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

--

[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]

--

[waldo kitty]

On 7/16/2012 13:20, Mark Morgan Lloyd wrote:
> 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".
>

i pointed this out previously several months back when we were having the big
help installation discussion... i couldn't get it to work and then suddenly it
started... about that time someone wrote in here to fill in that field with the
path... i checked mine and is was empty so i responded that i didn't have
anything in mine and it was now working... i had thought that you might have
picked up on that post of mine because your help install started working per
your report...

now, the only thing left for me/us is to find the rest of the chm files...
there's more than three of them ;)

--

[Marco van de Voort]

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.

--

[Graeme Geldenhuys]

On 10 July 2012 18:11, Mattias Gaertner <nc-***@netcologne.de> wrote:
> And there is a feature request to support the new fpdoc notes.
> I don't know the state of the annotation system.

I personally thing that is tackling the problem from the wrong end. I
definitely don't want other peoples annotations in my help documents.
Such functionality needs to be added at runtime by the docs viewer.
Just my 2c.


> I can't help you there.
> Same for what image format to use, what installer to use, what version
> control system or what upgrade system.

OK, then forget about me. :) What help do you use in your applications
- what help format and help editor do you use?



--
Regards,
- Graeme -


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

--

[Mattias Gaertner]

On Tue, 10 Jul 2012 21:26:00 +0100
Graeme Geldenhuys <***@gmail.com> wrote:

> On 10 July 2012 18:11, Mattias Gaertner <nc-***@netcologne.de> wrote:
> > And there is a feature request to support the new fpdoc notes.
> > I don't know the state of the annotation system.
>
> I personally thing that is tackling the problem from the wrong end. I
> definitely don't want other peoples annotations in my help documents.
> Such functionality needs to be added at runtime by the docs viewer.
> Just my 2c.

I agree with the locality. The IDE is not a science project or critical
apparatus. Annotations of the LCL docs and probably all packages in the
Lazarus sources should be local.
I don't understand what you mean with "that is tackling the problem
from the wrong end".


> > I can't help you there.
> > Same for what image format to use, what installer to use, what version
> > control system or what upgrade system.
>
> OK, then forget about me. :) What help do you use in your applications
> - what help format and help editor do you use?

So far my other applications never needed an extensive offline help
and therefore I do not dare to give an advice. I leave this to others.


Mattias

--

[Graeme Geldenhuys]

Hi,

On 10 July 2012 23:45, Mattias Gaertner <nc-***@netcologne.de> wrote:
>>
>> I personally thing that is tackling the problem from the wrong end. I
>> definitely don't want other peoples annotations in my help documents.
>> Such functionality needs to be added at runtime by the docs viewer.
>> Just my 2c.
>
> I agree with the locality. The IDE is not a science project or critical
> apparatus. Annotations of the LCL docs and probably all packages in the
> Lazarus sources should be local.

Yes, annotations are a personal thing. I might annotate a help topic I
struggle with, where somebody else could well have thought it pretty
obvious, and needed no further explanation.


> I don't understand what you mean with "that is tackling the problem
> from the wrong end".

I meant, in is not really the fpdoc XML files that need annotation
support, it is the Help Viewers than need the support. The Help
Viewers must be able to add annotations at runtime, store them
locally, and separate from the original help files.

The other problems I can see that will happen with the Lazarus IDE's
FPDoc Editor supporting annotations, is that if those annotations are
stored in the same fpdoc XML files as the LCL, then somebody might
submit those changes with actual LCL documentation fixes. Then the
burden will fall on the Lazarus core team to make sure they don't
accidentally commit such a contribution (somebody's personal
annotations mixed with legit documentation bug fixes) to the
repository.


> So far my other applications never needed an extensive offline help

Lucky you! :)


--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> Hi,
>
> On 10 July 2012 16:40, Mark Morgan Lloyd
> <***@telemetry.co.uk> wrote:
>> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
>> understand things correctly, the various viewers) while "all" doesn't.
>
> As far as I understand it, that simply registers CHM help with the
> IDE, and gives the IDE a default location of where to find LHelp. And
> with newer Lazarus IDE versions, the IDE will automatically try to
> compile LHelp if the executable doesn't exist. This still doesn't
> compile/generate any of the CHM help files themselves.

Agreed, and the various wiki pages etc. do appear to stress that the
final conversion of files to .chm is still work-in-progress (with
caveats on alignment etc.).

>> Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody
>> else can come along and demonstrate that a .chm is no more difficult.
>
> :-) I've explained this many times before, and then created a web
> page to stop repeating myself.
>
> http://fpgui.sourceforge.net/docview_ide_integration.shtml

Relevance noted, will revisit. In that pretty pictcha of yours, should
FPCHELP be decorated with a $ to indicate it's a shell variable?

> 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?

[Nod] I suspect that we're not the only people asking for guidance.

> 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.

Good point. But at the same time most unix-style OSes can't read .inf,
so one would need to bundle docview or whatever. Which I think suggests
that an important point is having a flexible and foolproof document
generation process, which can produce .inf, .chm or whatever...
basically, any format where a viewer can jump straight to the relevant
section (which specifically excludes .pdf, for this role).

> 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?
> Also, how does my product know where to find LHelp (or whatever CHM
> viewer I want to use)?

[Nod] I suspect that we're not the only people asking for guidance.

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

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

--

[Žilvinas Ledas]

Hello,

On 2012-07-10 20:40, Mark Morgan Lloyd wrote:
>> 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?
>> Also, how does my product know where to find LHelp (or whatever CHM
>> viewer I want to use)?
>
> [Nod] I suspect that we're not the only people asking for guidance.
>

fpc has chm "compiler" classes to make CHM files.
TChmProject is in chmfilewriter unit and TChmWriter is in chmwriter unit
(both in packages\chm\src\).
And there even is a GUI app to make chm files somewhere in Lazarus or
fpc examples :) I don't remember where exactly, because I did make my
own chm help maker application (it took about a day using existing chm
writing functionality) before I discovered that existing one. BTW I
posted my chm maker (app with sources) about two years ago on this (or
fpc) list ;)

Regarding LHelp - I myself package LHelp executable with the main app
and help files so I know that LHelp is besides main app.
You can register your help format system-wide and install LHelp in a
different place from your app - as with any other file viewer your app
may need :)

Regards,
Žilvinas

--

[Graeme Geldenhuys]

Hi Mark,

On 10 July 2012 18:40, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
> Relevance noted, will revisit. In that pretty pictcha of yours, should
> FPCHELP be decorated with a $ to indicate it's a shell variable?

No, DocView will handle that automatically. DocView can handle many
types of parameters and all are tested when DocView starts up. eg: It
queries the environment variables defined on your system for a match.
Yes/No. Query if it is a directory? Yes/No. Query if it is a one or
more help files without the .inf extension (in which case it then uses
a predefined help directory/directories specified by the BOOKSHELF
environment variable)? Yes/No. Query if it is a full path to a .inf
(with the .inf extension). Yes/No. If still nothing, simply start up
with no help file loaded.

DocView comes with its own extensive docview.inf application help
file, which explains all this and much more.


> [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'm still fuzzy on how LCL based applications know which CHM help
viewer to use though. This is especially important under Linux & MacOS
because the free CHM help viewers available on those platforms have
vastly different features and functionality. Some don't support
searching, some don't have Index support, some don't support CSS etc
etc. And I'm 100% sure they have different parameter options, so the
LCL app needs to know what it can and can't pass the the CHM help
viewer.


> Good point. But at the same time most unix-style OSes can't read .inf, so
> one would need to bundle docview or whatever.

Correct, and I don't have a problem with that. What I was getting at
is that different CHM help viewers support different features, and
there command line parameters will differ too. So how does LCL based
apps know how to tell each of those CHM help viewers that they must
display Help Topic Index 1234, or Help Topic String 'MyDialog1', from
the CHM help file of application X.

These are the most basic things that need to be address for an
application help to have working application help. Amazing no LCL
developer has come across this yet. Maybe the little bit I know of LCL
is just too little. ;-)


--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

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).

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

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

--

[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]

--

[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]

--

[Marco van de Voort]

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?

--

[Graeme Geldenhuys]

Hi Marco,

Nice chatting to an old friend again. ;-)

On 16 July 2012 20:14, Marco van de Voort <***@stack.nl> 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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> Hi Marco,
>
> Nice chatting to an old friend again. ;-)

So lets all try to keep this friendly and constructive, without
launching into a "my IDE's better than yours" exercise :-)

I'm writing this from the position of an outsider, so am happy to be
corrected by Marco, Andrew et al. However if I there are areas that I
haven't been able to "get my head round" after several days scouring the
Wiki and Google, it's going to be far worse for a tyro. If somebody
thinks I've got things wrong, I suggest that exploring /why/ I've got it
wrong and what can be improved is in order.

> On 16 July 2012 20:14, Marco van de Voort <***@stack.nl> 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.

The current situation- and this is with Lazarus trunk, not stable-
appears to be that HTML keyword-based application help works well
provided that you're prepared to tolerate browser startup time. However,
even worse than the startup delay is the fact that in the general case
neither the IDE nor general apps can tell an existing browser to change
the page it's displaying: I believe there's a backdoor for this sort of
thing in IE on Windows but on unix you can end up with multiple browser
instances that don't go away when the program's shut down.

I very much look forward to the CHM reader being made available for apps
rather than just for the IDE, I'm starting to code what could be my
magnum opus and I'd like the opportunity to exercise it.

> 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 end user is entitled to have all files of a particular type (chm in
the current case) look and handled the same, but I'm not sure it should
be the developer's choice which program is opened for a given file type,
unless he is prepared to take full responsibility for things going wrong
in other apps.

As a general point, current desktops (including KDE and Gnome) have a
standardised set of programs for opening files by extension (xdg-open
etc.), and to be quite honest I think it's not to the credit of anybody
who tries to open a browser or viewer without reference to these.

> 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?
..
> 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.

I added a section to that page on adding a TOC yesterday and how to find
what options are supported by chmcmd. I didn't want to be too verbose
since it's hardly my area of expertise, but I felt it needed to be
documented somewhere.

> 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.

The canonical tool appears to still be the Microsoft Help Workshop (or
some similar name), and almost everything else appears to be based on
this in some way: chmcmd is pretty much unique, to the extent that I've
seen a Debian bug report asking why it's not packaged separately because
of it's general usefulness. The Wiki page above mentions a
product/project to convert Tex to chm which I've not investigated, I'm
now able to convert Lyx source or PDF to HTML hence to a .chm including
semi-automatic TOC (single-level) but it doubtless needs more work and
I'm not sure what the situation is regarding integrating CHM in an app.

Got to go, sorry if anything above is incomplete or unchecked.

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

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

--

[Reinier Olislagers]

On 17-7-2012 10:15, Mark Morgan Lloyd wrote:
> Graeme Geldenhuys wrote:
>> Hi Marco,
>>
>> Nice chatting to an old friend again. ;-)
>
> So lets all try to keep this friendly and constructive, without
> launching into a "my IDE's better than yours" exercise :-)
Totally agreed.

>> On 16 July 2012 20:14, Marco van de Voort <***@stack.nl> 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.
<snip>
> The current situation- and this is with Lazarus trunk, not stable-
> appears to be that HTML keyword-based application help works well
> provided <snip why HTML help might not be such a good idea>
> I very much look forward to the CHM reader being made available for apps
> rather than just for the IDE, I'm starting to code what could be my
> magnum opus and I'd like the opportunity to exercise it.
>From another outsider's view, wouldn't this be a solution:
1. document the IPC mechanism used for communication between IDE and
lhelp so application developers can use it
2. compile and distribute lhelp with your application... should be
possible already, shouldn't it?
3. in application: start lhelp and pass messages using 1.

- I don't know intercepting e.g. an F1 keypress from being sent to
system wide help would take special action... perhaps it doesn't.
- Perhaps there is some Linux standard or GNOME or KDE standard that
indicates how to do *keyword sensitive help* with chm files.
In that case the approach above could be a fallback mechanism... or this
approach could be a fallback mechanism depending on programmer's preference.


>> 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.
I'd lean to this conclusion as well.

> The end user is entitled to have all files of a particular type (chm in
> the current case) look and handled the same, but I'm not sure it should
> be the developer's choice which program is opened for a given file type,
> unless he is prepared to take full responsibility for things going wrong
> in other apps.
I don't think changing the system wide association between the .chm file
type and the executable to open that is what Mark or I would have in
mind. In any case, I agree that is bad.
However, given my solution above, this step would not be necessary at all.

> As a general point, current desktops (including KDE and Gnome) have a
> standardised set of programs for opening files by extension (xdg-open
> etc.), and to be quite honest I think it's not to the credit of anybody
> who tries to open a browser or viewer without reference to these.
In general, agreed, but:
If that standard allows keyword lookup etc.. I'm all for it. Also, the
number of standards must be manageable ;)
Finally, quite probably not *all* desktops support this (saw your
"current" up there)... so a fallback mechanism would be needed if others
are supported, too.
It may just be too much effort to support all of it... unless this
effort can be moved into some kind of cross-platform application help
framework to be included in say... Lazarus ;)

> The canonical tool appears to still be the Microsoft Help Workshop (or
> some similar name),
Microsoft HTML Help Workshop, if I've got the right one installed here. Yes.

--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:

>> The current situation- and this is with Lazarus trunk, not stable-
>> appears to be that HTML keyword-based application help works well
>> provided <snip why HTML help might not be such a good idea>
>> I very much look forward to the CHM reader being made available for apps
>> rather than just for the IDE, I'm starting to code what could be my
>> magnum opus and I'd like the opportunity to exercise it.
>
>From another outsider's view, wouldn't this be a solution:
> 1. document the IPC mechanism used for communication between IDE and
> lhelp so application developers can use it
> 2. compile and distribute lhelp with your application... should be
> possible already, shouldn't it?
> 3. in application: start lhelp and pass messages using 1.

Agreed, or tentatively "componentize" the relevant classes
(TLclChmHelpDatabase and TChmHelpViewer?).

>> As a general point, current desktops (including KDE and Gnome) have a
>> standardised set of programs for opening files by extension (xdg-open
>> etc.), and to be quite honest I think it's not to the credit of anybody
>> who tries to open a browser or viewer without reference to these.
> In general, agreed, but:
> If that standard allows keyword lookup etc.. I'm all for it. Also, the
> number of standards must be manageable ;)

No, the tools are strictly for handling file and mime types:

-----8<-----
xdg-desktop-icon (1) - command line tool for (un)installing icons to the
desktop
xdg-desktop-menu (1) - command line tool for (un)installing desktop menu
items
xdg-email (1) - command line tool for sending mail using the
users preferred e-mail composer
xdg-icon-resource (1) - command line tool for (un)installing icon resources
xdg-mime (1) - command line tool for querying information about
file type handling and adding descriptions for new file types
xdg-open (1) - opens a file or URL in the users preferred
application
xdg-screensaver (1) - command line tool for controlling the screensaver
xdg-settings (1) - get various settings from the desktop environment
----->8-----

> Finally, quite probably not *all* desktops support this (saw your
> "current" up there)... so a fallback mechanism would be needed if others
> are supported, too.

I agree about the fallback, but the xdg stuff has been in most if not
all Linux distreaux for around five years (doesn't appear to be in
Solaris 10 which is 5+ years old now, don't have a newer version to
check). The important point is that the xdg command lines are
standardised, the implementations are platform-specific.

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

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

--

[Reinier Olislagers]

On 17-7-2012 10:55, Mark Morgan Lloyd wrote:
> Reinier Olislagers wrote:
>>> As a general point, current desktops (including KDE and Gnome) have a
>>> standardised set of programs for opening files by extension (xdg-open
>>> etc.), and to be quite honest I think it's not to the credit of anybody
>>> who tries to open a browser or viewer without reference to these.
>> In general, agreed, but:
>> If that standard allows keyword lookup etc.. I'm all for it. Also, the
>> number of standards must be manageable ;)
>
> No, the tools are strictly for handling file and mime types:
>
> -----8<-----
> xdg-desktop-icon (1) - command line tool for (un)installing icons to the
> desktop
> xdg-desktop-menu (1) - command line tool for (un)installing desktop menu
> items
> xdg-email (1) - command line tool for sending mail using the
> users preferred e-mail composer
> xdg-icon-resource (1) - command line tool for (un)installing icon resources
> xdg-mime (1) - command line tool for querying information about
> file type handling and adding descriptions for new file types
> xdg-open (1) - opens a file or URL in the users preferred
> application
> xdg-screensaver (1) - command line tool for controlling the screensaver
> xdg-settings (1) - get various settings from the desktop environment
> ----->8-----

Ok, this would mean the xdg-open tools don't allow context-sensitive
help... and end of discussion on that front as far as LCL application
help is concerned, I suppose.
Unless
a. I'm misinterpreting things
b. there are other APIs/standards that address this

>> Finally, quite probably not *all* desktops support this (saw your
>> "current" up there)... so a fallback mechanism would be needed if others
>> are supported, too.
>
> I agree about the fallback, but the xdg stuff has been in most if not
> all Linux distreaux for around five years (doesn't appear to be in
> Solaris 10 which is 5+ years old now, don't have a newer version to
> check). The important point is that the xdg command lines are
> standardised, the implementations are platform-specific.
Given the above this wouldn't really matter anymore, would it?



--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:

> Ok, this would mean the xdg-open tools don't allow context-sensitive
> help... and end of discussion on that front as far as LCL application
> help is concerned, I suppose.
> Unless
> a. I'm misinterpreting things
> b. there are other APIs/standards that address this
>
>>> Finally, quite probably not *all* desktops support this (saw your
>>> "current" up there)... so a fallback mechanism would be needed if others
>>> are supported, too.
>> I agree about the fallback, but the xdg stuff has been in most if not
>> all Linux distreaux for around five years (doesn't appear to be in
>> Solaris 10 which is 5+ years old now, don't have a newer version to
>> check). The important point is that the xdg command lines are
>> standardised, the implementations are platform-specific.
> Given the above this wouldn't really matter anymore, would it?

The only relevance is that this- in my opinion at least- should be the
primary way that a program tries to locate subsidiary file viewers etc.
It's the unix answer to ShellOpenEx() (or whataver the Windows API's
function is).

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

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

--

[Reinier Olislagers]

On 17-7-2012 12:06, Mark Morgan Lloyd wrote:
> Reinier Olislagers wrote:
>
>> Ok, this would mean the xdg-open tools don't allow context-sensitive
>> help... and end of discussion on that front as far as LCL application
>> help is concerned, I suppose.
<snip>
> The only relevance is that this- in my opinion at least- should be the
> primary way that a program tries to locate subsidiary file viewers etc.
> It's the unix answer to ShellOpenEx() (or whataver the Windows API's
> function is).

Ah, ok.

AFAIU, LCLIntf.OpenDocument('thedocument.chm'); would open the CHM file
with the system viewer (if present) in a cross-platform way.
On Windows (sysenvapis_win.inc) it uses ShellExecute/ShellExecuteW.

On Unix, Linux (sysenvapis_unix.inc), it looks for xdg-open, kfmclient,
gnome-open and tries those.

On OSX (sysenvapis_mac.inc), it runs
RunCmdFromPath('open',ResultingPath);
too lazy to look up what that does.

There seems to be an implementation for Android customdrawn as well.

--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:
> On 17-7-2012 12:06, Mark Morgan Lloyd wrote:
>> Reinier Olislagers wrote:
>>
>>> Ok, this would mean the xdg-open tools don't allow context-sensitive
>>> help... and end of discussion on that front as far as LCL application
>>> help is concerned, I suppose.
> <snip>
>> The only relevance is that this- in my opinion at least- should be the
>> primary way that a program tries to locate subsidiary file viewers etc.
>> It's the unix answer to ShellOpenEx() (or whataver the Windows API's
>> function is).
>
> Ah, ok.
>
> AFAIU, LCLIntf.OpenDocument('thedocument.chm'); would open the CHM file
> with the system viewer (if present) in a cross-platform way.
> On Windows (sysenvapis_win.inc) it uses ShellExecute/ShellExecuteW.
>
> On Unix, Linux (sysenvapis_unix.inc), it looks for xdg-open, kfmclient,
> gnome-open and tries those.
>
> On OSX (sysenvapis_mac.inc), it runs
> RunCmdFromPath('open',ResultingPath);
> too lazy to look up what that does.
>
> There seems to be an implementation for Android customdrawn as well.

Thanks for that- I'd missed that the xdg stuff had (finally :-) been added.

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

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

--

[Reinier Olislagers]

On 17-7-2012 10:36, Reinier Olislagers wrote:
> On 17-7-2012 10:15, Mark Morgan Lloyd wrote:
>>From another outsider's view, wouldn't this be a solution:
> 1. document the IPC mechanism used for communication between IDE and
> lhelp so application developers can use it

Added some notes on
http://wiki.freepascal.org/IDE_Development#Working_8
Although that page says: "This page contains notes for lazarus core
developers about ongoing development." it seems like it can serve as
documentation of realized development as well.

See lazarus\components\chmhelp\democontrol for a project that
demonstrates IPC communication.

The source code
(lazarus\components\chmhelp\packages\help\lhelpcontrol.pas) is quite
legible... even for me ;)
While I've submitted some more comments in issue 22467, I think it can
serve very well as documentation for the protocol.
AFAIU it could be used as-is in applications, perhaps aided by taking
inspiration from the code in
lazarus\components\chmhelp\packages\idehelp\lazchmhelp.pas

Creating a component that includes lhelpcontrol added with some
functionality from chmhelppkg should be quite doable.

I can't seem to find any license info for these packages though. Is it
modified LGPL?

> 2. compile and distribute lhelp with your application... should be
> possible already, shouldn't it?
> 3. in application: start lhelp and pass messages using 1.


--

[Mattias Gaertner]

Reinier Olislagers <***@gmail.com> hat am 19. Juli 2012 um 10:06
geschrieben:

>
> I can't seem to find any license info for these packages though. Is it
> modified LGPL?


Modified LGPL 2, same as the LCL.
I added the note in the package.



>
> > 2. compile and distribute lhelp with your application... should be
> > possible already, shouldn't it?


yes


> > 3. in application: start lhelp and pass messages using 1.

Mattias

[Mark Morgan Lloyd]

Reinier Olislagers wrote:
> On 17-7-2012 10:36, Reinier Olislagers wrote:
>> On 17-7-2012 10:15, Mark Morgan Lloyd wrote:
>> >From another outsider's view, wouldn't this be a solution:
>> 1. document the IPC mechanism used for communication between IDE and
>> lhelp so application developers can use it
>
> Added some notes on
> http://wiki.freepascal.org/IDE_Development#Working_8
> Although that page says: "This page contains notes for lazarus core
> developers about ongoing development." it seems like it can serve as
> documentation of realized development as well.
>
> See lazarus\components\chmhelp\democontrol for a project that
> demonstrates IPC communication.
>
> The source code
> (lazarus\components\chmhelp\packages\help\lhelpcontrol.pas) is quite
> legible... even for me ;)
> While I've submitted some more comments in issue 22467, I think it can
> serve very well as documentation for the protocol.
> AFAIU it could be used as-is in applications, perhaps aided by taking
> inspiration from the code in
> lazarus\components\chmhelp\packages\idehelp\lazchmhelp.pas
>
> Creating a component that includes lhelpcontrol added with some
> functionality from chmhelppkg should be quite doable.

I was working through stuff last night and could see where it was based
on SimpleIPC, with the socket name passed as a parameter to the lhelp
program. So provided that an app can grab F1 it doesn't look too bad.

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

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

--

[Marco van de Voort]

On Tue, Jul 17, 2012 at 08:15:29AM +0000, Mark Morgan Lloyd wrote:

> I'm writing this from the position of an outsider, so am happy to be
> corrected by Marco, Andrew et al. However if I there are areas that I
> haven't been able to "get my head round" after several days scouring the
> Wiki and Google, it's going to be far worse for a tyro. If somebody
> thinks I've got things wrong, I suggest that exploring /why/ I've got it
> wrong and what can be improved is in order.

This has all been rehashed umpteen times. The bottom line: It's a work in
progress, people seem to start competing projects instead of chipping in.

Recent progress is slow or has stalled.

> The current situation- and this is with Lazarus trunk, not stable-
> appears to be that HTML keyword-based application help works well
> provided that you're prepared to tolerate browser startup time.

Decompress a zip with the html help on an ARM with SD or something else
slow. Then the browser startup isn't the worst bit anymore. (I've seen the
FPC installer do over 30 minutes of decompression on dos, and that was when
the docs were far smaller. The rest of FPC installed in 2 minutes)

> However, even worse than the startup delay is the fact that in the general
> case neither the IDE nor general apps can tell an existing browser to
> change the page it's displaying: I believe there's a backdoor for this
> sort of thing in IE on Windows but on unix you can end up with multiple
> browser instances that don't go away when the program's shut down.

It's not really IE. It is simply true browser instrumentation vs cheap and
easy fire and forget browser launching.

> I very much look forward to the CHM reader being made available for apps
> rather than just for the IDE, I'm starting to code what could be my
> magnum opus and I'd like the opportunity to exercise it.

I don't know if Andrew is still actively working on lview. I never worked on
the visual part. That's because I originally came to work on CHM from the
textmode IDE side, not Lazarus.

> The end user is entitled to have all files of a particular type (chm in
> the current case) look and handled the same, but I'm not sure it should
> be the developer's choice which program is opened for a given file type,
> unless he is prepared to take full responsibility for things going wrong
> in other apps.

This is too vague and generic. "look and handled the same" from where? From
the explorer, I agree, that is the users choice.

But the help is lauched from the app, not the explorer, and thus the
app developer's responsibility.

We all would like it otherwise, but on *nix it has been that way for a
while, and it doesn't look like it is going to change soon.

> As a general point, current desktops (including KDE and Gnome) have a
> standardised set of programs for opening files by extension (xdg-open
> etc.), and to be quite honest I think it's not to the credit of anybody
> who tries to open a browser or viewer without reference to these.

xdg-open is opening a document (and even then only the gnome-KDE lowest
common denomitor only. I'm pretty sure KDE apps don't call their help or
instrument eachother via xdg-open)

I'm instrumenting an application, for which there is no standarized set. KDE
and Gnome afaik both have separate instrumentation (ORB like) systems, which
often change on major releases.

> The canonical tool appears to still be the Microsoft Help Workshop (or
> some similar name), and almost everything else appears to be based on
> this in some way

Be careful. That Workshop consists out of two tools, both equally horrid.
One is a simple editor for help projects, and one is the compiler.

You can do without an editor (just generating a hhp project from some other
source), and chmcmd is rougly equivalent with to the compiler.

Most "CHM" authoring tools call the MS compiler in the end. With some
crafting you can simply use commercial authoring tools and then export it to
a hhp project (or rescue that from %TEMP% while compiling).

Or just create html, and use the DOM tool

chmcmd is rough, but I have gotten reports of people using it ON WINDOWS to
workaround bugs with the MS tool (which seems to have problems with big
files) :_)

Being able to enable the multi-core compression which is in CHM, but not
stable would be another really big boon.

Anyway, the chmcmd compiler should work for most basic projects. A simple
editor that allows you to add html to a project, scan it for labels and/or
outlines should be easy, as long as you control where the html is coming
from.

: chmcmd is pretty much unique, to the extent that I've
> seen a Debian bug report asking why it's not packaged separately because
> of it's general usefulness.

Well I expanded chmcmd a bit in the last few releases to become a .hhp
compiler (before it was only rudimentary access to the chm writer class, I
basically added the same, but to/from the .hhp ini like format, implemented
recursive scanning for additional files).

But the real virtue is the CHM writer in general. chmcmd only instruments
it. Credit for that mostly goes to Andrew Haines. Sergei did some good work
debugging the HTML modules of fcl-xml too btw.

> The Wiki page above mentions a
> product/project to convert Tex to chm which I've not investigated, I'm
> now able to convert Lyx source or PDF to HTML hence to a .chm including
> semi-automatic TOC (single-level) but it doubtless needs more work and
> I'm not sure what the situation is regarding integrating CHM in an app.

The latex chms (ref,user,prog) are generated much the same way. See the
latexcompile or something program in the fpcdocs repo. (the documentation
sources). The cherry on the cake is the folding of the keyword index into
ref.chm.

Be warned though. It is ad-hoc code, probably not 2.7.1 compatible (due ot
unicode changes), and works around fcl-xml bugs probably resolved now.

--

[Michael Schnell]

On 07/17/2012 12:15 AM, Graeme Geldenhuys wrote:
> 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 hel

I remember from our discussion some months ago that there was an
announcement that hopefully a tool will be crated, that somehow unifies
the help information generated by updating the Wiki and by using (e.g.)
fpdoc. Do you know the state of that project ? I suppose before deciding
about any other improvement for the help system - that of course needs
to be based on some common central help source repository - a decision
on this (if doable, seemingly very advantageous) project should be done.

-Michael

--

[Graeme Geldenhuys]

Hi,

On 18 July 2012 10:48, Michael Schnell <***@lumino.de> wrote:
> Do you know the state of that project ? I suppose before deciding about any

I know Mattias started work on a tool that extracts the help content
directly from the wiki pages. I have not followed that project so I
have no clue as to the status of it, but I would guess it is somewhere
inside the Lazarus project if you want to take a look.


> other improvement for the help system - that of course needs to be based on

Please note, that the discussion some months back was about help for
the RTL, FCL, LCL, FPC Language Reference etc to be used by the
Lazarus IDE - to help developers with programming and API information.
What I was talking about in this message thread is "application help".
Integrating CHM help into your own applications, giving your end-users
context sensitive help for your product. So far I have heard that
integrating CHM help into your own LCL-based applications are not
possible, and that nobody here actually seems to ship help files with
their own applications. I guess I'm the only exception to that rule.

The following URL is exactly what I am talking about, but as I said,
it only describes HTML help (lots of HTML files located in a folder),
and has limited help abilities.

http://wiki.freepascal.org/Add_Help_to_Your_Application


I had a look at the chmhelp package include with Lazarus, to see if I
could follow the same guideline as mentioned in the above wiki page.
But the chmhelp package depends on the IDE (CodeTools, IDEInterface
etc), so as far as I can see, it can't be used in general LCL-based
applications.


--
Regards,
- Graeme -


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

--

[Michael Schnell]

On 07/18/2012 12:49 PM, Graeme Geldenhuys wrote:
> What I was talking about in this message thread is "application help".

I see, but as the IDE _is_ an application, I feel that - if Lazarus is
supposed to provide means for application programmers to integrate a
help system in their apps and fill it with appropriate information - it
would be a good idea to do both with the same tools, leveraging both the
amount of work that needs to be done by those creating the system(s)
that allow for inputting and displaying the help content, and the
learning curve for those that as well use and help improving Lazarus (a
big plus for an open source project as Lazarus is).

-Michael

--

[Reinier Olislagers]

On 18-7-2012 13:04, Michael Schnell wrote:
> On 07/18/2012 12:49 PM, Graeme Geldenhuys wrote:
>> What I was talking about in this message thread is "application help".
>
> I see, but as the IDE _is_ an application, I feel that - if Lazarus is
> supposed to provide means for application programmers to integrate a
> help system in their apps and fill it with appropriate information - it
> would be a good idea to do both with the same tools, leveraging both the
> amount of work that needs to be done by those creating the system(s)
> that allow for inputting and displaying the help content, and the
> learning curve for those that as well use and help improving Lazarus (a
> big plus for an open source project as Lazarus is).

See Mark's and my thread on what to do to actually get things working
and Graeme's investigation into the chm help package (haven't looked at
that yet, myself).

I'm sorry but it seems so much more constructive to discuss actual ways
forward to solve things based on what we have now, even if it is step by
step, than to keep talking about abstract concepts.

We have a lot of components already there: a tool that can generate chm
files (even if it has limitations), a cross-platform viewer for chm help
(lhelp), a communication mechanism between application and help viewer
that tells the viewer what to show.

1. CHM context-sensitive help
We'd need to document the protocol used by the IDE to instruct the help
viewer to display certain help

2. Other help viewers
If we get the communication protocol documented, even other help viewers
like Graeme's docview could get adapted. This would mean more choice in
the help document format you use and the tools that can be used to
author help.

3. Ease of use
If we get the communication protocol "packaged up" as a Lazarus
component, it will make it easier for developers to add context
sensitive help.

4. HTML help
This page: http://wiki.freepascal.org/Add_Help_to_Your_Application
would indicate application help using HTML files is possible but lacks
context-sensitive help, i.e. directing the viewer to a specific keyword
or chapter.

Is this a direction that you would support?

Reinier


--

[Michael Schnell]

On 07/18/2012 01:41 PM, Reinier Olislagers wrote:
> I'm sorry but it seems so much more constructive to discuss actual
> ways forward to solve things based on what we have now, even if it is
> step by step, than to keep talking about abstract concepts.
While I do see your point, I of course don't agree.

To me it does make sense to decide whether I want to drink tee or beer,
before opening either the cupboard or the fridge. ;-)

-Michael

--

[Reinier Olislagers]

On 18-7-2012 14:04, Michael Schnell wrote:
> On 07/18/2012 01:41 PM, Reinier Olislagers wrote:
>> I'm sorry but it seems so much more constructive to discuss actual
>> ways forward to solve things based on what we have now, even if it is
>> step by step, than to keep talking about abstract concepts.
> While I do see your point, I of course don't agree.
>
> To me it does make sense to decide whether I want to drink tee or beer,
> before opening either the cupboard or the fridge. ;-)

Well... have you decided whether you want to have tea or beer? If so, why?

In other words, if you see another possible architecture/solution,
please share, as I'm sure that will help choose the best one.


--

[Michael Schnell]

On 07/18/2012 02:30 PM, Reinier Olislagers wrote:
> Well... have you decided whether you want to have tea or beer? If so,
> why?
Nope.

I just intended to provide a hint so that those that are inclined to do
some work on that behalf might consider this and might be able to do the
decision on an even broader base of information.

> In other words, if you see another possible architecture/solution,
> please share
I think I did exactly this:

My suggestion is, that the help system (displaying and help in a user
application and creating help content) Lazarus offers for it's users
should be the same that the IDE uses to provide help for the application
programmers and that enables Lazarus-contributors to create/update
Lazarus help content.

-Michael

--

[Reinier Olislagers]

On 18-7-2012 15:30, Michael Schnell wrote:
> On 07/18/2012 02:30 PM, Reinier Olislagers wrote:
>> Well... have you decided whether you want to have tea or beer? If so,
>> why?
> Nope.
>
> I just intended to provide a hint so that those that are inclined to do
> some work on that behalf might consider this and might be able to do the
> decision on an even broader base of information.
>
>> In other words, if you see another possible architecture/solution,
>> please share
> I think I did exactly this:
>
> My suggestion is, that the help system (displaying and help in a user
> application and creating help content) Lazarus offers for it's users
> should be the same that the IDE uses to provide help for the application
> programmers and that enables Lazarus-contributors to create/update
> Lazarus help content.

I'm sorry. You can't have your cake and eat it.
The high level idea you write above was already posted by e.g. Mark. You
(IIRC later) then wrote the same idea.
Then Mark & I proposed a way to implement it, Graeme did additional
research and I asked for your comments on that, and it turns out you
don't have any.
I still don't see the added value of your posts, and will leave it at that.


--

[Mark Morgan Lloyd]

Michael Schnell wrote:
> On 07/18/2012 01:41 PM, Reinier Olislagers wrote:
>> I'm sorry but it seems so much more constructive to discuss actual
>> ways forward to solve things based on what we have now, even if it is
>> step by step, than to keep talking about abstract concepts.
> While I do see your point, I of course don't agree.
>
> To me it does make sense to decide whether I want to drink tee or beer,
> before opening either the cupboard or the fridge. ;-)

But first you have to identify the need: that you're thirsty :-)

I think Reinier and I are saying that the need in the current case is
how to intercept F1 and recover an associated keyword, and how to pass
that keyword to lhelp.

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

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

--

[Michael Schnell]

On 07/18/2012 02:35 PM, Mark Morgan Lloyd wrote:
>
> But first you have to identify the need: that you're thirsty :-)
>
Yep. Seemingly both are: The application programmers that want to
provid3e a help system to their users, and the application programmers
that want to use a help system when working with Lazarus. Moreover those
willing to provide/update content to the Lazarus help system are
thirsty, too.

> I think Reinier and I are saying that the need in the current case is
> how to intercept F1 and recover an associated keyword, and how to pass
> that keyword to lhelp.
Of course you are right. This is one aspect of the functionality that
might be provided by the Lazarus LCL to have the application programmers
provide a "help" functionality to their users. Other aspects of this
functionality is launching a help viewer (or providing an internal one)
and allowing the programmer to create the help files in a decent way.

Beer: _When_ all this is resolved in a perfect way for the IDE, any
application programmer can just use it for his own product.
Tee: some unrelated system might be integrated in the LCL that is usable
for the application programmers' product. Same supposedly will use some
3rd party help writing tool.

-Michael



--

[Reinier Olislagers]

On 18-7-2012 15:39, Michael Schnell wrote:
> Tee: some unrelated system might be integrated in the LCL that is usable
> for the application programmers' product. Same supposedly will use some
> 3rd party help writing tool.
Sorry, perhaps we're talking at cross-purposes which may explain some of
the confusion.

Your tea option: having another help viewer integrated is *exactly* what
has already been proposed: the IDE<>lhelp communication protocol could
be used for third party help viewers, whatever file format that viewer
wants to use, and whatever tools that can be used to generate that file
format.

--

[Michael Schnell]

On 07/18/2012 03:44 PM, Reinier Olislagers wrote:
> Sorry, perhaps we're talking at cross-purposes which may explain some of
> the confusion.
>
> Your tea option: having another help viewer integrated is *exactly* what
> has already been proposed:
I do know.

With my contribution I just wanted to say that I think that this option
should not be put aside just because there are some difficulties
assigned to it (e.g it has been stated that fpdoc is not perfectly
suited for the task of creating such help content. So my hint was that
in the past there has been suggestions for improvements.

Sorry for being a troll (again).
-Michael

--

[Graeme Geldenhuys]

Hi,


> I think Reinier and I are saying that the need in the current case is how to
> intercept F1 and recover an associated keyword, and how to pass that keyword
> to lhelp.

Surely the "capturing of the F1 key press" functionality already
exists in LCL? I also see TControl.HelpType, TControl.HelpContext,
TControl.HelpKeyword and Application.HelpFile properties... Are they
just for show (not functional yet)?

Another problem I spotted was with the Application.HelpCommand()
signature. It's got the signature designed by Borland Delphi v1
(somewhere around then) for the use with the very old WinHelp help
viewer and the long discontinued .HLP files. I've already raised this
issue some years back, but received my usual answer that it will not
be changed - go figure. Anyway, a more sane signature for
Application.HelpCommand() would be like Delphi & Kylix defined it for
the CLX framework. As a matter of fact, the help system for CLX was
designed to be cross-platform and uses Interfaces to be very flexible.
It is probably the cleanest help system design I have ever seen, and
it supports multiple help viewers too. Kylix even came with two
reference implementations - a Man Page viewer and a HyperHelp viewer.

For more interesting discussions on Lazarus help system ideas, see
this message thread from way back in May 2006...

http://www.mail-archive.com/***@miraclec.com/msg07364.html


May 2006 was a busy month for talk about help systems and help
formats. If the archives would be easier to view, it would help a lot.
I found some links though, but they don't all start at the beginning
of each message thread.

http://www.mail-archive.com/***@miraclec.com/msg07274.html
http://www.mail-archive.com/***@miraclec.com/msg07368.html


--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> Hi,
>
>
>> I think Reinier and I are saying that the need in the current case is how to
>> intercept F1 and recover an associated keyword, and how to pass that keyword
>> to lhelp.
>
> Surely the "capturing of the F1 key press" functionality already
> exists in LCL? I also see TControl.HelpType, TControl.HelpContext,
> TControl.HelpKeyword and Application.HelpFile properties... Are they
> just for show (not functional yet)?

Of course they work- in the context of the HTML help components. But if
you'd been paying attention you'd have seen that what Reinier raised was
how to use lhelp's (socket?) interface to get it to display a named
page, and that's not very much use unless you can get the appropriate
keyword to the other end of the communication connection (i.e. get F1 to
behave properly).

Now I presume that the existing HTML help components tell the LCL that
they want F1 when they auto-register, but in the absence of comparable
components for CHM we need to know how to do it.

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

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

--

[Mattias Gaertner]

Graeme Geldenhuys <***@gmail.com> hat am 18. Juli 2012 um 19:53
geschrieben:

> Hi,
>
>
> > I think Reinier and I are saying that the need in the current case is how to
> > intercept F1 and recover an associated keyword, and how to pass that keyword
> > to lhelp.
>
> Surely the "capturing of the F1 key press" functionality already
> exists in LCL? I also see TControl.HelpType, TControl.HelpContext,
> TControl.HelpKeyword and Application.HelpFile properties... Are they
> just for show (not functional yet)?


They do work.
See here an example with HTML pages:
http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application


>
> Another problem I spotted was with the Application.HelpCommand()
> signature. It's got the signature designed by Borland Delphi v1
> (somewhere around then) for the use with the very old WinHelp help
> viewer and the long discontinued .HLP files.


There are:

function HelpCommand(Command: Word; Data: PtrInt): Boolean;
function HelpContext(Context: THelpContext): Boolean;
function HelpKeyword(const Keyword: String): Boolean;


The Keyword can be an arbitrary string. In the HTML viewer it is the path behind
the BaseURL.



> I've already raised this> issue some years back, but received my usual answer
> that it will not
> be changed - go figure. Anyway, a more sane signature for
> Application.HelpCommand() would be like Delphi & Kylix defined it for
> the CLX framework. As a matter of fact, the help system for CLX was
> designed to be cross-platform and uses Interfaces to be very flexible.
> It is probably the cleanest help system design I have ever seen, and
> it supports multiple help viewers too. Kylix even came with two
> reference implementations - a Man Page viewer and a HyperHelp viewer.


The current help system knows viewers and databases (= sources). It's not clx
compatible though.

Mattias

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:

> What I was talking about in this message thread is "application help".
> Integrating CHM help into your own applications, giving your end-users
> context sensitive help for your product. So far I have heard that

I agree that it's a distinction that has to be made.

> integrating CHM help into your own LCL-based applications are not
> possible, and that nobody here actually seems to ship help files with
> their own applications. I guess I'm the only exception to that rule.

I think it was Reinier who yesterday said that if the socket interface
used by lhelp was published (or at least if somebody could give us a
pointer to the location of the information) it would be a big step forwards.

> The following URL is exactly what I am talking about, but as I said,
> it only describes HTML help (lots of HTML files located in a folder),
> and has limited help abilities.
>
> http://wiki.freepascal.org/Add_Help_to_Your_Application

As I wrote yesterday, I've added a brief section to that page on
generating arbitrary .chm files.

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

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

--

[Reinier Olislagers]

On 18-7-2012 13:18, Mark Morgan Lloyd wrote:
> Graeme Geldenhuys wrote:
>> The following URL is exactly what I am talking about, but as I said,
>> it only describes HTML help (lots of HTML files located in a folder),
>> and has limited help abilities.
>>
>> http://wiki.freepascal.org/Add_Help_to_Your_Application
>
> As I wrote yesterday, I've added a brief section to that page on
> generating arbitrary .chm files.

I think you might mean this page?
http://wiki.freepascal.org/chm_backend_for_fpdoc


--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:
> On 18-7-2012 13:18, Mark Morgan Lloyd wrote:
>> Graeme Geldenhuys wrote:
>>> The following URL is exactly what I am talking about, but as I said,
>>> it only describes HTML help (lots of HTML files located in a folder),
>>> and has limited help abilities.
>>>
>>> http://wiki.freepascal.org/Add_Help_to_Your_Application
>> As I wrote yesterday, I've added a brief section to that page on
>> generating arbitrary .chm files.
>
> I think you might mean this page?
> http://wiki.freepascal.org/chm_backend_for_fpdoc

I do indeed. And there was I thinking that a certain party never
listened to anything anybody said... :-)

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

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

--

[Graeme Geldenhuys]

On 18 July 2012 12:18, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
>> http://wiki.freepascal.org/Add_Help_to_Your_Application
>
> As I wrote yesterday, I've added a brief section to that page on generating
> arbitrary .chm files.

Strange, as I see no such amendment. There is no mention of CHM
files, and the line at the bottom of the page footer says "This page
was last modified on 15 April 2012, at 11:44."

Maybe you amended some other wiki page?

--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> On 18 July 2012 12:18, Mark Morgan Lloyd
> <***@telemetry.co.uk> wrote:
>>> http://wiki.freepascal.org/Add_Help_to_Your_Application
>> As I wrote yesterday, I've added a brief section to that page on generating
>> arbitrary .chm files.
>
> Strange, as I see no such amendment. There is no mention of CHM
> files, and the line at the bottom of the page footer says "This page
> was last modified on 15 April 2012, at 11:44."
>
> Maybe you amended some other wiki page?

As Reinier points out, I was thinking of
http://wiki.freepascal.org/chm_backend_for_fpdoc Mea culpa.

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

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

--

[Michael Schnell]

On 07/17/2012 12:15 AM, Graeme Geldenhuys wrote:
> 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,
In fact search features (including "F1" fast search) are especially
essential to the usability of a help system.

As discussed some months ago: When e.g. Wiki is used to have users
crate/updates help information, I suppose some special definitions need
to be defined on top of the usual Wiki stuff to allow for search
support and for cross references to help information that is generated
by other tools.


-Michael

--

[Mattias Gaertner]

Michael Schnell <***@lumino.de> hat am 18. Juli 2012 um 11:54 geschrieben:

> On 07/17/2012 12:15 AM, Graeme Geldenhuys wrote:
> > 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,
> In fact search features (including "F1" fast search) are especially
> essential to the usability of a help system.
>
> As discussed some months ago: When e.g. Wiki is used to have users
> crate/updates help information, I suppose some special definitions need
> to be defined on top of the usual Wiki stuff to allow for search
> support and for cross references to help information that is generated
> by other tools.


Can you give an example?

Mattias

[Michael Schnell]

On 07/18/2012 12:15 PM, Mattias Gaertner wrote:
>
>
> Can you give an example?
>
>
I don't remember the details of what has been discussed at that time. I
just seem to remember that the said tool should be able to use as well
the user-updateable Wiki(s) as the (existing expert-updateable) files
(e.g. xmls managed by fpdoc) as a combined repository for the help
files. (Maybe this is done by converting the xmls in wikis, but I don't
remember and don't have a suggestion or opinion on how this might be
best done, I only feel that it would be a good thing.)

In fact if there are multiple wikis and/or XMLs, the wikis would need to
be equipped with keywords accessible by search functions, "F1" and maybe
usable as targets on other pages. I don't know if the Wiki database
format provides that out of the box. Independently of how the
combination with the existing XML files is accomplished,
cross-references seem to be necessary.

-Michael

[Graeme Geldenhuys]

Hi,

On 18 July 2012 16:10, Marco van de Voort <***@stack.nl> wrote:
> Basically the source for a CHM is
>
> a .hhp file, which is an ini-like format containing
> 1. references to which are the toplevel html files to link
> ....snip....

Thanks, those steps were really helpful. That gave me a good starting
point, and I'll Google .hhp files further.


> I don't think an application call makes sense at all. It should be IPC
> (dbus) like,
> to avoid multiple instances, and to avoid having settings at all.

I agree with this. fpGUI currently uses TProcess to start up DocView,
but that was just step 1 to get the help system going. I'm working on
step 2 now, which is the IPC communications.


> IOW an IPC call to register helpfiles at startup (and start a small daemon
> if necessary), and then just fire the
> "show help" or "give me index" commands.

Yes, that is how I understood it too. The dbugintf.pas unit and the
various "debug server" apps around are good working examples of this.


>> specific help topics. The fpgApplication instance has a HelpFile
>> property to specify where an applications specific INF help file is,
>
> (Only one helpfile per app?)

No, you can concatenate multiple help files, specify a help directory
(instead of a file), specify an environment variable etc... DocView is
very flexible with this.


> I don't ship Lazarus applications.

:-/ Time to speak to your boss then.


> At work I use Delphi, but I don't ship help with those either. (though I
> have in previous jobs). We ship latex generated manuals in PDF format for

You guys have it way to easy! :) All our apps must ship with help
files, and we have a separate installation PDF. Our end-users are not
the most computer literate, but they know everything about Maths and
Science.



--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:

>> At work I use Delphi, but I don't ship help with those either. (though I
>> have in previous jobs). We ship latex generated manuals in PDF format for
>
> You guys have it way to easy! :) All our apps must ship with help
> files, and we have a separate installation PDF. Our end-users are not
> the most computer literate, but they know everything about Maths and
> Science.

This is a bit like the argument about whether code should be commented
or properly-written. I normally argue for copious comments in source,
but at the same time I think I favour properly-designed forms and
components which don't need on-screen help.

Having a decent manual, possibly with weak linkage to the app so that it
opens on the right page (something that PDF is bad at) is a different issue.

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

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

--

[Graeme Geldenhuys]

On 18 July 2012 20:15, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
> the same time I think I favour properly-designed forms and components which
> don't need on-screen help.

Some of our apps have advanced features. eg: Dynamic views that the
user can customise, thus changing what they see, and how the data is
presented. We supply some default views, which they can use to base
there views on, or create new views from scratch. The "what is a
view", and "how to create your own views" are things that appear in
the application help. Then we also have some help and transaction
examples in our accounting section of the application. People learn
best by example - thus, that is in the application help. We don't
display detailed help per widget, but rather an overview of each
dialog, and what is is for. And more detailed help for things like the
two examples I listed above.


> Having a decent manual, possibly with weak linkage to the app so that it
> opens on the right page (something that PDF is bad at) is a different issue.

We even have one-to-one training sessions on our applications and
business practices (we are a franchise business)... and amazingly we
still get phone calls about certain things. :)


--
Regards,
- Graeme -


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

--

[Reinier Olislagers]

On 19-7-2012 10:09, Graeme Geldenhuys wrote:
>> > Having a decent manual, possibly with weak linkage to the app so that it
>> > opens on the right page (something that PDF is bad at) is a different issue.
> We even have one-to-one training sessions on our applications and
> business practices (we are a franchise business)... and amazingly we
> still get phone calls about certain things. :)

LOL ;)

<cynical>As always, it's a careful balance between providing help[1]
that nobody reads versus not providing any help which users can then
complain about ;)</cynical

[1] And the advanced version: help that actually helps vs help where
some keywords are thrown together in order to give the appearance of
having made the effort...

--

[Marco van de Voort]

On Wed, Jul 18, 2012 at 07:26:29PM +0100, Graeme Geldenhuys wrote:
> > (Only one helpfile per app?)
>
> No, you can concatenate multiple help files, specify a help directory
> (instead of a file), specify an environment variable etc... DocView is
> very flexible with this.



> > I don't ship Lazarus applications.
>
> :-/ Time to speak to your boss then.

It's mostly my call. There is nothing much to gain there.

> > At work I use Delphi, but I don't ship help with those either. (though I
> > have in previous jobs). We ship latex generated manuals in PDF format for
>
> You guys have it way to easy! :) All our apps must ship with help
> files, and we have a separate installation PDF. Our end-users are not
> the most computer literate, but they know everything about Maths and
> Science.

Well, the pdf manuals are on average 100-150 pages, but sometimes 300 pages,
40-60% of which is custom per project. Then on top of that, blueprints and
BOMs of all mechanical parts.

--

[Mark Morgan Lloyd]

Marco van de Voort wrote:

> Well, the pdf manuals are on average 100-150 pages, but sometimes 300 pages,
> 40-60% of which is custom per project. Then on top of that, blueprints and
> BOMs of all mechanical parts.

Do you ever have a situation where you need to index into a PDF, and if
so how do you cope?

I'm looking at something where it would be beneficial to have a
collection of electronics info, and I'd want immediate access to a given
section. Allowing for the dominance of PDF in that industry, the best I
can think of so far is to burst each PDF into pages, and then convert
each page back to PDF.

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

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

--

[Reinier Olislagers]

On 23-7-2012 12:16, Mark Morgan Lloyd wrote:
> Marco van de Voort wrote:
> Do you ever have a situation where you need to index into a PDF, and if
> so how do you cope?
>
> I'm looking at something where it would be beneficial to have a
> collection of electronics info, and I'd want immediate access to a given
> section. Allowing for the dominance of PDF in that industry, the best I
> can think of so far is to burst each PDF into pages, and then convert
> each page back to PDF.

Are you talking about PDFs with digital text or images with hidden text
("searchable PDFs" as they are sometimes called) as opposed to images only?

If so, extracting the text using e.g. pdftotext (e.g. page by page),
finding the text etc and instructing a pdf reader to open at a certain
page - if that reader supports it - may be helpful??
E.g. for the Sumatra PDF reader (IIRC, only available on Windows):
sumatrapdf -page <pageno>

Depending on the reader, you could do more, see e.g.:
https://code.google.com/p/sumatrapdf/wiki/CommandLineArguments

If the PDFs are images only, the only feasible way I'd see would be to
extract the images, OCR them and deal with it then; e.g. rebuild the
PDFs, adding the resulting text as hidden images, e.g. with the Linux
hocr2pdf tool provided by the exactimage package:
http://www.exactcode.com/site/open_source/exactimage/


FYI, I'm actually in the process of building a fairly simple document
scanning solution (for now on Linux) that:
- scans the document using sane, outputing tiff files
- performs optional cleanup, e.g. with the scantailor package
- recognizes text with tesseract, output layout/text info into hocr format
- combines the image and text into "searchable PDFs" using hocr2pdf
- adds metadata to the PDF
- adds the text to either a database or more probably some kind of full
text search package
- registers the scan into a database
- provide a viewer to search for documents, print them etc; in future
perhaps to be used for correcting OCR results

Not very far, but:
https://bitbucket.org/reiniero/papertiger/overview

For Dutch speaking readers: yes, the project name is intentional ;)

--

[Bart]

On 7/23/12, Reinier Olislagers <***@gmail.com> wrote:

> For Dutch speaking readers: yes, the project name is intentional ;)

LOL

Bart

--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:
> On 23-7-2012 12:16, Mark Morgan Lloyd wrote:

>> Do you ever have a situation where you need to index into a PDF, and if
>> so how do you cope?
>>
>> I'm looking at something where it would be beneficial to have a
>> collection of electronics info, and I'd want immediate access to a given
>> section. Allowing for the dominance of PDF in that industry, the best I
>> can think of so far is to burst each PDF into pages, and then convert
>> each page back to PDF.
>
> Are you talking about PDFs with digital text or images with hidden text
> ("searchable PDFs" as they are sometimes called) as opposed to images only?

Any sort of PDF, including murky scans from Bitsavers.

> If so, extracting the text using e.g. pdftotext (e.g. page by page),
> finding the text etc and instructing a pdf reader to open at a certain
> page - if that reader supports it - may be helpful??
> E.g. for the Sumatra PDF reader (IIRC, only available on Windows):
> sumatrapdf -page <pageno>
>
> Depending on the reader, you could do more, see e.g.:
> https://code.google.com/p/sumatrapdf/wiki/CommandLineArguments

Although highly non-portable. My thoughts were to have documentation on
a server to be available to anybody using a specialist Lazarus app, the
whole thing would be spoilt if as well as loading the app (tentatively,
Borg-UI) and possibly lhelp and associated CHMs I required users to find
a specific PDF reader and possibly integrate it with their browser.

> If the PDFs are images only, the only feasible way I'd see would be to
> extract the images, OCR them and deal with it then; e.g. rebuild the
> PDFs, adding the resulting text as hidden images, e.g. with the Linux
> hocr2pdf tool provided by the exactimage package:
> http://www.exactcode.com/site/open_source/exactimage/

Although even if the original wasn't a bitmap from Bitsavers,
electronics stuff with lots of tabular material (control registers and
the likes) is notoriously difficult to reformat. I /hope/ to be able to
get the docs into a database (PostgreSQL handles binaries fairly well,
which would simplify some of the replication/dissemination issues) even
if they were saved as files local to each HTTP daemon.

> FYI, I'm actually in the process of building a fairly simple document
> scanning solution (for now on Linux) that:
> - scans the document using sane, outputing tiff files
> - performs optional cleanup, e.g. with the scantailor package
> - recognizes text with tesseract, output layout/text info into hocr format
> - combines the image and text into "searchable PDFs" using hocr2pdf
> - adds metadata to the PDF
> - adds the text to either a database or more probably some kind of full
> text search package
> - registers the scan into a database
> - provide a viewer to search for documents, print them etc; in future
> perhaps to be used for correcting OCR results
>
> Not very far, but:
> https://bitbucket.org/reiniero/papertiger/overview
>
> For Dutch speaking readers: yes, the project name is intentional ;)

I'm afraid I don't speak Dutch, although my mother used to quote "Bûter,
brea, en griene tsiis" out of context every few months. But I like the
palindrome :-)

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

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

--

[Reinier Olislagers]

On 23-7-2012 13:40, Mark Morgan Lloyd wrote:
> Reinier Olislagers wrote:
>> On 23-7-2012 12:16, Mark Morgan Lloyd wrote:
>> Are you talking about PDFs with digital text or images with hidden text
>> ("searchable PDFs" as they are sometimes called) as opposed to images
>> only?
>
> Any sort of PDF, including murky scans from Bitsavers.
>
>> If so, extracting the text using e.g. pdftotext (e.g. page by page),
>> finding the text etc and instructing a pdf reader to open at a certain
>> page - if that reader supports it - may be helpful??
>> E.g. for the Sumatra PDF reader (IIRC, only available on Windows):
>> sumatrapdf -page <pageno>
>>
>> Depending on the reader, you could do more, see e.g.:
>> https://code.google.com/p/sumatrapdf/wiki/CommandLineArguments
>
> Although highly non-portable.
Agreed. Any takers for adding PDF functionality to lhelp or docview ;)
Note: viewers like SumatraPDF can be used without installation, so it
becomes a matter of deployment with your application.

You'd still face issues with Linux/OSX of course.

> My thoughts were to have documentation on
> a server to be available to anybody using a specialist Lazarus app, the
> whole thing would be spoilt if as well as loading the app (tentatively,
> Borg-UI) and possibly lhelp and associated CHMs I required users to find
> a specific PDF reader and possibly integrate it with their browser.

Your idea of extracting the single relevant PDF page into a separate PDF
and presenting that to the user could work, especially if you provide
forward/back navigation buttons (in a Lazarus app or web browser+PDF
plugin).
On Windows you might be able to embed some Activex PDF control, once
again not portable...

Captain obvious: I'd balance ease of use for this solution versus
distributing a portable PDF viewer and telling that to go to a certain page.

>> If the PDFs are images only, the only feasible way I'd see would be to
>> extract the images, OCR them and deal with it then; e.g. rebuild the
>> PDFs, adding the resulting text as hidden images, e.g. with the Linux
>> hocr2pdf tool provided by the exactimage package:
>> http://www.exactcode.com/site/open_source/exactimage/
>
> Although even if the original wasn't a bitmap from Bitsavers,
> electronics stuff with lots of tabular material (control registers and
> the likes) is notoriously difficult to reformat.
Yes, but I wasn't talking about reformatting, just pasting the invisible
text "behind" the visible graphics (in another layer) in the PDF.
Alternatively, you could store the retrieved text (and page numbers)
somewhere else.

Of course, OCR itself may be crummy with these kinds of PDFs... which
will lead to search misses/false positives.

If you have graphics-only PDFs and want to do text search you'd have to
perform this step if you want to go to a certain spot based on a user
search... unless you retype the text...


I /hope/ to be able to
> get the docs into a database (PostgreSQL handles binaries fairly well,
> which would simplify some of the replication/dissemination issues) even
> if they were saved as files local to each HTTP daemon.
Sounds like a large system?
You'd be having multiple HTTP servers that serve up PDFs coming from the
db? And viewing those with a web browser?
That does confuse me: what do you use the "specialist Lazarus app" for
you talked about earlier?

>> For Dutch speaking readers: yes, the project name is intentional ;)
>
> I'm afraid I don't speak Dutch, although my mother used to quote "Bûter,
> brea, en griene tsiis" out of context every few months. But I like the
> palindrome :-)
Butter, bread and green cheese in Frisian? (Note: as the Frisians will
insist on telling you, different language from Dutch... only reason I
seem to understand the words is context and because it's close to both
English and Dutch ;)



--

[Mark Morgan Lloyd]

Reinier Olislagers wrote:

> I /hope/ to be able to
>> get the docs into a database (PostgreSQL handles binaries fairly well,
>> which would simplify some of the replication/dissemination issues) even
>> if they were saved as files local to each HTTP daemon.
> Sounds like a large system?
> You'd be having multiple HTTP servers that serve up PDFs coming from the
> db? And viewing those with a web browser?
> That does confuse me: what do you use the "specialist Lazarus app" for
> you talked about earlier?

I'd rather not discuss the problem domains at the moment, but yes: a big
system with a tree of database servers (PostgreSQL, with the option of
Firebird at the leaves). I'm hoping to be able to use the same (or at
least a very similar) app both at each analyst's client computer and to
aggregate state at each node in the tree.

I'm hoping to be able to say more at some point, because apart from
anything else making it open (or at least free-distribution) and
applicable to some juicy problems would be the best way of testing that
it scales.

>>> For Dutch speaking readers: yes, the project name is intentional ;)
>> I'm afraid I don't speak Dutch, although my mother used to quote "Bûter,
>> brea, en griene tsiis" out of context every few months. But I like the
>> palindrome :-)
> Butter, bread and green cheese in Frisian? (Note: as the Frisians will
> insist on telling you, different language from Dutch... only reason I
> seem to understand the words is context and because it's close to both
> English and Dutch ;)

She always used to use it to demonstrate the similarity between English
and Friesian, but my more recent understanding is that it was also used
as a shibboleth that only Friesians could pronounce properly. But she
was Welsh, so you have to make allowances :-)

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

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

--

[Graeme Geldenhuys]

On 23 July 2012 13:13, Reinier Olislagers <***@gmail.com> wrote:
>>
>> Although highly non-portable.
> Agreed. Any takers for adding PDF functionality to lhelp or docview ;)


DocView will shortly have PDF support - but only in the form of saving
help topics or selected topics to PDF, which could then later be
printed (or emailed) if needed.


As for your whole idea of using PDF's as some form of application help
system - that's just crazy. You are trying to fit a square into a
round hole. Use a decent documentation system like DocView instead -
which was designed for that purpose.



--
Regards,
- Graeme -


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

--

[Michael Van Canneyt]

On Mon, 23 Jul 2012, Graeme Geldenhuys wrote:

> On 23 July 2012 13:13, Reinier Olislagers <***@gmail.com> wrote:
>>>
>>> Although highly non-portable.
>> Agreed. Any takers for adding PDF functionality to lhelp or docview ;)
>
>
> DocView will shortly have PDF support - but only in the form of saving
> help topics or selected topics to PDF, which could then later be
> printed (or emailed) if needed.
>
>
> As for your whole idea of using PDF's as some form of application help
> system - that's just crazy. You are trying to fit a square into a
> round hole. Use a decent documentation system like DocView instead -
> which was designed for that purpose.

I don't agree it is crazy ?

I use PDF for application help. Works perfectly, F1 and all.
It has all properties you expect from a help system (including hyperlinks),
and can be used to print to boot.


Michael.

--

[Graeme Geldenhuys]

On 23 July 2012 19:27, Michael Van Canneyt <***@freepascal.org> wrote:
>
> I use PDF for application help. Works perfectly, F1 and all. It has all

Yes, you told me that a long time ago. But I also remember you told me
that it only works in Windows. Plus the "help" is at the mercy of the
documentation writer.... by that I mean, there might not be a Index or
a Table of Content, and Searching PDF's are damn slow. And while we
are talking about slow - Acrobat Reader (installed by most users,
especially under Windows) has the longest start-up time of any PDF
reader.

Yup, still a crazy idea. ;-)


--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> On 23 July 2012 19:27, Michael Van Canneyt <***@freepascal.org> wrote:
>> I use PDF for application help. Works perfectly, F1 and all. It has all
>
> Yes, you told me that a long time ago. But I also remember you told me
> that it only works in Windows. Plus the "help" is at the mercy of the
> documentation writer.... by that I mean, there might not be a Index or
> a Table of Content, and Searching PDF's are damn slow. And while we
> are talking about slow - Acrobat Reader (installed by most users,
> especially under Windows) has the longest start-up time of any PDF
> reader.
>
> Yup, still a crazy idea. ;-)

It's not as crazy as using a pseudo-standard such as one of the MS Word
or Open/Libre Office formats, or the sanitized versions which IBM et al.
are pushing in their attempts to prove to various governments that they
are 100% behind open standards. But I remain very concerned about the
level of support- i.e. with any reader on any platform- to jump to a
predefined entry point in a PDF.

And quite frankly, when looking at a fairly wide range of OSes and CPUs,
Adobe's reader is better than the alternatives particularly when there's
a thousand or so pages in a document (like the IBM S/390 manual I'm
using to put myself to sleep at night).

From the POV of the Lazarus IDE, /the/ important thing is rapid and
correct loading of a page in response to F1. If the storage format that
this dictates can be easily created and exploited by user-written
programs- which (with the possible exception of F1 support) is pretty
much where we are with .chm- then all the better, because it means that
the maximum number of people are focusing on improving performance and
reliability.

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

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

--

[Graeme Geldenhuys]

On 24 July 2012 09:44, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
>
> And quite frankly, when looking at a fairly wide range of OSes and CPUs,
> Adobe's reader is better than the alternatives particularly when there's a
> thousand or so pages in a document (like the IBM S/390 manual I'm using to
> put myself to sleep at night).

Make no mistake, Adobe Reader does good rendering, and performs better
than other PDF readers when it comes to graphic intensive PDF's like
"Linux Format Magazine" monthly editions etc. But I must say that
Evince (Gnome default) and Okular (KDE default) has fantastic
performance, and has much faster startup times than Adobe Reader.
Evince and Okular also has no problems in opening the 1700+ page PDF
of FPC's RTL for example.


--
Regards,
- Graeme -


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

--

[Marco van de Voort]

On Mon, Jul 23, 2012 at 10:16:04AM +0000, Mark Morgan Lloyd wrote:
> Marco van de Voort wrote:
>
> > Well, the pdf manuals are on average 100-150 pages, but sometimes 300 pages,
> > 40-60% of which is custom per project. Then on top of that, blueprints and
> > BOMs of all mechanical parts.
>
> Do you ever have a situation where you need to index into a PDF, and if
> so how do you cope?

No. We don't do help. Stronger even, I haven't really in past jobs either,
since those were server apps.

So all my helpfile stuff is hobby, but that goes back a long time. I was
already dabbling with helpfile systems in my topspeed days (before FPC)

> I'm looking at something where it would be beneficial to have a
> collection of electronics info, and I'd want immediate access to a given
> section. Allowing for the dominance of PDF in that industry, the best I
> can think of so far is to burst each PDF into pages, and then convert
> each page back to PDF.

Since I don't HAVE TO deploy anything, I only work on long term
solutions. IMHO this is not one :-)

For the same reason, I don't like the constant Kylix help recommendations
either. Fine for isolated cases, but shouldn't be promoted as general thing
to do IMHO

--

[Mark Morgan Lloyd]

Marco van de Voort wrote:

> For the same reason, I don't like the constant Kylix help recommendations
> either. Fine for isolated cases, but shouldn't be promoted as general thing
> to do IMHO

Strongly agreed. The ONLY case in which these might be applicable is
when somebody is working on x86 Linux, in all other cases the fact that
a closed-source reader is required detracts from Lazarus's claim to be
cross-platform. Not to mention the copyright aspect.

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

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

--

[Graeme Geldenhuys]

On 27 July 2012 14:05, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
>
> Strongly agreed. The ONLY case in which these might be applicable is when


The reasoning for recommending Kylix Help to Lazarus users was simple.
Only in the last year or so did the Lazarus LCL actually start getting
help. Not to mention that Lazarus didn't even have a offline help
system to compete with anything out there. I still feel to this day,
the Kylix Help is still a lot more complete, detailed and useful, with
working example code too.

As for the x86 Linux only comment.... Well, tough sh*t to the Windows
and Mac users. I paid for Kylix Enterprise, so why the hell may I not
reuse what I paid a fortune for! In any case, LCL is supposed to be a
VCL clone (just like CLX), so the Delphi/Kylix help should be very
appropriate to LCL - if not, then the Lazarus project didn't do a very
good job cloning Delphi VCL.


--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> On 27 July 2012 14:05, Mark Morgan Lloyd
> <***@telemetry.co.uk> wrote:
>> Strongly agreed. The ONLY case in which these might be applicable is when
>
>
> The reasoning for recommending Kylix Help to Lazarus users was simple.
> Only in the last year or so did the Lazarus LCL actually start getting
> help. Not to mention that Lazarus didn't even have a offline help
> system to compete with anything out there. I still feel to this day,
> the Kylix Help is still a lot more complete, detailed and useful, with
> working example code too.

It's also copyright, and you were very quick to point out the
questionable status of somebody's contribution earlier in the day.

However I agree that Lazarus and FPC help still has some way to go.

> As for the x86 Linux only comment.... Well, tough sh*t to the Windows
> and Mac users. I paid for Kylix Enterprise, so why the hell may I not
> reuse what I paid a fortune for! In any case, LCL is supposed to be a
> VCL clone (just like CLX), so the Delphi/Kylix help should be very
> appropriate to LCL - if not, then the Lazarus project didn't do a very
> good job cloning Delphi VCL.

You miss my point. The proprietary viewer is NBG on Linux running on
ARM, MIPS, PPC, SPARC and so on. And it's NBG for Solaris and BSD on any
CPU. Not to mention Windows, OS X, or minority operating systems such as
OS/2.

So while I agree wholeheartedly that you (or anybody else who's paid for
Kylix, and arguably anybody who's been given a legitimate free copy)
should be able to use the help files even as an aid to migrating to
another development environment, I don't think it's appropriate for them
to be recommended for use in other contexts.

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

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

--

[Graeme Geldenhuys]

Hi,

On 27 July 2012 21:25, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
>
> It's also copyright, and you were very quick to point out the questionable
> status of somebody's contribution earlier in the day.

I NEVER implied that the Lazarus project must use the Kylix Help
viewer as "the lazarus help viewer". I also NEVER implied that the
Kylix Help must be copied or used verbatim as "the lazarus help". The
suggestion was always meant as a "stop gap" option, while the Lazarus
help was non-existent.

Not to mention that you could have received a copy of the Kylix Open
Edition product - which was freely available as magazine cover CD's
etc back in 2000-2004. Kylix Open Edition - for use for developing GPL
software - is still available for download from various locations on
the internet - it's just not supported by Embarcadero any more.


> You miss my point. The proprietary viewer is NBG on Linux running on ARM,

Again, I NEVER said the Kylix Help Viewer must become the official
Lazarus help viewer. You came up with that idea all by yourself.



--
Regards,
- Graeme -


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

--

[Mark Morgan Lloyd]

I flatly refuse to get into a querulous, nitpicking quibble about who
wrote what and with what intention. But

Graeme Geldenhuys wrote:

>> You miss my point. The proprietary viewer is NBG on Linux running on ARM,
>
> Again, I NEVER said the Kylix Help Viewer must become the official
> Lazarus help viewer. You came up with that idea all by yourself.

I'd point out that when I wrote

"...the fact that a closed-source reader is required detracts from
Lazarus's claim to be cross-platform."

you countered with

"As for the x86 Linux only comment.... Well, tough sh*t to the Windows
and Mac users."

I really don't know where you got this "the Kylix Help Viewer must
become the official Lazarus help viewer" thing from, I've certainly
neither suggested it nor said that you've suggested it. I /have/ pointed
out that having the Kylix helpfiles is no substitute to having
Lazarus-specific ones because of the former's limited portability, which
is hardly the same thing.

I suggest that we just drop this subthread, before it gets excessively
tedious to the rest of the community. After all, we've all got things to
get on with that are more suited to our skills, like writing code that
doesn't involve reasoned public argument :-)

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

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

--

[Kostas Michalopoulos]

I just noticed this (there is a lot of activity in the mailing list and
i only browse it occasionally).

On 10/7/2012 6:39 μμ, Graeme Geldenhuys wrote:
> Hi,
> 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?
>

Personally i have written a custom help system:

http://badsector.github.com/lazhelp/

It is made up of a bunch of components that can either provide the help
content from inside the program (f.e. from a resource or just a string
list) or from an external file. The help can be displayed as a
popup/tooltip, inside a panel using a custom control or a separate
window with back, forward, home and other optional buttons (like
introduction, tutorial, etc). It can also be registered as a help
provider for LCL (so you can use HelpContext etc in controls).

The viewer is written with LCL so it should be portable (although there
are some inconsistencies, especially regarding scrollbars). There aren't
many things supported by the language (which has a simple syntax) but it
should be enough for simple applications. For larger help sites, it
probably needs more stuff (f.e. there is no table support).

I have used it for Runtime World, my 3D world editor:

http://chiselapp.com/user/badsector/repository/rtworld/

and for LILCard, a hypercard-like program:

https://github.com/badsector/lilcard

(the latter shows how the help system can become part of the executable
itself since lilcard is a single executable in all platforms)

The reason i made it is, as you have said in other threads, i find
Lazarus current help situation to be inadequate at least. Additionally,
i don't want to distribute a huge executable for viewing CHM files (in
the case the user's computer do not have the ability to view CHM files)
and i find the CHM viewer's user interface to be somewhat complex.

Kostas "Bad Sector" Michalopoulos


--

[William Oliveira Ferreira]

Seems to be a good project.

Could someone from LazCore make a test on it?

I think it should be a step foward to a Lazarus' Embedded Help System

2012/7/28 Kostas Michalopoulos <***@gmail.com>

> I just noticed this (there is a lot of activity in the mailing list and i
> only browse it occasionally).
>
> On 10/7/2012 6:39 ΌΌ, Graeme Geldenhuys wrote:
>
>> Hi,
>>
>> 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?
>>
>>
> Personally i have written a custom help system:
>
> http://badsector.github.com/**lazhelp/<http://badsector.github.com/lazhelp/>
>
> It is made up of a bunch of components that can either provide the help
> content from inside the program (f.e. from a resource or just a string
> list) or from an external file. The help can be displayed as a
> popup/tooltip, inside a panel using a custom control or a separate window
> with back, forward, home and other optional buttons (like introduction,
> tutorial, etc). It can also be registered as a help provider for LCL (so
> you can use HelpContext etc in controls).
>
> The viewer is written with LCL so it should be portable (although there
> are some inconsistencies, especially regarding scrollbars). There aren't
> many things supported by the language (which has a simple syntax) but it
> should be enough for simple applications. For larger help sites, it
> probably needs more stuff (f.e. there is no table support).
>
> I have used it for Runtime World, my 3D world editor:
>
> http://chiselapp.com/user/**badsector/repository/rtworld/<http://chiselapp.com/user/badsector/repository/rtworld/>
>
> and for LILCard, a hypercard-like program:
>
> https://github.com/badsector/**lilcard<https://github.com/badsector/lilcard>
>
> (the latter shows how the help system can become part of the executable
> itself since lilcard is a single executable in all platforms)
>
> The reason i made it is, as you have said in other threads, i find Lazarus
> current help situation to be inadequate at least. Additionally, i don't
> want to distribute a huge executable for viewing CHM files (in the case the
> user's computer do not have the ability to view CHM files) and i find the
> CHM viewer's user interface to be somewhat complex.
>
> Kostas "Bad Sector" Michalopoulos
>
>
>
> --
> ______________________________**_________________
> Lazarus mailing list
> ***@lists.lazarus.**freepascal.org<***@lists.lazarus.freepascal.org>
> http://lists.lazarus.**freepascal.org/mailman/**listinfo/lazarus<http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus>
>



--
________________________________
William de Oliveira Ferreira

[Mattias Gaertner]

On Sat, 28 Jul 2012 15:01:36 +0200
Kostas Michalopoulos <***@gmail.com> wrote:

> I just noticed this (there is a lot of activity in the mailing list and
> i only browse it occasionally).
>
> On 10/7/2012 6:39 μμ, Graeme Geldenhuys wrote:
> > Hi,
> > 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?
> >
>
> Personally i have written a custom help system:
>
> http://badsector.github.com/lazhelp/

About the name "lazhelp":
I'm not a great namer myself, and tend to use technical names as well,
so I understand your choice for the name.
But I fear the name "lazhelp" has become confusingly ambiguous.

To avoid name clashes with third parties the Lazarus developers
prefix/postfix all new units, for example with "laz". If third parties
use the same prefixes, we have a problem. ;)
So I ask anyone kindly to be more innovative when creating new projects.


> It is made up of a bunch of components that can either provide the help
> content from inside the program (f.e. from a resource or just a string
> list) or from an external file. The help can be displayed as a
> popup/tooltip, inside a panel using a custom control or a separate
> window with back, forward, home and other optional buttons (like
> introduction, tutorial, etc). It can also be registered as a help
> provider for LCL (so you can use HelpContext etc in controls).

Nice.


> The viewer is written with LCL so it should be portable (although there
> are some inconsistencies, especially regarding scrollbars). There aren't
> many things supported by the language (which has a simple syntax) but it
> should be enough for simple applications. For larger help sites, it
> probably needs more stuff (f.e. there is no table support).
>
> I have used it for Runtime World, my 3D world editor:
>
> http://chiselapp.com/user/badsector/repository/rtworld/
>
> and for LILCard, a hypercard-like program:
>
> https://github.com/badsector/lilcard
>
> (the latter shows how the help system can become part of the executable
> itself since lilcard is a single executable in all platforms)
>
> The reason i made it is, as you have said in other threads, i find
> Lazarus current help situation to be inadequate at least. Additionally,
> i don't want to distribute a huge executable for viewing CHM files (in
> the case the user's computer do not have the ability to view CHM files)
> and i find the CHM viewer's user interface to be somewhat complex.

Huh?
The chm viewer "lhelp" has only "home", "backward", "forward" and a menu
to open and close chm files. If I understood your above text
correct, this is less than your viewer.

The reason for a separate executable is that the help viewer should be
usable independent of any modal forms, mdi, hints or docking of the
application.
Of course it would be nice to have a LCL control
to view chm files in applications. It should not be that hard to write.

Mattias

--

[Mark Morgan Lloyd]

Graeme Geldenhuys wrote:
> On 10 July 2012 14:52, Mark Morgan Lloyd
>> <***@telemetry.co.uk> wrote:

>> Finally, if I just want to add a few lines of plain text as
>> context-sensitive help for a control or form, with the main documentation
>
> Which one is it? Control or Form? If it's a Control, then it falls
> under the Class / API help, which means XML files must be edited. If
> it is a Form (as in application help describing a dialog in your
> application), then it's something else.

On reflection, in both cases I think I mean context-sensitive help in
the context of an app. In other words: either F1 on say a toolbar button
or an edit field, or a button labeled "Help" which describes a form. I'm
definitely not thinking about documentation for a new control, to be
displayed in the IDE.

I think .chm can be generated from DocBook (hence from e.g. Lyx), but
one is rapidly getting to the point where there is more documentation
software than development software on your computer. I've seen mention
of something called DITA Open Tools but again it appears pretty heavy.

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

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

--

[Graeme Geldenhuys]

Hi Mark,

On 10 July 2012 20:42, Mark Morgan Lloyd
<***@telemetry.co.uk> wrote:
> On reflection, in both cases I think I mean context-sensitive help in the
> context of an app. In other words: either F1 on say a toolbar button or an


OK, then we are thinking of the same thing. :) Context sensitive help
used in our own developed applications.

The subject of "context sensitive help" gets a bit confusing when it
comes to something like an IDE, because in such a case you have
"application help" describing the dialogs of the IDE, and you have
Framework / API help for the programming language you are writing
using the IDE.


--
Regards,
- Graeme -


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

--

[Michael Schnell]

On 07/10/2012 05:12 PM, Graeme Geldenhuys wrote:
> If you are referring to the help viewer, then again, that is where
> LHelp lags behind. DocView allows you to annotate (add inline
> comments) any INF files. Those annotations are stored in a separate
> file (<helpfile>.notes), which you can move around or copy with the
> INF file to a new computer if you want. LHelp has no such functionality.

Hmm. While I personally agree, that DocView in many aspects has a lot
advantages, referring to the *big* discussion on that we had in this
forum, I had the impression, that the "powers" decided, that - if any
work is dedicated to improving the help system - that should be done for
a (rather new) method that allows to use (online) Wikis as a source for
offline files providing the advantage that there is a rather
standardized and commonly accepted and ubiquitously available way to
have users improve the help content.

I don't know how far this idea is advanced (e.g. regarding providing
search capability across multiple help "chapters") right now and which
and how offline help content files can already generated that way.

-Michael



--