Installing IDE Help

[Curt Carpenter]

Hello.
I'm using Lazarus 0.9.30.4 under Windows XP, and have been trying to install the IDE help system following the instructions in http://wiki.freepascal.org/Installing_Help_in_the_IDE.  I've not had any success though.   Are there any newer instructions that I should be following?

In the first step, the instructions tell me:  "In Lazarus, make sure the package chmhelppkg is intalled. "  When I look I see that I have a package called ChmHelpPkg 01.  Is that the wrong package?
         
When I search for the chm files via the link provided in the instructions, I see two directories:  Lararus 1.0RC1 and Lazarus 0.9.3.4.  Not sure which of these two folders to use:  the first contains tar.gz  files as indicated in the instructions, while the second contains a .zip file, which makes more sense in a Windows context.

Any help appreciated.

============================================================

Update:  I just received a message from the IDE that I needed to move my .chm files into the docs\html folder, rather than putting them in a docs\chm folder.  Moved them, and now I get F1-key  help if I move my cursor to something like TButton.  Still no sign of help if I move my cursor in the editor to something like for though.

Again, any help appreciated.

[BigChimp]

Curt, you're on the right track.

docs\html is the old location; newer versions of Lazarus can also use docs\chm. Your 0.9.30.4 is probably too old for that.

You now have help for TButton, a GUI control? Good. That means the chm file for the LCL is picked up.

You don't have help for Pascal keywords? That probably means you didn't download the FPC help files. Try downloading files containing e.g. RTL.CHM, extracting them and putting them in the directory containing the LCL.CHM file (i.e. docs\html in your case).

One location I used is:
http://sourceforge.net/projects/freepascal/files/Documentation/2.6.0/doc-chm.zip/download
there may be newer in the meantime, sorry, too lazy now to look up the wiki docs.
If you see .tar.gz files you can extract them with e.g. 7zip.

Presumably restart Lazarus and it should work.

[BigChimp]

In the first step, the instructions tell me:  "In Lazarus, make sure the package chmhelppkg is intalled. "  When I look I see that I have a package called ChmHelpPkg 01.  Is that the wrong package?

The line below that instruction on the wiki says:

(windows installers, as of 0.9.30+ do include this program pre-compiled, package installed and paths set out-of-the-box)

I've updated the wiki at
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_help_for_the_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE
Could you tell me if that makes more sense to you?

[picstart]

I have never been able to get help to work with Lazarus. Help is for me the least robust feature of Lazarus. Fortunately I have a version of help from Delphi I can use and there is  good help for Lazarus on the web.
The Lazarus F1 help has never and still doesn't work Laz 9.30.4 fpc 2.6.0 win7pro 32bit. I have followed the wiki below to the letter. And pressing F1 the message I get is always no help available.

From the wiki
Installing CHM help

Note: these instructions use Windows path notation, but they also apply to other systems with minor changes.

    For older versions: go to <your-lazarus-directory>\components\chmhelp\lhelp and see if lhelp.exe exists. Compile <your-lazarus-directory>\components\chmhelp\lhelp\lhelp.lpi if it doesn't. For newer versions: Lazarus will compile lhelp if needed the first time you press F1, but compiling the lpi yourself won't hurt.
    In Lazarus older than 0.9.30: make sure the package chmhelppkg is installed. See the menu Package->Install Packages. It should appear in the left column and is called something like ChmHelpPkg 0.2. Since 0.9.30, Windows installers include this package installed with paths set out of the box.
    Go to <your-lazarus-directory>\docs\chm and look for lcl.chm and fcl.chm. If they don't exist, go to http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/, download and unpack the package with the CHM files into <your-lazarus-directory>\docs\chm\ (for old versions such as 0.9.30.4, download into <your-lazarus-directory>\docs\html\ instead).
    Additional troubleshooting step (useful if installing from Subversion, not using an installer): go to the Environment Options, tab "Help Options' and select the "CHM Help Viewer". Check its properties:
        "HelpExe" should be the lhelp you just built (i.e. <your-lazarus-directory>\components\chmhelp\lhelp\lhelp.exe)
        "HelpFilesPath" should be where you put the CHM files. Leave it empty to use the default, which includes $(LazarusDir)/docs/html (and $(LazarusDir)/docs/chm in newer versions).

Now context-sensitive help using F1 should work.

[Leledumbo]

I have 0.9.30.4 installed in my office with context sensitive help using chm documentation works. The "No help available error" will pop up if you don't put the chm in the correct place (at least if you don't want to change help options, you have to put it in the correct place). In 0.9.30.4, this is $(LazarusDir)/docs/html. Put the chms downloaded from either sourceforge or marco's stack.nl account, install chmhelppkg, and everything should work.

[BigChimp]

@picstart: good that you followed the wiki, but as Leledumbo indicates, there are still some choices you can make (which settings you set, where you download the files etc).

I'd be happy to try and help if you post what the results of each step were:

• Did you have lhelp.exe? If not, did you compile it?
• Is the package chmhelppkg installed? What version?
• Where did you download the CHM archive? Where did you extract the files?
• What are your settings for Enviornment Options, Help Options, CHM Help Viewer: HelpExe and HelpFilesPath?

Thanks,
BigChimp

[picstart]

The issue is mostly an expectation issue on my part. The built in help Delphi provided has raised the bar too high.
My early experiences with Lazarus built in help were all negative.. nothing worked or was so obtuse only an expert could get it to work but then again the expert probably didn't need built in help. I think it is unfortunate that in the past Lazarus help has needed so much help. Anyway I have Delphi help and the online Help so getting it to work may well be unproductive since often in a year or two a new release of Lazarus may remove the need for help to need an install wiki. IMHO the Help should be built in or if for download size issues have a separate installer that with one command adds help to the IDE. Now I can see there is forward progress with help such as the need to create the exe has been resolved and even the which directory chm or html is being addressed. Having a chm and a html directory but needing the chm files to go into the html directory gets a gold medal  in the obtuse Olympics. Sure chm is a jazzed up html file but really? Again Lazarus is a really great accomplishment and I can see help equaling Delphi's help at some point in the future.
I very much appreciate the help being offered but I'll wait for a future solution.

[BigChimp]

You don't understand. Putting chm files in the html directory is a requirement of your old version of Lazarus. It has been fixed for a long while now.

Have a try with the newly released 1.0RC1, I think it should even download the chms for you in the proper directory.

Oh and thanks for wasting my time replying to that post when you weren't even interested in fixing your install... though you probably didn't do that on purpose

[Leledumbo]

but then again the expert probably didn't need built in help

Well... you must be talking about God, not expert (do you really think an expert can remember ALL of those functions and classes scattered over thousands of units? I don't even think anyone can remember ALL unit names... )

IMHO the Help should be built in or if for download size issues have a separate installer that with one command adds help to the IDE

Try the new Lazarus 1.0RC1 installer

[picstart]

For information purposes ...the version I am using Laz 9.30.4 fpc 2.6.0 with win7pro 32bit. The Download section states that this is the latest robust version.
Now most less than optimal results will also come with a great explanation of why there are issues and often elaborate workarounds are proffered. Some will placate by saying it could have been worse. Some will take a workaround route some will not. Of those who can live without the feature some will point out the issue some will not. In the end it's just statistics except that those never pointing out issues skew the the data towards false positives. Again the good news is that help is getting help and is moving in a good direction.
BigChimp
I have learned much from your posts (thank you) so I apologize if reporting my experience with help wasted your time. I didn't emphasize enough that I had a Delphi and Web alternative that I have grown used to while Lazarus Help was getting help. My issue likely is that I have old lazarus directories (vestiges from prior versions). I am gun shy about Lazarus IDE dependencies so I never prune until my projects are finished and a new robust download version is posted.. The lazarus project exe's are remarkably dependency free. I love it.

[Martin_fr]

For information purposes ...the version I am using Laz 9.30.4 fpc 2.6.0 with win7pro 32bit. The Download section states that this is the latest robust version.

I understand everyone who wants to stay with the stable release. And in general, this is a wise decision.

But I also invite you and everyone, to test the RC:

• The RC is most likely as stable as the the last release. It had a 4 month stabilization period in the fixes branch, and received hundreds of fixes.
  
• Testing it gives you and everyone a chance to tell the developers, if anything breaks your code. If you find out after the final release, then it is too late. In this context it will be good to have a look at the compatibility changes on the wiki: http://wiki.lazarus.freepascal.org/Lazarus_1.0_release_notes#Changes_affecting_compatibility
  
• You can test it, while keeping the stable install for your work

In order to test it, while keeping your current install, you need to:
- Choose a different install directory
- Ignore the warning of the installer, that "multiple installations are not supported"
  - obviously do NOT uninstall
  - do NOT "clean user config" (this is anyway not done by default)
  - skip QT dll
  - probably avoid creating menu and desktop shortcuts
  The installer will strictly keep to the new directory only

Before starting the new Lazarus, you must create a shortcut with a --primary-config-path= option:
  http://wiki.lazarus.freepascal.org/Multiple_Lazarus

And then always use that shortcut only, so the test install will not interfere with your settings.

Additionally you can create a backup of those settings.

[Curt Carpenter]

BigChimp:

I appreciate your help!

I have the following .chm files in my lazarus\docs\html folder:  rtl.chm, fcl.chm and lcl.chm.  I'll check though, to see if there are some FPC .chm files I haven't included here and see if that does the trick.  You've given me enough information to work the issue though, so I'm happy.

Having help for things like "For" isn't important, other than for completeness.  Otherwise, the context sensitive help is working perfectly now!

I read your edit to the wiki, and it makes good sense as far as I'm concerned.  Newcomers like me though, tend to want to follow instructions like this exactly, and we (well, I anyway) get paranoid when we can't.  So when you refer to 0.9.30.4 as an "older version," it makes us worry, since as far as we know it's the latest version -- and we don't have the understanding (or courage) to run multiple versions for worry over messing something up and ending up needing to start over from scratch.   Same with file names and paths:  we don't know enough to be flexible with those, so we follow instructions slavishly.   

Thanks again for your help.   

[picstart]

Martin with all due respect a statement like "Ignore the warning of the installer, that "multiple installations are not supported" is often going to deter all but the most knowledgeable or the fool hardy from installing multiple versions. Sure politicians say one thing but mean something else..... so now the installer isn't to believed as well.
Anyway Lazarus is a great achievement (even if it does come with a small dose of doublespeak) kudo's to the team.

[Martin_fr]

Martin with all due respect a statement like "Ignore the warning of the installer, that "multiple installations are not supported" is often going to deter all but the most knowledgeable or the fool hardy from installing multiple versions. Sure politicians say one thing but mean something else..... so now the installer isn't to believed as well.

Well first of all: I did put the warning there. So, if I tell you, to ignore it *and* give you the additional steps, then I should know what I do.

Of course still leaves you with having to follow the steps without error.

* Some background:

1) The problem of multiple installations is, that they all use the same dir for user conf. (See the wiki link from my post, it will tell you the path for different OS)
Some of the config may not hurt if shared. But other parts can cause a battle of warnings and errors. e.g if the fpc version differ, and one Lazarus changes the fpc path of the other. Or the path to the installed packages, which will not work cross version.

All that is solved with the primary config path. But all that can also be solved by backing up the conf.

2) Otherwise, the only installed file that is not in the selected folder is  the QT dll (which you may not even use)

3) And last not least, if you go to "control panel" and try to uninstall it will list only one lazarus (the one that was last installed)

---
After all having multiple lazarus works very well (I have 6 of them). Only the installer does not help you with it.

The warning was added, because previously people have repeatedly tried, hoping the installer would. The warning explicitly says

Another installation of %1 was found at %2. Please use the button below to uninstall it now. If you wish to keep it, please tick the checkbox to continue.',
Note: Using multiple copies of Lazarus is not supported by this installer.
Using several installations of Lazarus can lead to conflicts in files shared by all of the installations, such as the IDE configuration.
If you wish to use more than one installation, then you must do additional setup after this installation finished. Please see the Lazarus web page for this, and how to use --primary-config-path

---
One more thing, that I came to think of only now (because I never use it). The double click association in the windows explorer will be changed to the new lazarus.
If you uncheck the option, it only means no new ones are created, but old ones are still updated.

That can be fixed by selecting the old lazarus, via the context menu "open with" in the explorer itself.

----
Ultimately it is your decision.

I don't want to talk you into something that you do not want.

But I want you do know what and why, before you make that decision.

[BigChimp]

@Martin: wow. Kudos for a crystal clear explanation.

I appreciate your help!

Thanks, Curt, and thanks for describing your experiences/thoughts!

I have the following .chm files in my lazarus\docs\html folder:  rtl.chm, fcl.chm and lcl.chm.  I'll check though, to see if there are some FPC .chm files I haven't included here and see if that does the trick.

If you have any .xct files, you could also extract them. AFAIU, they're cross-reference files that help searching in one chm doc (e.g. LCL)  for terms defined in others (RTL/FCL).
FYI, I've got these chms, but I'm using fpcup to get them and have perhaps downloaded some manually:

Code: [Select]

22-06-2012  05:42         2.014.399 fcl.chm
29-12-2011  01:32           100.171 fpdoc.chm
29-07-2012  12:37        12.558.895 lcl.chm
29-12-2011  01:32           385.677 prog.chm
29-12-2011  01:32           617.137 ref.chm
22-06-2012  05:42         3.286.543 rtl.chm
29-12-2011  01:32             6.907 toc.chm
29-12-2011  01:32           631.049 user.chm
Seems like it's mostly the user guide, programmer's guide and the very minor guide to fpdoc... I think one of them might have the help on basic Pascal keywords but I always mix up the names of the manuals.
If the download with your Lazarus help files doesn't contain these, perhaps the FPC specific doc download has them:
http://sourceforge.net/projects/freepascal/files/Documentation/2.6.0/doc-chm.zip/download

Fortunately the 1.0RC1 installer flawlessly installs chm help out of the box... so I'd recommend trying it out (see Martin's excellent post on how to install side by side with your existing Laz install). Once you go "Laz side by side", you never go back

I read your edit to the wiki, and it makes good sense as far as I'm concerned.  Newcomers like me though, tend to want to follow instructions like this exactly, and we (well, I anyway) get paranoid when we can't.  So when you refer to 0.9.30.4 as an "older version," it makes us worry, since as far as we know it's the latest version -- and we don't have the understanding (or courage) to run multiple versions for worry over messing something up and ending up needing to start over from scratch.   Same with file names and paths:  we don't know enough to be flexible with those, so we follow instructions slavishly.   

Excellent points, I agree. I'll see if I can clear things up, but with 1.0RC1 being out, 1.0 release isn't that far off and 0.9.30.4 will indeed be old. Perhaps a separate section with notes for 0.9.30.4 will be clearer.

Edit: modified wiki page. Hope it's more precise and clearer now.