installing chm help

[waldo kitty]

ok, i decided to go back and retry this all over again... i'm following the
instructions in the wiki as linked to by the default Help->Online Help page...

http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE


[quote]
Installing CHM Help for The RTL, FCL and LCL in the Lazarus IDE
If you are using Lazarus from Subversion

The Lazarus help files can be installed following this easy steps:

1) Make sure that the package chmhelppkg is intalled. See the menu
Package->Install Packages. This package is installed by default in the "bigide"
so most users should already have it installed.

2) Open the project lazarus/components/chmhelp/lhelp/lhelp.lpi

3) Build this project

4) Download the latest stable Lazarus CHM help files from
http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/

5) Copy all CHM files to lazarus/docs/html

Now context sensitive help using F1 should already be working.
[/quote]


i don't recall how my initial lazarus was built from svn... i do not believe it
was with "bigide", though... as such, i did not have this chmhelppkg
installed... so, by the numbers...


1. install chmhelppkg in the ide packages interface. save and rebuild the ide...
ok...

2. opened the project specified

3. built it with SHIFT-F9

4. pulled a chm tar.bz2 file

5. extracted three chm files to my freepascal/laz/docs/html

placed the cursor on a pascal keyword (ie: implementation in the currently
opened file from when i opened the lhelp.lpi), pressed F1 and... no help :(


so... alright... i don't recall everything else that was done but i do recall a
help path in the ide options... hummm... why is it set to C:\lazarus\docs\html??
that directory has not existed on this machine in a very long time... definitely
not since i started using the wiki documented method for updating from SVN at
which time i deleted everything related to fpc and lazarus... so i change the
path to C:\freepascal\laz\docs\html and exit the options dialog via 'ok'...
cursor is still on implementation so hit F1 again... same as before... no
help... try other keywords with same results...

the results are that i get two windows... the first one says "Help keyword
FPCKeyword_implementation not found" and the only option is the [Cancel]
button... the next window then says "No help found for
C:\freepascal\laz\components\chmhelp\lhelp\httpcontentprovider.pas" (38,7)...

so why isn't this working??? what is the key step that has been left out of the
instructions??


--

[Sven Barth]

Post by waldo kitty
ok, i decided to go back and retry this all over again... i'm following
the instructions in the wiki as linked to by the default Help->Online
Help page...
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE
[quote]
Installing CHM Help for The RTL, FCL and LCL in the Lazarus IDE
If you are using Lazarus from Subversion
1) Make sure that the package chmhelppkg is intalled. See the menu
Package->Install Packages. This package is installed by default in the
"bigide" so most users should already have it installed.
2) Open the project lazarus/components/chmhelp/lhelp/lhelp.lpi
3) Build this project
4) Download the latest stable Lazarus CHM help files from
http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/
5) Copy all CHM files to lazarus/docs/html
Now context sensitive help using F1 should already be working.
[/quote]
i don't recall how my initial lazarus was built from svn... i do not
believe it was with "bigide", though... as such, i did not have this
chmhelppkg installed... so, by the numbers...
1. install chmhelppkg in the ide packages interface. save and rebuild
the ide... ok...
2. opened the project specified
3. built it with SHIFT-F9
4. pulled a chm tar.bz2 file
5. extracted three chm files to my freepascal/laz/docs/html
placed the cursor on a pascal keyword (ie: implementation in the
currently opened file from when i opened the lhelp.lpi), pressed F1
and... no help :(
so... alright... i don't recall everything else that was done but i do
recall a help path in the ide options... hummm... why is it set to
C:\lazarus\docs\html?? that directory has not existed on this machine in
a very long time... definitely not since i started using the wiki
documented method for updating from SVN at which time i deleted
everything related to fpc and lazarus... so i change the path to
C:\freepascal\laz\docs\html and exit the options dialog via 'ok'...
cursor is still on implementation so hit F1 again... same as before...
no help... try other keywords with same results...
the results are that i get two windows... the first one says "Help
keyword FPCKeyword_implementation not found" and the only option is the
[Cancel] button... the next window then says "No help found for
C:\freepascal\laz\components\chmhelp\lhelp\httpcontentprovider.pas" (38,7)...
so why isn't this working??? what is the key step that has been left out
of the instructions??

What about trying not a keyword? What about things like "FileExists",
"TProcess", "TForm" (if the correct units are included of course).

Regards,
Sven


--

[waldo kitty]

Post by Sven Barth

Post by waldo kitty
so why isn't this working??? what is the key step that has been left out
of the instructions??

What about trying not a keyword? What about things like "FileExists",
"TProcess", "TForm" (if the correct units are included of course).

ok, so i opened my satsort project and placed the cursor on "Classes" in the
uses statement and hit F1... /that/ worked! this project doesn't have any GUI
stuffs and is not "process" oriented (AFAIK) so i didn't try those keywords (as
i called them in my previous post)...

the lhelp window is opening /two/ indicators on my w2k status bar (why??) and it
is indicating "lcl[]" which indicates that it has found the lcl.chm file... but
there is also a fcl.chm and rtl.chm in place...

i am also getting a box, labeled "Help selector" to select one of several (two
in this case) identical entries... why is this??

also basic things like 'writeln', 'write', and similar do not give any help...
but then some stuff, like 'integer' popup with a "Help selector" window as
mentioned above and one of the two RTL (ahh! found a RTL[] hit) options
(objpas.pp) talks about "redefinition of integer as 32-bit type" whereas the
other one (systemh.inc) says "a signed 16-bits integer"...

so which one is correct?

why are both being shown to me?

why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

where is the help for items like 'PadRight', 'AddChar', 'PadLeft', 'AddCharR'
and similar??

remember, "we" are coming at this as a pure newbie with some coding knowledge,
no books, and an extremely simple background in programing... yes, much of the
basic stuff really does need to be specified ;)

--

[Sven Barth]

Post by waldo kitty

Post by Sven Barth

Post by waldo kitty
so why isn't this working??? what is the key step that has been left out
of the instructions??

What about trying not a keyword? What about things like "FileExists",
"TProcess", "TForm" (if the correct units are included of course).

ok, so i opened my satsort project and placed the cursor on "Classes" in
the uses statement and hit F1... /that/ worked! this project doesn't
have any GUI stuffs and is not "process" oriented (AFAIK) so i didn't
try those keywords (as i called them in my previous post)...
the lhelp window is opening /two/ indicators on my w2k status bar
(why??) and it is indicating "lcl[]" which indicates that it has found
the lcl.chm file... but there is also a fcl.chm and rtl.chm in place...
i am also getting a box, labeled "Help selector" to select one of
several (two in this case) identical entries... why is this??
also basic things like 'writeln', 'write', and similar do not give any
help... but then some stuff, like 'integer' popup with a "Help selector"
window as mentioned above and one of the two RTL (ahh! found a RTL[]
hit) options (objpas.pp) talks about "redefinition of integer as 32-bit
type" whereas the other one (systemh.inc) says "a signed 16-bits
integer"...
so which one is correct?

Both are correct. The default size of Integer in FPC is 2 Bytes (16
Bit). Only if you use mode Delphi or ObjFPC the size is 4 Bytes (32 Bit)
and there it is indeed introduced by the ObjPas unit which is
automatically included by the compiler in these modes.

Post by waldo kitty
why are both being shown to me?
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

I don't know. At least the two ARE documented.

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

If you have the unit StrUtils included then it should work (it should be
rtl.chm).

Post by waldo kitty
remember, "we" are coming at this as a pure newbie with some coding
knowledge, no books, and an extremely simple background in programing...
yes, much of the basic stuff really does need to be specified ;)

Regards,
Sven

--

[Hans-Peter Diettrich]

Post by Sven Barth
Both are correct. The default size of Integer in FPC is 2 Bytes (16
Bit). Only if you use mode Delphi or ObjFPC the size is 4 Bytes (32 Bit)
and there it is indeed introduced by the ObjPas unit which is
automatically included by the compiler in these modes.

This is another flaw in the documentation (system), that it is not
properly configurable for the actual user environment. The RTL is almost
only documented and pre-configured for *nix (include paths...), so that
adding the Windows paths can produce strange results.

Of course cross-compilers can be installed on every machine, so that
documentation for other platforms and build modes makes sense, to some
degree. But when it leads to confusion as mentioned above, the
documentation should contain something like your above clarification.

DoDi


--

[waldo kitty]

Post by waldo kitty
but then some stuff, like 'integer' popup with a "Help selector"
window as mentioned above and one of the two RTL (ahh! found a RTL[]
hit) options (objpas.pp) talks about "redefinition of integer as 32-bit
type" whereas the other one (systemh.inc) says "a signed 16-bits
integer"...
so which one is correct?

Both are correct. The default size of Integer in FPC is 2 Bytes (16 Bit). Only
if you use mode Delphi or ObjFPC the size is 4 Bytes (32 Bit) and there it is
indeed introduced by the ObjPas unit which is automatically included by the
compiler in these modes.

yes, so i've found out... my project is (now) "{$mode objfpc}{$H+}" whereas
before it was in "turbo pascal mode" when i started it in text mode FPC... i had
to switch to using lazarus because i wanted the HasOption stuff for easier
command line processing which seems to only be available in a TApplication...
this is something else i tentatively plan to write about and ask why HasOption
and related functions are not available for all and a TApplication then uses
them... i made some rather large changes to my project which should be quite
simple and "small" :?

Post by waldo kitty
why are both being shown to me?
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

I don't know. At least the two ARE documented.

yes, they are documented but i guess that lhelp shows all entries when it cannot
determine which one is specific to the code in question... there were a few
others that showed me 5 or 6 options to choose from to see their definitions...

another thing with that is that i then had to close lhelp and hit F1 again to go
back to the choice dialog to choose another reference to read and see if it was
what i was after...

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

If you have the unit StrUtils included then it should work (it should be rtl.chm).

i do and they, themselves, work but the "latest stable" documentation pointed to
by the default F1 help page -> the wiki takes you to sourceforge where i chose
the before named file to download...

earlier i followed another path from the wiki (i believe dodi pointed me to it)
and come up with a whole different set of documentation archives that appear to
also be for the "latest stable" version :?


--

[Hans-Peter Diettrich]

Post by waldo kitty
also basic things like 'writeln', 'write', and similar do not give any
help... but then some stuff, like 'integer' popup with a "Help selector"
window as mentioned above and one of the two RTL (ahh! found a RTL[]
hit) options (objpas.pp) talks about "redefinition of integer as 32-bit
type" whereas the other one (systemh.inc) says "a signed 16-bits
integer"...
so which one is correct?

IMO "Integer" is a compiler built-in type, and thus it doesn't have a
reference to the current declaration. The same for Char and string types :-(

I already mentioned that flaw, and suggested conditional declarations:
{$IFDEF fpdocsystem}
type
integer = LongInt;
cardinal = LongWord;
...
char = WideChar;
string = UnicodeString;
...
{$ENDIF}

In my own docs I added topics for all basic types. Common to all these
workarounds is the missing correspondence to the effective declarations,
so that "a signed 16-bits integer" entry will survive ad nauseam, if
nobody happens to find and update such entries. E.g. AnsiChar is
described as an alias for Char, which in fact should read the opposite
way, and nowadays even Char=WideChar.

I found no time yet to create an overview of all the basic (built-in)
types, which would allow to update all these types in one single place,
whenever the declarations are changed in the compiler.

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are
compiler magics, for which FPDoc doesn't find a declaration in the
source code, and consequently ignores all such <element>, even if they
exist in the XML files. See above for possible workarounds.

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared. The FCL is only
documented to a small percentage, perhaps these functions reside in such
undocumented units?

Post by waldo kitty
remember, "we" are coming at this as a pure newbie with some coding
knowledge, no books, and an extremely simple background in programing...
yes, much of the basic stuff really does need to be specified ;)

Please create an according FPC bug report, if none exists yet, and hope
that somebody will update the documentation.

DoDi


--

[Sven Barth]

Post by Hans-Peter Diettrich

Post by waldo kitty
also basic things like 'writeln', 'write', and similar do not give any
help... but then some stuff, like 'integer' popup with a "Help
selector" window as mentioned above and one of the two RTL (ahh! found
a RTL[] hit) options (objpas.pp) talks about "redefinition of integer
as 32-bit type" whereas the other one (systemh.inc) says "a signed
16-bits integer"...
so which one is correct?

IMO "Integer" is a compiler built-in type, and thus it doesn't have a
reference to the current declaration. The same for Char and string types :-(

You don't like to validate your assumptions, do you?

rtl/inc/systemh.inc, line 87:

Type
{ The compiler has all integer types defined internally. Here
we define only aliases }
DWord = LongWord;
Cardinal = LongWord;
Integer = SmallInt;
UInt64 = QWord;

and rtl/objpas/objpas.pp, line 24:

{ first, in object pascal, the integer type must be redefined }
const
MaxInt = MaxLongint;
type
Integer = longint;

Post by Hans-Peter Diettrich
{$IFDEF fpdocsystem}
type
integer = LongInt;
cardinal = LongWord;
...
char = WideChar;
string = UnicodeString;
...
{$ENDIF}
In my own docs I added topics for all basic types. Common to all these
workarounds is the missing correspondence to the effective declarations,
so that "a signed 16-bits integer" entry will survive ad nauseam, if
nobody happens to find and update such entries. E.g. AnsiChar is
described as an alias for Char, which in fact should read the opposite
way, and nowadays even Char=WideChar.
I found no time yet to create an overview of all the basic (built-in)
types, which would allow to update all these types in one single place,
whenever the declarations are changed in the compiler.

For the other types this is indeed true...

Post by Hans-Peter Diettrich

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are
compiler magics, for which FPDoc doesn't find a declaration in the
source code, and consequently ignores all such <element>, even if they
exist in the XML files. See above for possible workarounds.

And again you didn't do a validation: Write and Writeln ARE documented.
I don't know currently how Michael did it, but they are in the RTL
documentation.

Post by Hans-Peter Diettrich

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared. The FCL is only
documented to a small percentage, perhaps these functions reside in such
undocumented units?

Open lHelp, go to "Search", enter "PadRight", be happy.

Alternatively in Google: "padright site:freepascal.org" (which will lead
you to the documentation as well).

They are all declared (and documented) in StrUtils which belongs to the RTL.

Post by Hans-Peter Diettrich

Post by waldo kitty
remember, "we" are coming at this as a pure newbie with some coding
knowledge, no books, and an extremely simple background in
programing... yes, much of the basic stuff really does need to be
specified ;)

Please create an according FPC bug report, if none exists yet, and hope
that somebody will update the documentation.

Please validate first by either checking the documentation by hand
(using lHelp's search) or using "IDENTIFER site:freepascal.org" on Google.

Regards,
Sven

--

[Hans-Peter Diettrich]

Post by Sven Barth

Post by Hans-Peter Diettrich
IMO "Integer" is a compiler built-in type, and thus it doesn't have a
reference to the current declaration. The same for Char and string types :-(

You don't like to validate your assumptions, do you?

You're right, the *basic* types (SmallInt...) are not documented, the
*generic* types are. That's why I added "IMO", because I was too lazy
ATM to dig deeper into the problems.

Post by Sven Barth
Type
{ The compiler has all integer types defined internally. Here
we define only aliases }
DWord = LongWord;
Cardinal = LongWord;
Integer = SmallInt;
UInt64 = QWord;

One problem is the missing declaration of "SmallInt", which makes the
"Integer" declaration useless.

Post by Sven Barth
{ first, in object pascal, the integer type must be redefined }
const
MaxInt = MaxLongint;
type
Integer = longint;

...what causes further confusion. I accept that a documentation
*generator* can not know about the later setting of the compiler mode.
An IDE might know that mode and the target platform, though. But how
should it propagate that knowledge to the help viewer? And how shall the
user know which of the duplicate entries applies?

Post by Sven Barth
Please validate first by either checking the documentation by hand
(using lHelp's search) or using "IDENTIFER site:freepascal.org" on Google.

I trust a user when he says that something doesn't work, e.g. he doesn't
get help displayed for some keyword. Next comes the search for the
reason, maybe a configuration only, or a more general problem. And there
I search in my "knowledge base" for similar items, but because human
brains work differently from computer storage, my memory may be
misadjusted, but it is not normally plain wrong.

DoDi


--

[waldo kitty]

Please validate first by either checking the documentation by hand (using
lHelp's search) or using "IDENTIFER site:freepascal.org" on Google.

I trust a user when he says that something doesn't work, e.g. he doesn't get
help displayed for some keyword. Next comes the search for the reason, maybe a
configuration only, or a more general problem. And there I search in my
"knowledge base" for similar items, but because human brains work differently
from computer storage, my memory may be misadjusted, but it is not normally
plain wrong.

this is why i gave all the steps and details that i did in my initial post... i
was quite unaware that it would show so much as it has...

i know that documenting is a rough job that only some can do... i mean, i've
written technical stuff in the past but man could not follow it... then i had a
friend who is a writer (not a coder or technical person) rewrite it and then
many people understood it much better... but the side effect was that some of
the needed technical details were lost in the "translation"...

i really do hope to actually contribute something back to the projects (FPC and
Lazarus) that is more than raising problem points and stirring the buckets... if
that means working with the documentation, i must first continue learning
(without documentation) how to work in the new (to me) environment and then
start figuring out how the documentation stuff works... i finally noticed a menu
option for FPDoc Editor in the View menu ;)


--

[Graeme Geldenhuys]

I found no time yet to create an overview of all the basic (built-in) types,
which would allow to update all these types in one single place, whenever
the declarations are changed in the compiler.

Once again you are creating unnecessary work for yourself. Michael van
Canneyt has already documented all the basic (built-in) types in the
FPC Language Reference (the chapter on Types). Can't get more clear
than that.

The difference between the size of Integer is also explained in that
documentation. See the attached image.

[Hans-Peter Diettrich]

Post by Graeme Geldenhuys
Once again you are creating unnecessary work for yourself. Michael van
Canneyt has already documented all the basic (built-in) types in the
FPC Language Reference (the chapter on Types). Can't get more clear
than that.

Sorry, I just tried "SmallInt" and could not find an according entry.
Even "types" leads to a single meaningless sentence about "unit types" :-(

That's why I added topics for all these identifiers, which then can link
to an overview or whatsoever, for more precise information.

It's like with the information in a wiki: an entry is useless if it
cannot be found.

DoDi


--

[Graeme Geldenhuys]

Sorry, I just tried "SmallInt" and could not find an according entry. Even
"types" leads to a single meaningless sentence about "unit types" :-(

See my previous screenshot of the FPC Language Reference showing the
help for the Integer type. In that screenshot you can also see the
entry for SmallInt - clearly defined size and range.
--
Regards,
  - Graeme -


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

--

[waldo kitty]

Post by Graeme Geldenhuys

I found no time yet to create an overview of all the basic (built-in) types,
which would allow to update all these types in one single place, whenever
the declarations are changed in the compiler.

Once again you are creating unnecessary work for yourself. Michael van
Canneyt has already documented all the basic (built-in) types in the
FPC Language Reference (the chapter on Types). Can't get more clear
than that.

the problem, then, must either be in the "latest stable" chm files i downloaded
OR in lhelp...

my path was this...

1. Help->Online Help

2. browser loads file:///C:/freepascal/laz/docs/index.html

3. click on "Installing CHM help in the IDE" ->
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE

4. follow the instructions (as i detailed in my first post) to download the
"latest stable Lazarus CHM help files from"
http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/

5. there i chose "Lazarus 0.9.30.2" since it has the newest date (2011 Nov 25)
http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/Lazarus%200.9.30.2/

6. there i chose "fpc-lazarus-doc-chm-0.9.30.2.tar.bz2" because it has the same
date AND it is CHM whereas the only other option in there is HTML...

7. i completed the rest of the installation and here we are...


i note that martin has added a step 6 to those wiki instructions... it has you
confirm that HelpExe is proper and also says to set HelpFilesPath to where the
chm files are... but[!!] i _have not_ changed HelpFilesPath from its blank
setting and the help /is/ working but not for all terms tested... i'm not sure,
at all, what is going on there or why it is working without that field being
filled in...

[wow, i didn't realize that my thread would cause such a stir as it has...]

--

[Andrew Haines]

Post by waldo kitty
i note that martin has added a step 6 to those wiki instructions... it
has you confirm that HelpExe is proper and also says to set
HelpFilesPath to where the chm files are... but[!!] i _have not_ changed
HelpFilesPath from its blank setting and the help /is/ working but not
for all terms tested... i'm not sure, at all, what is going on there or
why it is working without that field being filled in...

The server uses a default path if it is blank. IIRC if the path is blank
and the chm's don't exist Lazarus will tell you where to put the files.

Generally all the fileds can be blank and as long as the chm's are in
the right folder it will work.

Also last I knew you don't even have to compile lhelp since Lazarus will
build it for you.

Post by waldo kitty
[wow, i didn't realize that my thread would cause such a stir as it has...]

Yep, some stuff is exciting to the masses. :)

Clearly there are some issues (perceived or real) with access to the
documentation or quantity of the documentation or form of the documentation.

Andrew

--

[waldo kitty]

Post by Andrew Haines

Post by waldo kitty
i note that martin has added a step 6 to those wiki instructions... it
has you confirm that HelpExe is proper and also says to set
HelpFilesPath to where the chm files are... but[!!] i _have not_ changed
HelpFilesPath from its blank setting and the help /is/ working but not
for all terms tested... i'm not sure, at all, what is going on there or
why it is working without that field being filled in...

The server uses a default path if it is blank. IIRC if the path is blank
and the chm's don't exist Lazarus will tell you where to put the files.

this is good to know but it is not, AFAIKT, documented anywhere... and i cannot
confirm the "lazrus will tell you where" item :?

Post by Andrew Haines
Generally all the fileds can be blank and as long as the chm's are in
the right folder it will work.

ok... that does seem to be working... so, with that in mind, why has step6 been
added to the wiki which contains a note to ensure that the chm path for the chm
files is defined??

remember, i'm coming at this as a jack who doesn't know poop from poop... i
am/can only rely on what i'm told by the various URLs...

Post by Andrew Haines
Also last I knew you don't even have to compile lhelp since Lazarus will
build it for you.

really? under what circumstances would this be? AFAICT, i've never had lhelp
built for me from the SVN...

Post by Andrew Haines

Post by waldo kitty
[wow, i didn't realize that my thread would cause such a stir as it has...]

Yep, some stuff is exciting to the masses. :)
Clearly there are some issues (perceived or real) with access to the
documentation or quantity of the documentation or form of the documentation.

you're just being nice ;P ;)

andn actually, i am too... but i am one of (apparently very few) who
need/require /offline/ documentation to be equal to or (even better) local
documentation... in my mind, offline documentation should come first and then
(possibly!!) linking to online documentation for the equivalent or less...

in other words, *offline documentation* is a /much higher/ requirement than
online documentation... yeah, sure, online documentation might be easier but it
has many drawbacks and the major one is the blanket thinking that everyone is
online all the time...


--

[Graeme Geldenhuys]

Post by waldo kitty
but i am one of (apparently very few) who
need/require /offline/ documentation to be equal to or (even better) local
documentation... in my mind, offline documentation should come first and
then (possibly!!) linking to online documentation for the equivalent or
less...

[phone]

We seem to be the minority. :-(

For me, offline help and documentation has huge benefits over online help:

- I can get help at any time
- it doesn't cost me money every time I press F1 (yes my internet
data is limited and very expensive)
- it is much faster than online help.
- it should look better than online help
- the help viewer is a lot more rich in feature to online web browser systems.
- I can add my own notes that are always with me and accessible
- I can bookmark interesting topics

I can probably list a lot more... To address all these, I spent many
months reviewing various file formats and even considering creating a
new custom file format. At the same time I reviewed many help viewers
too, listing the pros and cons. I also looked at what features a
programmer and end-user would like to have in a help viewer - things
that actually help you, not hinder you. I also looked at how much
effort it would be to author documentation (electronic book style) and
application help. Also how easy and successful one could integrate
this with existing tools (fpdoc, Lazarus IDE, MSEide etc). This is how
I came to the decision of using INF, and developing DocView.
--
Regards,
  - Graeme -


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

--

[Lukasz Sokol]

Post by Graeme Geldenhuys

Post by waldo kitty
but i am one of (apparently very few) who
need/require /offline/ documentation to be equal to or (even better) local
documentation... in my mind, offline documentation should come first and
then (possibly!!) linking to online documentation for the equivalent or
less...

[phone]
We seem to be the minority. :-(

Make that +1 from me too.

[snip]

L.


--

[Michael Schnell]

Post by Andrew Haines
Yep, some stuff is exciting to the masses. :)

... that are lost without help ...:-) :-) :-)

-Michael

--

[Graeme Geldenhuys]

Post by Hans-Peter Diettrich

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are
compiler magics, for which FPDoc doesn't find a declaration in the source

They ARE defined in the System unit and already documented. It shows
up fine here (INF & PDF help).

Post by Hans-Peter Diettrich

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared.

Doesn't LHelp have a search function? Anyway, I found them documented
in the RTL in StrUtils unit.

Post by Hans-Peter Diettrich
Please create an according FPC bug report, if none exists yet, and hope that
somebody will update the documentation.

No, maybe use a help viewer that actually works. Then if it is still
not found or documented, report as a feature request or bug report.
--
Regards,
  - Graeme -


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

--

[Sven Barth]

Post by Graeme Geldenhuys

Post by Hans-Peter Diettrich

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are
compiler magics, for which FPDoc doesn't find a declaration in the source

They ARE defined in the System unit and already documented. It shows
up fine here (INF& PDF help).

They are not defined in the System unit (they are compiler intrinsics),
but they are indeed documented.

Post by Graeme Geldenhuys

Post by Hans-Peter Diettrich

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared.

Doesn't LHelp have a search function? Anyway, I found them documented
in the RTL in StrUtils unit.

Yes, LHelp does have a search function (though I don't know what sorting
it uses...)

Post by Graeme Geldenhuys

Post by Hans-Peter Diettrich
Please create an according FPC bug report, if none exists yet, and hope that
somebody will update the documentation.

No, maybe use a help viewer that actually works. Then if it is still
not found or documented, report as a feature request or bug report.

1.) This seems to be a problem of the IDE or the integration package
which can't find Writeln, etc. because they don't exist in the source.
2.) Verification for existance can also be done by searching manually in
the documentation or using "IDENTIFIER site:freepascal.org" in Google.

Regards,
Sven

--

[Marco van de Voort]

Post by Sven Barth

Post by Graeme Geldenhuys

Post by Hans-Peter Diettrich
Please create an according FPC bug report, if none exists yet, and hope that
somebody will update the documentation.

No, maybe use a help viewer that actually works. Then if it is still
not found or documented, report as a feature request or bug report.

1.) This seems to be a problem of the IDE or the integration package
which can't find Writeln, etc. because they don't exist in the source.
2.) Verification for existance can also be done by searching manually in
the documentation or using "IDENTIFIER site:freepascal.org" in Google.

I keep a textmode IDE with the CHMs installed as a quick doublecheck if it
is lazarus or the CHMs.

If that fails, I use chmls to extract the CHM, and inspect the content
manually.

--

[Michael Schnell]

Post by Hans-Peter Diettrich

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared.

IMHO, the help viewer should do this for you and show any appropriate
occurrence in the any of the docs.

-Michael

--

[m***@wisa.be]

Post by Hans-Peter Diettrich

Post by waldo kitty
also basic things like 'writeln', 'write', and similar do not give any
help... but then some stuff, like 'integer' popup with a "Help selector"
window as mentioned above and one of the two RTL (ahh! found a RTL[] hit)
options (objpas.pp) talks about "redefinition of integer as 32-bit type"
whereas the other one (systemh.inc) says "a signed 16-bits integer"...
so which one is correct?

IMO "Integer" is a compiler built-in type, and thus it doesn't have a
reference to the current declaration. The same for Char and string types :-(
{$IFDEF fpdocsystem}
type
integer = LongInt;
cardinal = LongWord;
...
char = WideChar;
string = UnicodeString;
...
{$ENDIF}

This is on my todo list.

Post by Hans-Peter Diettrich

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are
compiler magics, for which FPDoc doesn't find a declaration in the source
code, and consequently ignores all such <element>, even if they exist in the
XML files. See above for possible workarounds.

This is not correct. It has been documented for 12 years at least.
See my direct answer to the orginal post.

Post by Hans-Peter Diettrich

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft',
'AddCharR' and similar??

I just can't find in which units these are declared. The FCL is only
documented to a small percentage, perhaps these functions reside in such
undocumented units?

Post by waldo kitty
remember, "we" are coming at this as a pure newbie with some coding
knowledge, no books, and an extremely simple background in programing...
yes, much of the basic stuff really does need to be specified ;)

Please create an according FPC bug report, if none exists yet, and hope that
somebody will update the documentation.

It is documented since years, so no need for a bugreport.

Michael.

--

[waldo kitty]

Post by waldo kitty
also basic things like 'writeln', 'write', and similar do not give any help...
but then some stuff, like 'integer' popup with a "Help selector" window as
mentioned above and one of the two RTL (ahh! found a RTL[] hit) options
(objpas.pp) talks about "redefinition of integer as 32-bit type" whereas the
other one (systemh.inc) says "a signed 16-bits integer"...
so which one is correct?

IMO "Integer" is a compiler built-in type, and thus it doesn't have a reference
to the current declaration. The same for Char and string types :-(

it was but one of several i assumed would be documented by default :(

{$IFDEF fpdocsystem}
type
integer = LongInt;
cardinal = LongWord;
...
char = WideChar;
string = UnicodeString;
...
{$ENDIF}
In my own docs I added topics for all basic types. Common to all these
workarounds is the missing correspondence to the effective declarations, so that
"a signed 16-bits integer" entry will survive ad nauseam, if nobody happens to
find and update such entries. E.g. AnsiChar is described as an alias for Char,
which in fact should read the opposite way, and nowadays even Char=WideChar.

yeah, i've run into some problems in a tool that i'm trying to complete with
some of this type of stuff... i actually had to set sw_integer for some types
that should have worked with integer... i /just/ found out what sw_integer is
(objects unit - alias for longint)... but that brings me to another problem i
think i may have run into but i gotta find the posts that pointed me in that
direction and it has been a week or two :?

I found no time yet to create an overview of all the basic (built-in) types,
which would allow to update all these types in one single place, whenever the
declarations are changed in the compiler.

ahhh... that might be a bit of a mess?

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Thanks, I didn't realize that yet. It's for the same reason: these are compiler
magics, for which FPDoc doesn't find a declaration in the source code, and
consequently ignores all such <element>, even if they exist in the XML files.
See above for possible workarounds.

ahh... i found them quite quickly by hitting all routines and 'keywords' that
/i/ didn't write in my project ;) for example, i know that i have not written
any help (yet) for my TLEEpoch procedures and functions so testing docs by
trying to find them won't work but a lot of other code i didn't write as it is
mostly library code which i would expect to have been documented after all this
time and these discussions...

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft', 'AddCharR'
and similar??

I just can't find in which units these are declared. The FCL is only documented
to a small percentage, perhaps these functions reside in such undocumented units?

these are in strutils... i found them by using uncle google which is quite the
laugh because all of this is about *offline* help so these things can be found

Post by waldo kitty
remember, "we" are coming at this as a pure newbie with some coding knowledge,
no books, and an extremely simple background in programing... yes, much of the
basic stuff really does need to be specified ;)

Please create an according FPC bug report, if none exists yet, and hope that
somebody will update the documentation.

i may figure out where and how to start but i've already got too much going on
now :(

--

[m***@wisa.be]

Post by waldo kitty

Post by Sven Barth

Post by waldo kitty
so why isn't this working??? what is the key step that has been left out
of the instructions??

What about trying not a keyword? What about things like "FileExists",
"TProcess", "TForm" (if the correct units are included of course).

also basic things like 'writeln', 'write', and similar do not give any
help... but then some stuff, like 'integer' popup with a "Help selector"
window as mentioned above and one of the two RTL (ahh! found a RTL[] hit)
options (objpas.pp) talks about "redefinition of integer as 32-bit type"
whereas the other one (systemh.inc) says "a signed 16-bits integer"...
so which one is correct?
why are both being shown to me?
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Where do you get that from ? It is documented.

See

http://www.freepascal.org/docs-html/rtl/system/index-5.html

Select 'Writeln'

Which leads you to

http://www.freepascal.org/docs-html/rtl/system/writeln.html

etc.

Post by waldo kitty
where is the help for items like 'PadRight', 'AddChar', 'PadLeft', 'AddCharR'
and similar??

http://www.freepascal.org/docs-html/rtl/strutils/index-5.html

Of course, you need to know in which unit an identifier is.

To overcome this problem, a search engine for the docs is in the making.
(in fact, it's finished, we just need to deploy it properly)

Michael.

--

[waldo kitty]

Post by m***@wisa.be

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Where do you get that from ? It is documented.
See
http://www.freepascal.org/docs-html/rtl/system/index-5.html

but that's /online/... this whole mess is about offline help :?

yes, i use that online stuff when i can but there are times when being online is
simply not an option... you can't get online when you are 30 miles from nowhere
in the middle of the woods at a river/lake using a generator or vehicle battery
to power your laptop while waiting on the fish to bite ;)

(that /is/ a valid situation in my world)


--

[Everton Vieira]

Post by waldo kitty

Post by m***@wisa.be

Post by waldo kitty
why does basic stuff, eg: 'write' and 'writeln' not have any help at all?

Where do you get that from ? It is documented.
See
http://www.freepascal.org/docs-html/rtl/system/index-5.html

but that's /online/... this whole mess is about offline help :?
yes, i use that online stuff when i can but there are times when being online is simply not an option... you can't get online when you are 30 miles from nowhere in the middle of the woods at a river/lake using a generator or vehicle battery to power your laptop while waiting on the fish to bite ;)
(that /is/ a valid situation in my world)

what a world bro!

Post by waldo kitty
--
_______________________________________________
Lazarus mailing list
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

--

[Graeme Geldenhuys]

Post by waldo kitty
(that /is/ a valid situation in my world)

Your world sounds awesome! :)
--
Regards,
  - Graeme -


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

--

[f***@gmail.com]

so why isn't this working??? what is the key step that has been left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl. Nothing is said about keywords as they are not part of those libraries but of the language itself. It is for types, functions, classes, units, etc. Not keywords. I don't know what is required for keywords help. I don't even know if there is a chm for that. The wiki has some info on keywords.

Felipe

--

[Hans-Peter Diettrich]

Post by f***@gmail.com

Post by waldo kitty
so why isn't this working??? what is the key step that has been
left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl.

Download all the CHM, and keyword help works (here, Win7).
I got ref, prog, user and toc CHMs, too.

DoDi


--

[waldo kitty]

Post by Hans-Peter Diettrich

Post by f***@gmail.com

Post by waldo kitty
so why isn't this working??? what is the key step that has been
left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl.

Download all the CHM, and keyword help works (here, Win7).
I got ref, prog, user and toc CHMs, too.

hunh? there are only 3 in the ~16Meg fpc-lazarus-doc-chm-0.9.30.2.tar.bz2 file i
pulled off of sourceforge as directed by the wiki page </scratching head>


--

[Marco van de Voort]

Post by waldo kitty

Post by Hans-Peter Diettrich
I got ref, prog, user and toc CHMs, too.

hunh? there are only 3 in the ~16Meg fpc-lazarus-doc-chm-0.9.30.2.tar.bz2 file i
pulled off of sourceforge as directed by the wiki page </scratching head>

Check the FPC documentation download page for e.g. 2.6.0

--

[Hans-Peter Diettrich]

Post by waldo kitty

Post by Hans-Peter Diettrich
Download all the CHM, and keyword help works (here, Win7).
I got ref, prog, user and toc CHMs, too.

hunh? there are only 3 in the ~16Meg
fpc-lazarus-doc-chm-0.9.30.2.tar.bz2 file i pulled off of sourceforge as
directed by the wiki page </scratching head>

See
http://wiki.lazarus.freepascal.org/Lazarus_Documentation#Free_Pascal_Compiler_Documentation
for a list of the FPC related documentation. There exists some confusion
in the Wiki content, links and download sites. Good luck :-)

DoDi


--

[waldo kitty]

Post by Hans-Peter Diettrich

Post by waldo kitty

Post by Hans-Peter Diettrich
Download all the CHM, and keyword help works (here, Win7).
I got ref, prog, user and toc CHMs, too.

hunh? there are only 3 in the ~16Meg fpc-lazarus-doc-chm-0.9.30.2.tar.bz2 file
i pulled off of sourceforge as directed by the wiki page </scratching head>

See
http://wiki.lazarus.freepascal.org/Lazarus_Documentation#Free_Pascal_Compiler_Documentation
for a list of the FPC related documentation. There exists some confusion in the
Wiki content, links and download sites. Good luck :-)

yeah, i've waded thru that morass numerous times :? :(

--

[waldo kitty]

Post by f***@gmail.com

so why isn't this working??? what is the key step that has been left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl. Nothing is said about keywords

i used the term 'keyword' to cover basic pascal "verbs" or whatever the proper
verbiage is for them... i also see/use this term to cover all library items and
am surprised that 'writeln' is not included in the RTL docs... apparently my
understanding of 'RTL' is not what others think it is :?

Post by f***@gmail.com
as they are not part of those libraries but of the language itself.

so what chm file(s) would the language 'keywords' be defined in??

Post by f***@gmail.com
It is for types, functions, classes, units, etc. Not keywords.

i am, obviously(?), confusing the term 'keyword' :(

Post by f***@gmail.com
I don't know what is required for keywords help. I don't even know if there is a chm for that. The wiki has some info on keywords.

ummhumm :?


--

[Graeme Geldenhuys]

Post by waldo kitty
i used the term 'keyword' to cover basic pascal "verbs" or whatever the
proper verbiage is for them... i also see/use this term to cover all library
items and am surprised that 'writeln' is not included in the RTL docs...

Those "keywords" are coverer in the RTL documentation. I see it in
DocView when I press F1, so there must be yet another bug in the CHM
files or viewer or CHM IDE integration.

For the writeln() "keyword" as you put it, DocView took me to "RTL ->
Reference for unit 'System' > Procedures and Functions > Writeln"
--
Regards,
  - Graeme -


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

--

[Marco van de Voort]

Post by Graeme Geldenhuys

Post by waldo kitty
i used the term 'keyword' to cover basic pascal "verbs" or whatever the
proper verbiage is for them... i also see/use this term to cover all library
items and am surprised that 'writeln' is not included in the RTL docs...

Those "keywords" are coverer in the RTL documentation. I see it in
DocView when I press F1, so there must be yet another bug in the CHM
files or viewer or CHM IDE integration.
For the writeln() "keyword" as you put it, DocView took me to "RTL ->
Reference for unit 'System' > Procedures and Functions > Writeln"

That's a built in, not a keyword.

The keywords are in ref.chm ( stuff like repeat and until).

--

[Sven Barth]

Post by Graeme Geldenhuys

Post by waldo kitty
i used the term 'keyword' to cover basic pascal "verbs" or whatever the
proper verbiage is for them... i also see/use this term to cover all library
items and am surprised that 'writeln' is not included in the RTL docs...

Those "keywords" are coverer in the RTL documentation. I see it in
DocView when I press F1, so there must be yet another bug in the CHM
files or viewer or CHM IDE integration.
For the writeln() "keyword" as you put it, DocView took me to "RTL ->
Reference for unit 'System'> Procedures and Functions> Writeln"

It seems to be a problem of the IDE or the integration package, because
searching for Writeln in the search tab of lHelp works (Note: Other
identifiers that are not physically present in the system unit are not
shown either, like "Boolean". But e.g. PtrInt exists)

Regards,
Sven

--

[Graeme Geldenhuys]

Post by Sven Barth
searching for Writeln in the search tab of lHelp works (Note: Other
identifiers that are not physically present in the system unit are not shown
either, like "Boolean". But e.g. PtrInt exists)

In my setup, DocView is told to automatically open up 4 help files,
when I press F1. It loads the FPC Language Reference, RTL, FCL and
fpGUI class docs. So Boolean will be found in the FPC Language
Reference, PtrInt in the RTL etc. No need for me to open various help
files manually.
--
Regards,
  - Graeme -


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

--

[Sven Barth]

Post by Graeme Geldenhuys

Post by Sven Barth
searching for Writeln in the search tab of lHelp works (Note: Other
identifiers that are not physically present in the system unit are not shown
either, like "Boolean". But e.g. PtrInt exists)

In my setup, DocView is told to automatically open up 4 help files,
when I press F1. It loads the FPC Language Reference, RTL, FCL and
fpGUI class docs. So Boolean will be found in the FPC Language
Reference, PtrInt in the RTL etc. No need for me to open various help
files manually.

Then it is indeed a problem of either the IDE or the integration
package, because I have the ref.chm available as well. It might be that
the IDE tries to find the identifier, but fails, because they are
intrinsics (the help system does more checking and resolving than your
external tool).

Regards,
Sven

--

[waldo kitty]

Post by Sven Barth

Post by Graeme Geldenhuys

Post by waldo kitty
i used the term 'keyword' to cover basic pascal "verbs" or whatever the
proper verbiage is for them... i also see/use this term to cover all library
items and am surprised that 'writeln' is not included in the RTL docs...

Those "keywords" are coverer in the RTL documentation. I see it in
DocView when I press F1, so there must be yet another bug in the CHM
files or viewer or CHM IDE integration.
For the writeln() "keyword" as you put it, DocView took me to "RTL ->
Reference for unit 'System'> Procedures and Functions> Writeln"

It seems to be a problem of the IDE or the integration package, because
searching for Writeln in the search tab of lHelp works

interesting... it doesn't make sense (yet) but it is interesting...

Post by Sven Barth
(Note: Other identifiers that are not physically present in the system unit
are not shown either, like "Boolean". But e.g. PtrInt exists)

@graeme: does docview work with chm files? i haven't looked at it, yet, if if
does, i'm curious if it will find things that lhelp doesn't in the same chm
files when invoked by placing the cursor on a {dang, what terms to use??} word
in the IDE and hitting F1 (or CTRL-F1 for docview as an external app)...

--

[Graeme Geldenhuys]

Post by waldo kitty
@graeme: does docview work with chm files? i haven't looked at it, yet, if
if does, i'm curious if it will find things that lhelp doesn't in the same
chm files when invoked by placing the cursor on a {dang, what terms to
use??} word in the IDE and hitting F1 (or CTRL-F1 for docview as an external
app)...

No, DocView uses INF help files. They are much more optimised for size
and speed - compared to CHM (which is basically just a zip file of
HTML pages).

http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/

A 1.7MB download for the FPC Language Reference, RTL, FCL and fpGUI
class docs. The LCL help is a separate 1.4MB download.

DocView has an advanced search algorithm too. Not only does in search
for the exact term, but also similar terms, and has a rating system to
better ordering of results etc.


What are INF files?
INF files was designed and created by IBM. It was the help file format
for OS/2. It can serve as a "digital book" or as a help file for
applications. INF files scale very well. The larger the content, the
more optimised the INF file becomes. The IBM designed help viewer for
OS/2 and Windows sucked though. It had a terrible interface - DocView
solves this.
--
Regards,
  - Graeme -


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

--

[waldo kitty]

Post by Graeme Geldenhuys

Post by waldo kitty
@graeme: does docview work with chm files? i haven't looked at it, yet, if
if does, i'm curious if it will find things that lhelp doesn't in the same
chm files when invoked by placing the cursor on a {dang, what terms to
use??} word in the IDE and hitting F1 (or CTRL-F1 for docview as an external
app)...

No, DocView uses INF help files.

i kinda thought this would be the case with all the reading i've been doing on
everything related to the help laz/fpc system(s)... and since i /still/ run OS/2
Warp 3 Connect on my main front line system, this type of stuff can be very
important... especially if i develop an app on win32 and also need to compile
the code on OS2 where it is intended to be anyway...

Post by Graeme Geldenhuys
They are much more optimised for size and speed - compared to CHM (which is
basically just a zip file of HTML pages).

actually, i do remember this difference being brought up years ago when M$ "took
their toys and stomped off home"... size is also a major factor in much of what
i deal with... even moreso since much of it deals with older hardware with
/maybe/ 256Meg of RAM... lucky to see 512Meg...


--

[Marco van de Voort]

Post by f***@gmail.com

so why isn't this working??? what is the key step that has been left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl. Nothing is
said about keywords as they are not part of those libraries but of the
language itself.

True.

Post by f***@gmail.com
It is for types, functions, classes, units, etc. Not
keywords. I don't know what is required for keywords help.

Putting ref.chm in the same directory. The keywords are in there for nearly
two years.

But iirc only .31 supports it, not .30. (and it is one of the things that
would be nice to backport to a future stable release)

The textmode IDE has supported it from the start.

--

[Sven Barth]

Post by Marco van de Voort

Post by f***@gmail.com

so why isn't this working??? what is the key step that has been left out of the instructions??

Read the wiki section title. Documentation for RTL, fcl, lcl. Nothing is
said about keywords as they are not part of those libraries but of the
language itself.

True.

Post by f***@gmail.com
It is for types, functions, classes, units, etc. Not
keywords. I don't know what is required for keywords help.

Putting ref.chm in the same directory. The keywords are in there for nearly
two years.
But iirc only .31 supports it, not .30. (and it is one of the things that
would be nice to backport to a future stable release)

As the next Lazarus release seems to be based on 0.9.31 (0.99) this does
not seem to be a problem ;)

Regards,
Sven


--

[Marco van de Voort]

Post by Sven Barth

Post by Marco van de Voort
two years.
But iirc only .31 supports it, not .30. (and it is one of the things that
would be nice to backport to a future stable release)

As the next Lazarus release seems to be based on 0.9.31 (0.99) this does
not seem to be a problem ;)

The last bit I heard was that a 30.3 would be inserted if the 0.99 stuff
took too long, and end of februari was considered as the decision point to
evaluate if 0.99 was "close".

--

[Sven Barth]

Post by Marco van de Voort

Post by Sven Barth

Post by Marco van de Voort
two years.
But iirc only .31 supports it, not .30. (and it is one of the things that
would be nice to backport to a future stable release)

As the next Lazarus release seems to be based on 0.9.31 (0.99) this does
not seem to be a problem ;)

The last bit I heard was that a 30.3 would be inserted if the 0.99 stuff
took too long, and end of februari was considered as the decision point to
evaluate if 0.99 was "close".

Ok, then you heard more than me ^^

Regards,
Sven


--

[waldo kitty]

Post by Marco van de Voort
Putting ref.chm in the same directory. The keywords are in there for nearly
two years.
But iirc only .31 supports it, not .30. (and it is one of the things that
would be nice to backport to a future stable release)

As the next Lazarus release seems to be based on 0.9.31 (0.99) this does not
seem to be a problem ;)

FWIW: i am using lazarus 0.9.31 from SVN (updated every few days) but i am still
using FPC 2.4.5 (also from SVN)... i'm not sure of the FPC SVN revision... it is
not shown in the lazarus Help->About dialog... only the lazarus SVN revision is
shown... i /think/ my FPC is r17628, though...

FWIW2: i haven't updated this and my other main dev box to FPC 2.6.0 because, as
has happened in the past, i've had to wipe everything and start all over pulling
from the SVN and then bootstrapping up from there... it is easy to do lazarus
but updating FPC and then trying to make it and then laz always break some how
for me :(


--

[Graeme Geldenhuys]

Post by waldo kitty
5. extracted three chm files to my freepascal/laz/docs/html
placed the cursor on a pascal keyword (ie: implementation in the currently
opened file from when i opened the lhelp.lpi), pressed F1 and... no help :(

Funny that, I had the exact same problem. You missed out step 6.

[quote]

6) Ignore the previous five steps, and rather go to the following URL that
explains how to install DocView via the "External Tools" menu option.

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

[/quote]


See attached image. Cursor was over "implementation" keyword when the
F1 key was pressed.


;-)

[Martin]

Post by waldo kitty
ok, i decided to go back and retry this all over again... i'm
following the instructions in the wiki as linked to by the default
Help->Online Help page...
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE
[quote]
Installing CHM Help for The RTL, FCL and LCL in the Lazarus IDE
If you are using Lazarus from Subversion
1) Make sure that the package chmhelppkg is intalled. See the menu
Package->Install Packages. This package is installed by default in the
"bigide" so most users should already have it installed.
2) Open the project lazarus/components/chmhelp/lhelp/lhelp.lpi
3) Build this project
4) Download the latest stable Lazarus CHM help files from
http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/
5) Copy all CHM files to lazarus/docs/html
Now context sensitive help using F1 should already be working.

....

Post by waldo kitty
so why isn't this working??? what is the key step that has been left
out of the instructions??

I added to the wiki

6) Go to the Environment Options, tab "Help Options' and select the "CHM
Help Viewer". Check it's properties:
:"HelpExe" should be the lhelp you did just build
:"HelpFilesPath" should be, where you did put the chm files


which I found I needed to do, since my Lazarus was not in it's default
dir either

--

[Bernd]

Somewhere else (on this list or in the forum) I have seen the define
UseCHMHelp being mentioned (could have been an old post already). How
is this related to the instructions mentioned at the beginning of this
thread?

I can remember I had played around with CHM help a year ago but
deactivated it soon again and only recently by sheer coincidence I
found this define mentioned somewhere and just out of curiosity I
added it to my "build lazarus"-settings, rebuilt Lazarus and
immediately the CHM help was active and working again (at least I did
not change anything else and I'm 75% sure it was somehow deactivated
before).

--

[waldo kitty]

Post by Martin

Post by waldo kitty
so why isn't this working??? what is the key step that has been left out of
the instructions??

I added to the wiki
6) Go to the Environment Options,

i see this as "IDE Options" dialog

Post by Martin
tab "Help Options'

i do not have any tabs across the top or side of this dialog... i do have some
sort of tree like thing on the left, though... help options is where i was
talking about in my earlier post... and i called the 'path' i was looking at by
the wrong name... what i was looking at and altered is the 'FPC Doc HTML Path'
according to the bold type above the field i was looking at...

Post by Martin
and select the "CHM Help Viewer".

go that ;)

Post by Martin
:"HelpExe" should be the lhelp you did just build

yes...

Post by Martin
:"HelpFilesPath" should be, where you did put the chm files

this is blank but now that i have selected some other 'keywords' (apparently i'm
using that term incorrectly) i am getting some help stuff popping up...

Post by Martin
which I found I needed to do, since my Lazarus was not in it's default dir either

AIR, we are living in the same directory tree since we (IIRC) are using the same
wiki article on birthing FPC/Lazarus clean from the SVN and bootstrapping it up
from there...


--

[Michael Schnell]

Post by waldo kitty
placed the cursor on a pascal keyword (ie: implementation in the
currently opened file from when i opened the lhelp.lpi), pressed F1
and... no help :(

To get context help for pascal language keywords, you need to install a
combined chm file that (in addition to the standard LCL) help includes
FPC language help (and hopefully help on help, IDE help, RTL help, you
name it.

I don't know if such a file even exist and/or (how) it is possible to
build it from the svn sources.

(Se the lots of recent discussions on the help system that pointed out
the benefits of DocView.)

-Michael


--

[Hans-Peter Diettrich]

Post by Michael Schnell
To get context help for pascal language keywords, you need to install a
combined chm file

Nope. Simply download the additional CHM files, and it works as expected.

Post by Michael Schnell
(Se the lots of recent discussions on the help system that pointed out
the benefits of DocView.)

I don't see a reason or need for another (incompatible) help system.
Learn to use the existing one first, before praising other systems.

DoDi


--

[Graeme Geldenhuys]

I don't see a reason or need for another (incompatible) help system. Learn
to use the existing one first, before praising other systems.

Please explain or elaborate on "incompatible help system"? I do not
understand your comment or what you are referring too.
--
Regards,
  - Graeme -


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

--

[Michael Schnell]

Post by Hans-Peter Diettrich
Nope. Simply download the additional CHM files, and it works as expected.

I once asked how the CHM help can be configured to search across
multiple files. I never got a positive answer. But things might be
improved by now.

Post by Hans-Peter Diettrich
Learn to use the existing one first, before praising other systems.

The current discussions pointed out so many drawbacks regarding the CHM
help, that I was not eager to try it (while DocvView does work rather
nicely for me).

-Michael

--

[Marco van de Voort]

Post by Michael Schnell

Post by Hans-Peter Diettrich
Nope. Simply download the additional CHM files, and it works as expected.

I once asked how the CHM help can be configured to search across
multiple files.

There is no "CHM help". There is Lazarus help, which loads the indexes from
individual CHMs, and a viewer for single CHMs.

IOW, afaik such searches are part of lazarus, not the viewer.

Your judging CHM on Docview based assumptions. Docviewer holds an own
helpfile registration, lhelp not, it is lazarus' slave.

Post by Michael Schnell
I never got a positive answer.

That's because the question is vague and unclear.

Post by Michael Schnell

Post by Hans-Peter Diettrich
Learn to use the existing one first, before praising other systems.

The current discussions pointed out so many drawbacks regarding the CHM
help, that I was not eager to try it (while DocvView does work rather
nicely for me).

Those are mostly noise from Hans and Graeme, not defects per se. Sometimes
they are minor implementation flaws presented as fundamental defects.

--

[Felipe Monteiro de Carvalho]

Post by Marco van de Voort
There is no "CHM help". There is Lazarus help, which loads the indexes from
individual CHMs, and a viewer for single CHMs.

Correction: LHelp can view and handle multiple CHM files at the same
time and will keep multiple CHMs loaded.

[Michael Schnell]

There is no "CHM help". ...

Sorry for being vague. I learned that the help viewer for the Lazarus
IDE is installed as a package. What I meant is the "installable help
viewer that works on CHM files".

That's because the question is vague and unclear.

Sorry for that. I did not notice.

Those are mostly noise from Hans and Graeme,

What about Waldo, to whom my first answer in this thread was sent ?

not defects per se. Sometimes
they are minor implementation flaws presented as fundamental defects.

That is why I am waiting for somebody claiming that an updated version
is available that is supposed to be appropriately dummy-friendly.

I'll be happy to test that one.

-Michael

--

[Felipe Monteiro de Carvalho]

uhh... reserved words are not keywords... at least not in my 30+ year old
coding book of terms... and definitely not in my ~50 years of life
experience :?
placed the cursor on a >>>pascal keyword (ie: implementation<<< in the currently opened file from when i opened the lhelp.lpi), pressed F1 and... no help :(

From that I understood that you placed the cursor in the
"implementation" reserved word and pressed F1 and called it a keyword.

--
Felipe Monteiro de Carvalho

--

[waldo kitty]

Post by Felipe Monteiro de Carvalho

uhh... reserved words are not keywords... at least not in my 30+ year old
coding book of terms... and definitely not in my ~50 years of life
experience :?
placed the cursor on a>>>pascal keyword (ie: implementation<<< in the currently opened file from when i opened the lhelp.lpi), pressed F1 and... no help :(

From that I understood that you placed the cursor in the
"implementation" reserved word and pressed F1 and called it a keyword.

yes, i did place the cursor on the word "implementation"... yes, i called it a
"keyword" because it is a keyword into the index of the help document structure...

my apologies for any confusion... situations like this will, however, happen
because there are only enough words to describe something... in the above,
"implementation" is a reserved word in the language but when searching
documentation, it is an/the index key word...

we need to figure what to call these things so that we can avoid this confusion
in the future... especially in this discussion... i've already seen numerous
other similar confusion incidents in this topic, too :?

--

[Hans-Peter Diettrich]

Post by waldo kitty

Post by Felipe Monteiro de Carvalho
From that I understood that you placed the cursor in the
"implementation" reserved word and pressed F1 and called it a keyword.

yes, i did place the cursor on the word "implementation"... yes, i
called it a "keyword" because it is a keyword into the index of the help
document structure...
my apologies for any confusion...

I feel no need for apologies here. The *help* system is based on
*keywords* (see TControl.HelpKeyword). Context sensitive (F1) help is
based on the *word* under the mouse cursor. The language specifies e.g.
*reserved* words, but no specific keywords.

The different handling, required for e.g. language words, source code
identifiers or dialog window elements, must not be known to the help
user; it doesn't help him. It's sufficient to point the user to the
ref.chm file, whose absence is the most probable reason when the
documentation of "implementation" is not found.

DoDi


--

[waldo kitty]

Post by waldo kitty

Post by Felipe Monteiro de Carvalho
From that I understood that you placed the cursor in the
"implementation" reserved word and pressed F1 and called it a keyword.

yes, i did place the cursor on the word "implementation"... yes, i called it a
"keyword" because it is a keyword into the index of the help document structure...
my apologies for any confusion...

I feel no need for apologies here. The *help* system is based on *keywords* (see
TControl.HelpKeyword). Context sensitive (F1) help is based on the *word* under
the mouse cursor. The language specifies e.g. *reserved* words, but no specific
keywords.

thank you, dodi... you explained it much better than i... it can be confusing,
though, when one is thinking of one thing when they should be thinking of
another... in our context of the help system, "write", "writeln",
"implementation", "sysutils", "objects", "integer" and the like are all
keywords... their individual status in the language is moot... we do agree on
that :)

The different handling, required for e.g. language words, source code
identifiers or dialog window elements, must not be known to the help user; it
doesn't help him. It's sufficient to point the user to the ref.chm file, whose
absence is the most probable reason when the documentation of "implementation"
is not found.

i do not have this chm file... i downloaded exactly what i was told to
download... seems that either the instructions or the file are incomplete :?


--

[Andrew Haines]

Post by Marco van de Voort

Post by Michael Schnell

Post by Hans-Peter Diettrich
Nope. Simply download the additional CHM files, and it works as expected.

I once asked how the CHM help can be configured to search across
multiple files.

There is no "CHM help". There is Lazarus help, which loads the indexes from
individual CHMs, and a viewer for single CHMs.
IOW, afaik such searches are part of lazarus, not the viewer.

When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one. If there is only one result or when
you select one it then asks the helpviewer to show that topic. It does
not use the help viewer to search the help.

LHelp can have multiple chm files open and will search them all from the
LHelp search pane.

Regards,

Andrew

--

[Mattias Gaertner]

Post by Andrew Haines

Post by Marco van de Voort

Post by Michael Schnell

Post by Hans-Peter Diettrich
Nope. Simply download the additional CHM files, and it works as expected.

I once asked how the CHM help can be configured to search across
multiple files.

There is no "CHM help". There is Lazarus help, which loads the indexes from
individual CHMs, and a viewer for single CHMs.
IOW, afaik such searches are part of lazarus, not the viewer.

When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one. If there is only one result or when
you select one it then asks the helpviewer to show that topic. It does
not use the help viewer to search the help.
LHelp can have multiple chm files open and will search them all from the
LHelp search pane.

AFAIK there is a two-way communication between the IDE and lhelp.
Just an idea:
The chmhelppkg can use this to perform a search in lhelp. Then F1 would
show lhelp with the search results.

Mattias

[Andrew Haines]

Post by Mattias Gaertner

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one. If there is only one result or when
you select one it then asks the helpviewer to show that topic. It does
not use the help viewer to search the help.
LHelp can have multiple chm files open and will search them all from the
LHelp search pane.

AFAIK there is a two-way communication between the IDE and lhelp.
The chmhelppkg can use this to perform a search in lhelp. Then F1 would
show lhelp with the search results.

There is some communication now yes but I am working on a 2 way ipc unit
now to make this more efficient, and plan to add the ability for lhelp
to be able to do searches through ipc.

The current IPC lhelp has is too primitive and can block lazarus while
it loads the a TOC which although fast is noticable.

The 2 way IPC unit is done and I am adding the lhelp layer to it now.

Andrew

--

[Graeme Geldenhuys]

The chmhelppkg can use this to perform a search in lhelp. Then F1 would show
lhelp with the search results.

In that case, why bother with the chmhelppkg in the first place? What
you are describing, is exactly what I do with the "docview integration
via External Tools menu item". I use the current token macro from the
IDE, and pass that to DocView as a search parameter, which then does
the search across all INF files.

From all the discussions in this mailing list, my solution seems much
more accurate (in terms of search results) than letting the IDE do the
searching. This was my experience ages ago too - hence I never
bothered created a "docview help package for lazarus".
--
Regards,
  - Graeme -


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

--

[Mattias Gaertner]

On Thu, 16 Feb 2012 00:34:55 +0200

Post by Graeme Geldenhuys

The chmhelppkg can use this to perform a search in lhelp. Then F1 would show
lhelp with the search results.

In that case, why bother with the chmhelppkg in the first place? What
you are describing, is exactly what I do with the "docview integration
via External Tools menu item". I use the current token macro from the
IDE, and pass that to DocView as a search parameter, which then does
the search across all INF files.

Maybe you missed my mail in this storm of threads.

The token is only one word. It misses the context. It can not
distinguish between a TStrings.LoadFromFile and a
TMemoryStream.LoadFromFile. Or think about the "Create". Only
if the search for the specific item fails only then should the help use
a simple word search.

Post by Graeme Geldenhuys
From all the discussions in this mailing list, my solution seems much
more accurate (in terms of search results) than letting the IDE do the
searching. This was my experience ages ago too - hence I never
bothered created a "docview help package for lazarus".

The IDE only provides extra context information. How the help
uses this information is completely up to the help.
DocView ignores it completely, chmhelppkg is too picky.
I think the best solution is something in between.


Mattias

--

[Michael Schnell]

Post by Mattias Gaertner
The token is only one word. It misses the context. It can not
distinguish between a TStrings.LoadFromFile and a
TMemoryStream.LoadFromFile. Or think about the "Create". Only if the
search for the specific item fails only then should the help use a
simple word search.

Yep. But that does not mean that the IDE needs to do some search on it's
own. It just could pass the appropriate info though the the (well
defined) "help package" interface to have the help viewer do it's work.

OTOH, (for the help tool tips) the project code can be target of the
help search. This of course it unknown to the help viewer. So here the
IDE might do it's own search in the project files (and pass the result
to the help viewer via the help package interface.

(My opinion based on the current discussions)

-Michael

--

[Sven Barth]

Post by Michael Schnell

Post by Mattias Gaertner
The token is only one word. It misses the context. It can not
distinguish between a TStrings.LoadFromFile and a
TMemoryStream.LoadFromFile. Or think about the "Create". Only if the
search for the specific item fails only then should the help use a
simple word search.

Yep. But that does not mean that the IDE needs to do some search on it's
own. It just could pass the appropriate info though the the (well
defined) "help package" interface to have the help viewer do it's work.

The IDE has all infos that are necessary to find a certain identifier
(though there are problematic cases like "Writeln", etc.). It would be a
waste to duplicate this into every possible help package...

Regards,
Sven

--

[Michael Schnell]

Post by Sven Barth
.
The IDE has all infos that are necessary to find a certain identifier

OTOH it does not have a clue about the help texts itself, as it does not
know what format the help files the help viewer is about to show.

-Michael

--

[Reinier Olislagers]

Post by Michael Schnell

Post by Sven Barth
The IDE has all infos that are necessary to find a certain identifier

OTOH it does not have a clue about the help texts itself, as it does not
know what format the help files the help viewer is about to show.
-Michael

So it seems to me the best way is to
1. let the IDE figure out which exact identifier is meant
2. define and implement a communications protocol between IDE and help
viewer that gives this information to the help viewer
3. let the help viewer show the help in whatever way it thinks best

In other words, more or less what happens now with lhelp, right?
AFAIU, for external viewers the situation is currently different:
Lazarus passes the identifier name and the help system looks it up.
AFAIU, again, this can be improved by improving the IPC protocol in use;
there were some mails to the list about that.

What problem is left then, or am I misunderstanding something?

Regards,
Reinier

--

[Michael Schnell]

Post by Reinier Olislagers
In other words, more or less what happens now with lhelp, right?

This is what I supposed would happen. But I donb'rt know if it is true

Post by Reinier Olislagers
AFAIU, again, this can be improved by improving the IPC protocol in use;

To me this seems like the best solution.

-Michael

--

[Michael Schnell]

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

If it finds anything does it call the Help viewer via the Help Package
interface (i.e. can the help viewer add some info) or does it organize
the output on its own ?

-Michael

--

[Mattias Gaertner]

On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.
The help databases do the real search and how they do that is
completely up to them.

Post by Michael Schnell
If it finds anything does it call the Help viewer via the Help Package
interface (i.e. can the help viewer add some info) or does it organize
the output on its own ?

If no db found anything, then the IDE shows an error message.
If multiple db found something, then the IDE shows a dialog to choose.
If only one db found something, then the IDE calls the help viewer of
the mime type.

Mattias

--

[Michael Schnell]

Post by Mattias Gaertner
It asks the registered help databases. See View / IDE internals /
About IDE / help.
The help databases do the real search and how they do that is
completely up to them.

IMHO it would be better to have the help viewer do this step (after
being provided by the IDE with the necessary information). By this the
format and handling of "help database" is up to the help viewer.
Otherwise it would not be decently selectable.

-Michael

--

[Mattias Gaertner]

On Thu, 16 Feb 2012 13:11:35 +0100

Post by Michael Schnell

Post by Mattias Gaertner
It asks the registered help databases. See View / IDE internals /
About IDE / help.
The help databases do the real search and how they do that is
completely up to them.

IMHO it would be better to have the help viewer do this step (after
being provided by the IDE with the necessary information). By this the
format and handling of "help database" is up to the help viewer.
Otherwise it would not be decently selectable.

The selection dialog is only shown if multiple databases have help for
the same thing (e.g. the unit classes.pp in the fpc sources).
You can disable the default databases. AFAIK the chmhelppkg does that.
This way the selection dialog is never shown and the user directly
gets the viewer.
The context information is always collected and passed to the help.

If the user installs multiple helps for the same thing, then he gets
the selection dialog. Sounds reasonable to me.

Mattias

--

[waldo kitty]

Post by Mattias Gaertner
On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.

"registered help databases"?? /when/ do they get registered?

the reason i ask is because one thing i expressly did _not_ do when i followed
the instructions and started this thread was to exit lazarus at all... lazarus
was up and running the whole time i was following the instructions... the only
time it was not was when it restarted after i add the chmhelppkg and
recompiled... lazarus was running when i copied the chm files into the docs/html
directory... lazarus was running when i fixed the incorrect FPDoc Editor's path
to the doc files...

Post by Mattias Gaertner
The help databases do the real search and how they do that is
completely up to them.

another interesting tidbit...

Post by Mattias Gaertner

Post by Michael Schnell
If it finds anything does it call the Help viewer via the Help Package
interface (i.e. can the help viewer add some info) or does it organize
the output on its own ?

If no db found anything, then the IDE shows an error message.

i've seen that! :)

Post by Mattias Gaertner
If multiple db found something, then the IDE shows a dialog to choose.

i've seen this, too! ;)

Post by Mattias Gaertner
If only one db found something, then the IDE calls the help viewer of
the mime type.

and finally i've seen this, as well :)

so it is lazarus that is performing these digs into the chm files and isn't
locating these items that should already be documented in these local
documentation files (eg: write and writeln)... i guess now one needs to figure
out why... it could be one of two things, as far as i can see...

1. the information simply is not in the chm (not good)

2. there is a coding or logic error leading to the miss

TBH, i'm still reading back over your words and am still rather surprised that
lazarus is doing this work instead of the help viewer... i would have thought
that it would have been the help viewer doing the work after lazarus told the
help viewer what to search for... this also explains why i cannot "back up" to
choose another db entry but have to exit the help viewer and perform the F1 hit
again...


--

[Michael Schnell]

Post by waldo kitty
1. the information simply is not in the chm (not good)

or wherever file(s) the attached help viewer uses. (not good either).
Thus the IDE would need to either request the help"database" data from
the help viewer, or use the help viewer as a database engine and issue a
search request to it, or issue an appropriately complexly specified
"display" request to it.

-Michael

--

[waldo kitty]

Post by Michael Schnell

Post by waldo kitty
1. the information simply is not in the chm (not good)

or wherever file(s) the attached help viewer uses. (not good either).

right... i was thinking only of chm since that's what is expected to be the
online help at this point in time...

Post by Michael Schnell
Thus the IDE would need to either request the help"database" data from the help
viewer, or use the help viewer as a database engine and issue a search request
to it, or issue an appropriately complexly specified "display" request to it.

hehe... [overengineered] hey! let's use a local sql database and to hell with
all these various formats... provide the context to the database search engine
and let it figure out what you meant to lookup [/overengineered] :P :lol:


--

[Sven Barth]

Post by waldo kitty

Post by Michael Schnell

Post by waldo kitty
1. the information simply is not in the chm (not good)

or wherever file(s) the attached help viewer uses. (not good either).

right... i was thinking only of chm since that's what is expected to be
the online help at this point in time...

Correction: It's expected to be the offline help, not the online help.

Regards,
Sven


--

[Sven Barth]

Post by waldo kitty

Post by Mattias Gaertner
On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.

"registered help databases"?? /when/ do they get registered?

The IDE is registering these internally.

Post by waldo kitty
so it is lazarus that is performing these digs into the chm files and
isn't locating these items that should already be documented in these
local documentation files (eg: write and writeln)... i guess now one
needs to figure out why... it could be one of two things, as far as i
can see...
1. the information simply is not in the chm (not good)
2. there is a coding or logic error leading to the miss

3. The IDE can not correctly establish the context for Writeln, because
it is not physically present in the source (the unit System).

Post by waldo kitty
TBH, i'm still reading back over your words and am still rather surprised that lazarus is doing this work instead of the help viewer... i would have thought that it would have been the help viewer doing the work after lazarus told the help viewer what to search for... this also explains why i cannot "back up" to choose another db entry but have to exit the help viewer and perform the F1 hit again...

Lazarus is doing this, because in theory (currently not possible*) you
could have the following setup:

* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)

All three help systems are registered to the IDE and for each you have
added the corresponding files (e.g. rtl.chm and fcl.inf). Then the IDE
will ask each help system whether it can provide help and in our example
LHelp will answer with "Yes" for all identifiers that belong to rtl.chm.

I know this example is rather artificial, but that is the purpose of
this help system.

Note: A more practical use case might be to add third party
documentation that e.g is only available in CHM format, but for RTL, FCL
and LCL documentation you normally use DocView...

* This is because of at least two reasons:
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

Regards,
Sven

--

[waldo kitty]

Post by Sven Barth

Post by waldo kitty

Post by Mattias Gaertner
On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.

"registered help databases"?? /when/ do they get registered?

The IDE is registering these internally.

i understand that but the question is *when* does it do this... remember, i
stated that lazarus was running with the chmhelppkg installed when i copied the
chm files to the docs/html directory... i pushed the files in the background
across my network from another machine to the machine where lazarus was
running... what will it do if i remove those chm files while it is running?

there is nothing that states that you have to restart lazarus after putting the
files in place so that these files can be registered...

Post by Sven Barth

Post by waldo kitty
so it is lazarus that is performing these digs into the chm files and
isn't locating these items that should already be documented in these
local documentation files (eg: write and writeln)... i guess now one
needs to figure out why... it could be one of two things, as far as i
can see...
1. the information simply is not in the chm (not good)
2. there is a coding or logic error leading to the miss

3. The IDE can not correctly establish the context for Writeln, because it is
not physically present in the source (the unit System).

which source? why would the IDE be looking in the system units source files? it
can't do that on a binary only installed system where there are no sources for
the system unit...

Post by Sven Barth

Post by waldo kitty
TBH, i'm still reading back over your words and am still rather surprised that
lazarus is doing this work instead of the help viewer... i would have thought
that it would have been the help viewer doing the work after lazarus told the
help viewer what to search for... this also explains why i cannot "back up" to
choose another db entry but have to exit the help viewer and perform the F1
hit again...

Lazarus is doing this, because in theory (currently not possible*) you could
* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)
All three help systems are registered to the IDE and for each you have added the
corresponding files (e.g. rtl.chm and fcl.inf). Then the IDE will ask each help
system whether it can provide help and in our example LHelp will answer with
"Yes" for all identifiers that belong to rtl.chm.
I know this example is rather artificial, but that is the purpose of this help
system.
Note: A more practical use case might be to add third party documentation that
e.g is only available in CHM format, but for RTL, FCL and LCL documentation you
normally use DocView...
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

this actually all does make sense... in its context... it does also explain why
the help system is built the way it is... but it still doesn't explain why
things that have been documented for years are not available in the official chm
files... i assume they are available in the official html files but have not
pulled that huge load down to find out... it likely would do me much good anyway
because lhelp is all i currently have that i can use not to mention the space
consumption on an already space tight machine :?

--

[Sven Barth]

Post by waldo kitty

Post by Sven Barth

Post by waldo kitty

Post by Mattias Gaertner
On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.

"registered help databases"?? /when/ do they get registered?

The IDE is registering these internally.

i understand that but the question is *when* does it do this...
remember, i stated that lazarus was running with the chmhelppkg
installed when i copied the chm files to the docs/html directory... i
pushed the files in the background across my network from another
machine to the machine where lazarus was running... what will it do if i
remove those chm files while it is running?
there is nothing that states that you have to restart lazarus after
putting the files in place so that these files can be registered...

The databases are registered IN CODE inside the IDE. They are always
registered no matter if a help system is installed. By default they
simply point to an URL where the online documentation is located. The
CHM package contains code which overwrites the paths on IDE startup for
the help and the action to do when an entry is looked for (it
essentially disables the online help system of Lazarus).

Post by waldo kitty

Post by Sven Barth

Post by waldo kitty
so it is lazarus that is performing these digs into the chm files and
isn't locating these items that should already be documented in these
local documentation files (eg: write and writeln)... i guess now one
needs to figure out why... it could be one of two things, as far as i
can see...
1. the information simply is not in the chm (not good)
2. there is a coding or logic error leading to the miss

3. The IDE can not correctly establish the context for Writeln, because it is
not physically present in the source (the unit System).

which source? why would the IDE be looking in the system units source
files? it can't do that on a binary only installed system where there
are no sources for the system unit...

If I remember correctly you are on a Windows system and you used the
normal Lazarus installer? Then you have the source, because the Windows
installer includes the source for the RTL and Packages directories of
FPC inside %lazarusdir%\fpc\%fpcversion%\ (otherwise most of the RTLs
features like CodeTools would not work as good as they do, also you
would not have been able to find e.g. "Integer" in the help).

Post by waldo kitty

Post by Sven Barth

Post by waldo kitty
TBH, i'm still reading back over your words and am still rather surprised that
lazarus is doing this work instead of the help viewer... i would have thought
that it would have been the help viewer doing the work after lazarus told the
help viewer what to search for... this also explains why i cannot "back up" to
choose another db entry but have to exit the help viewer and perform the F1
hit again...

Lazarus is doing this, because in theory (currently not possible*) you could
* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)
All three help systems are registered to the IDE and for each you have added the
corresponding files (e.g. rtl.chm and fcl.inf). Then the IDE will ask each help
system whether it can provide help and in our example LHelp will answer with
"Yes" for all identifiers that belong to rtl.chm.
I know this example is rather artificial, but that is the purpose of this help
system.
Note: A more practical use case might be to add third party
documentation that
e.g is only available in CHM format, but for RTL, FCL and LCL
documentation you
normally use DocView...
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

this actually all does make sense... in its context... it does also
explain why the help system is built the way it is... but it still
doesn't explain why things that have been documented for years are not
available in the official chm files... i assume they are available in
the official html files but have not pulled that huge load down to find
out... it likely would do me much good anyway because lhelp is all i
currently have that i can use not to mention the space consumption on an
already space tight machine :?

I know that I'm repeating myself, but Writeln IS AVAILABLE in the CHM
files. Just open the help with some other identifier that's available in
the RTL (e.g. Integer), change to the Search tab and enter "Writeln". In
the result list (sadly it's a rather long list with a strange sorting)
you'll find the entry for "Writeln" (in my case it was at the end of the
list).
It's not the documentation that's flawed here. Both the online
documentation and the CHM one (and also Graeme's INF one) are created
from the same raw documentation files (XML files to be specific), so
there are no content related differences between them. It's just the
lookup of the IDE's help system that is not able to find
"System.Writeln", because it does not physically exist as a procedure in
the System unit.

Regards,
Sven

--

[Graeme Geldenhuys]

If I remember correctly you are on a Windows system and you used the normal
Lazarus installer? Then you have the source, because the Windows installer
includes the source for the RTL and Packages directories of FPC inside
%lazarusdir%\fpc\%fpcversion%\ (otherwise most of the RTLs features like
CodeTools would not work as good as they do, also you would not have been
able to find e.g. "Integer" in the help).

So what you are saying is that if you don't have the source code for
FPC, them some of the help wouldn't work??? Now that is a design flaw!
Having the source code of FPC was never a requirement for Lazarus -
but now it seems it is a must. A very odd design if you ask me. [good
news is, I have a solution I'll post in another thread]
--
Regards,
  - Graeme -


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

--

[Michael Schnell]

Post by Sven Barth
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

But as The CHM package overrides the database search function, a DocView
(or whatever) package would be able to do this, as well,

Sounds great.

-Michael

--

[Graeme Geldenhuys]

Post by Sven Barth
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

But as The CHM package overrides the database search function, a DocView (or
whatever) package would be able to do this, as well,
Sounds great.

No, it doesn't sound great. If I had to implement a INFHelpPackage
like what was done for CHM, that means the last one to be compiled
would "steal" / override all the databases for themselves. Thus, you
can't have both CHM and INF help packages installed together.
--
Regards,
  - Graeme -


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

--

[Mattias Gaertner]

On Thu, 16 Feb 2012 16:48:54 +0100

Post by Sven Barth
[...]
Lazarus is doing this, because in theory (currently not possible*) you
* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)
All three help systems are registered to the IDE and for each you have
added the corresponding files (e.g. rtl.chm and fcl.inf). Then the IDE
will ask each help system whether it can provide help and in our example
LHelp will answer with "Yes" for all identifiers that belong to rtl.chm.
I know this example is rather artificial, but that is the purpose of
this help system.
Note: A more practical use case might be to add third party
documentation that e.g is only available in CHM format, but for RTL, FCL
and LCL documentation you normally use DocView...
- the CHM package overrides all databases to itself
- DocView does not yet have an integration package

Here is a more practical example:
The package externhelp installs help for the windows unit opening a
browser on msdn, the gtk2 units, opening the gtk2.org and the
postgresql units.
It also adds a page to the IDE options where you can define your own
additions.


Mattias

--

[Hans-Peter Diettrich]

Post by Sven Barth
Lazarus is doing this, because in theory (currently not possible*) you
* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)

IMO this is a very bad idea, that may end up in different information,
displayed by multiple help viewers at the same time. At least a clear
priority should exist, so that e.g. online help could be searched when a
topic was not found in the offline help, or that online help should be
preferred whenever available. The user should have full control over
what he gets to see.

E.g. Embarcadero had to use the Microsoft (VS) help system, to make the
Windows and .NET topics available in the IDE help system. The FPC
documentation providers refuse to add Windows specific help, and say
that Windows users should use the already available Microsoft sources.
How would the MS content integrate in your model? Will the user then
have to specify the wanted context himself, when he is presented an
selection dialog with almost *every* F1 press?

DoDi


--

[Sven Barth]

Post by Hans-Peter Diettrich

Post by Sven Barth
Lazarus is doing this, because in theory (currently not possible*) you
* for LCL help use the online documentation
* for RTL help use LHelp (CHM based)
* for FCL help use DocView (INF based)

IMO this is a very bad idea, that may end up in different information,
displayed by multiple help viewers at the same time. At least a clear
priority should exist, so that e.g. online help could be searched when a
topic was not found in the offline help, or that online help should be
preferred whenever available. The user should have full control over
what he gets to see.

I already said that it's a rather artificial example. Further below I
had written a more practical one. Also in the example above there would
only exist a rtl.chm and a fcl.inf (thus the respective help viewers
only find these files) and the missing one is directed to online help.
But as I said: It's an artificial example.

Post by Hans-Peter Diettrich
E.g. Embarcadero had to use the Microsoft (VS) help system, to make the
Windows and .NET topics available in the IDE help system. The FPC
documentation providers refuse to add Windows specific help, and say
that Windows users should use the already available Microsoft sources.
How would the MS content integrate in your model? Will the user then
have to specify the wanted context himself, when he is presented an
selection dialog with almost *every* F1 press?

Look at Matthias' answer regarding ExternHelp. Also there is nothing
that stops one to add a help provider that uses Microsoft's Document
Viewer to display help for Windows related stuff.

Regards,
Sven

--

[Mattias Gaertner]

On Thu, 16 Feb 2012 10:23:55 -0500

Post by waldo kitty

Post by Mattias Gaertner
On Thu, 16 Feb 2012 12:30:44 +0100

Post by Michael Schnell

Post by Andrew Haines
When you press F1 in lazarus it performs it's own search of what it is
looking for. If it finds something it presents a list of possible
results if there are more than one.

Where does Lazarus (I suppose you mean the IDE ) search ?

It asks the registered help databases. See View / IDE internals /
About IDE / help.

"registered help databases"?? /when/ do they get registered?

You only need to know, if you want to write a help db like chmhelppkg.
It's done in the "register" procedure of an installed package unit.

Post by waldo kitty
the reason i ask is because one thing i expressly did _not_ do when i followed
the instructions and started this thread was to exit lazarus at all...

IDE plugins can register and unregister Help databases at any time.
The plugins needs to be installed and for this you need to restart
the IDE once.

Post by waldo kitty
lazarus
was up and running the whole time i was following the instructions... the only
time it was not was when it restarted after i add the chmhelppkg and
recompiled...

ok

Post by waldo kitty
lazarus was running when i copied the chm files into the docs/html
directory... lazarus was running when i fixed the incorrect FPDoc Editor's path
to the doc files...

Post by Mattias Gaertner
The help databases do the real search and how they do that is
completely up to them.

another interesting tidbit...

Post by Mattias Gaertner

Post by Michael Schnell
If it finds anything does it call the Help viewer via the Help Package
interface (i.e. can the help viewer add some info) or does it organize
the output on its own ?

If no db found anything, then the IDE shows an error message.

i've seen that! :)

Post by Mattias Gaertner
If multiple db found something, then the IDE shows a dialog to choose.

i've seen this, too! ;)

Maybe chmhelppkg reported several results.
That's a choice of the chmhelppkg. Maybe it can be made optional and
use it's own selector in the viewer.

Post by waldo kitty

Post by Mattias Gaertner
If only one db found something, then the IDE calls the help viewer of
the mime type.

and finally i've seen this, as well :)
so it is lazarus that is performing these digs into the chm files and isn't
locating these items that should already be documented in these local
documentation files (eg: write and writeln)... i guess now one needs to figure
out why... it could be one of two things, as far as i can see...
1. the information simply is not in the chm (not good)
2. there is a coding or logic error leading to the miss
TBH, i'm still reading back over your words and am still rather surprised that
lazarus is doing this work instead of the help viewer... i would have thought
that it would have been the help viewer doing the work after lazarus told the
help viewer what to search for... this also explains why i cannot "back up" to
choose another db entry but have to exit the help viewer and perform the F1 hit
again...

The IDE has no idea of chm files. All chm functions and how chm is
searched or presented to the user is done by the chmhelppkg and lhelp. I
have not written this package. Maybe next week I have some time to look
at it and improve a few things.


Mattias

--

[Michael Schnell]

Post by Marco van de Voort
There is no "CHM help".

http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE

says:

"1) Make sure that the package *chmhelppkg* is intalled."

-Michael

[waldo kitty]

Post by waldo kitty
placed the cursor on a pascal keyword (ie: implementation in the currently
opened file from when i opened the lhelp.lpi), pressed F1 and... no help :(

To get context help for pascal language keywords, you need to install a combined
chm file that (in addition to the standard LCL) help includes FPC language help
(and hopefully help on help, IDE help, RTL help, you name it.

i understand what you are saying but lhelp is working, when i attempt to look up
something that it can find, with more than one chm file... there are three of
them in the "latest stable" documentation archive as pointed to by the wiki
page... the biggest thing i see is that a lot of stuff, stuff i would have
thought would have been documented first, is simply not documented...

I don't know if such a file even exist and/or (how) it is possible to build it
from the svn sources.

yeah, me either...

(Se the lots of recent discussions on the help system that pointed out the
benefits of DocView.)

i've been watching it... even posted a message or two in it/them i think ;)

once i get past this lhelp stuff, then docview is next on my list to look at :P

--

[Michael Schnell]

Post by waldo kitty
once i get past this lhelp stuff, then docview is next on my list to look at :P

Great ! There might be some limitations and DocView (still) is installed
using the "external tool" interface not not the "help package"
interfaces (like chmhelppkg). Maybe Graeme can improve this.

-Michael

--

[Graeme Geldenhuys]

using the "external tool" interface not not the "help package" interfaces
(like chmhelppkg). Maybe Graeme can improve this.

As I mentioned numerous times, I believe the "external tools"
interface works better with DocView than the "help package
integration" interface. I don't believe there will be any benefits to
implementing the latter. But, if I have any free time some day, I'll
make such a package - no promises though.
--
Regards,
  - Graeme -


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

--

[Sven Barth]

Post by Graeme Geldenhuys

using the "external tool" interface not not the "help package" interfaces
(like chmhelppkg). Maybe Graeme can improve this.

As I mentioned numerous times, I believe the "external tools"
interface works better with DocView than the "help package
integration" interface. I don't believe there will be any benefits to
implementing the latter. But, if I have any free time some day, I'll
make such a package - no promises though.

It might be enough to implement the IPC possibility you spoke of, then
somebody else can implement the package.

Regards,
Sven

--

[Graeme Geldenhuys]

Post by Sven Barth
It might be enough to implement the IPC possibility you spoke of, then
somebody else can implement the package.

The IPC support will definitely happen in DocView - I need it for
controlling or updating DocView from my applications.
--
Regards,
  - Graeme -


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

--

[Michael Schnell]

Post by Graeme Geldenhuys
As I mentioned numerous times, I believe the "external tools"
interface works better with DocView than the "help package
integration" interface.

The current discussion suggests that the help package interface might be
improved.

The current discussion shows that the external interface is not good
enough, as it only provides a single word and not the context.

If e.g. the cursor is on "Visible" in the line "Button1.Visible :=
True", it can't know that help on TButton in to be shown.

So the IDE needs to find that Button1 is a TButton and should provide
"TButton.Visible" to the help Viewer through the Help package interface.

If it does not find the type of Button1 it of course just provides
Visible to have the help viewer show a selection of possibilities.

-Michael

--

[Hans-Peter Diettrich]

Post by Michael Schnell
The current discussion shows that the external interface is not good
enough, as it only provides a single word and not the context.

Who says that this "word" cannot be e.g. "#lcl.controls.TButton.Visible"?

Post by Michael Schnell
If e.g. the cursor is on "Visible" in the line "Button1.Visible :=
True", it can't know that help on TButton in to be shown.
So the IDE needs to find that Button1 is a TButton and should provide
"TButton.Visible" to the help Viewer through the Help package interface.

It's not the IDE, it's the Editor that has to determine the context. If
it finds an identfier (Visible), it must invoke help for its
declaration. If it finds a reserved word, it must invoke the language
reference database instead. For help on a control in an dialog the
designer of the dialog is responsible, by adding the proper "word"
(search path) to the control's HelpKeyword or HelpContext.

Post by Michael Schnell
If it does not find the type of Button1 it of course just provides
Visible to have the help viewer show a selection of possibilities.

This approach is too dumb. FPDoc already does an good job in linking to
inherited classes or methods, so that a help viewer has all information
for narrowing down the request to the closest existing help entry.
Likewise help on a dialog control should defer to the help on the entire
dialog, when no specific entry is found for help on a contained control.


I only found one situation, so far, where help on e.g. "integer" leads
to multiple units. This might be improved in the Editor, which IMO can
*know* whether the current unit uses "objpas" or only "system". Here the
Editor has better chances, to figure out the precise unit, than the user
has.

DoDi


--