What are the steps required in order to install the various help options?

[CephasAtheos]

G'day all,

I've been reading the wiki and various threads here about enabling the various help files. Unfortunately, I'm more confused than ever, and so are many other people. Some of the information is very detailed and great, but it's years out of date. Other information is very complex, and doesn't explain anything at all in terms of understanding how the help system works nowadays, and what packages need to be installed in the ide and so on. There are also multiple help packages that seem to co-exist, but it's not clear how they are different, or why there are two of them, and why sometimes one and sometimes both are needed.

Plus, there's not much information on what help types (chm or html or xml) work best in what situations. Plus, there's a whole bunch of different archives mentioned with various versions of the precompiled help files, but after doing what I thought was compiling the chm files, and setting up the paths in the ide, I can't get them to actually work in the IDE (when pressing F1 or control-F1, I get told that "the answers are in the database, but I can't give them to you"!!! This makes me very sad. )

So here are my questions, and if anyone can provide answers that work, I'll put them in the wiki in the next 24 hours so everyone can benefit.

1) Are ALL the help files (runtime, core, ide, and so on) available as part of the current distribution?
1a) If not, where can we get the files? Or individual subsets of the files?

2) Since the help isn't installed (or at least, isn't functioning) when starting from a complete new build of lazarus, what steps do we need to take to compile and install ALL the help files?
2a) Is this actually possible without affecting the ide build? In other words, can we just "add" the help system without needing multiple rebuilds of the rest of the ide?

Preferably separate steps (if that's possible) for html, chm, and whatever other alternatives are available would be most helpful, then people can select whichever format suits them best.

3) I've read that the different IDEs (text and graphics) have different needs in terms of tables of contents (TOC), what help groups will work and so on. It would be helpful if this could be clarified, so we can understand what we need to have for each ide type, all in one place.

4) Would it be useful to have a repository (folder) accessible from the wiki, where precompiled files could be maintained, so people don't have to jump through hoops to get the latest help files. If they could be provided ready to unzip into whatever hierarchy is needed, that would also be helpful I think.

I realise it's not possible to have perfectly up-to-date help packages (not ide packages, groups of help files - this is really confusing terminology, and I'm sorry about that!) for every development version. But if a "base" version of the help files - say 2.6.0 - were available to be installed in lieu of the latest and greatest versions, then that would probably be better than nothing at all.

5) Is it worth having a separate section for the help files? Where people can just update, compile, and test/package/rollout the help part of the application? Because it's really confusing enough with command-line compilers, in-ide-compilers, and now help/doc compilers all being talked about, with not much to tell the difference for new users!

And, as always : If this information currently exists, and meets these requirements already, please forgive my questions and just point me to the resource where all this stuff is documented. (Right now, there's a hell of a lot of information, but it's all over the place). This might be a good place for me to start pulling stuff together and weeding the garden, so to speak, so other people can benefit.

Thanks, as always, and I hope that answers here will work for everyone, and we never hear another help-related question, ever again, forever and ever.
Cheers,
"Helpless" Pete

[BigChimp]

Piet jongen,

You can write long posts. Haven't read it all, sorry.
I'd advise CHM help: it's compressed, and the viewer is available (and set up) by default for Lazarus 1.0.
If you haven't set up help yet, I'd start here:
http://wiki.lazarus.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_help_.28Lazarus_1.0RC1_and_later.29
In short, just download the Lazarus 1.0 CHM zip file, extract it in the indicated directory. Now help should work.
Edit: actually, Lazarus 1.0 should ship with the CHM file, no need to download. Forgot about that.
Please follow the steps indicated in the link above and report on what the results are. Help should just work.
(I'm assuming you're using Lazarus 1.0 from the installer - if you're not, you should download the chm help & extract it. No need to go recompiling it etc and the zip contains help for Lazarus, FPC keywords, some manuals for FPC, everything that's there execept the content of the wiki).

Please let us know if there's something not clear there...

Thanks,
Reinier aka BigChimp

[CephasAtheos]

That's an excellent link you provided, thank you so much!

Unlike much of the rest of the wiki in my browser, all the links in that document were UNfollowed, so I haven't even seen it before! Now I'm worried that I didn't look hard enough to be able to find that document - it answers nearly all my questions I posted. I seriously can't believe I didn't find it... I suspect I was expecting too technical answers, because the closest I got was generating chm docs using fpcdoc.

So thank you for your patient answer. 

I just wanted to say "thanks" before I head off and do what it says to do... But I will document any issues and bring them back if I can't solve them.

[CephasAtheos]

OK, that didn't hurt too much. But I'm still having the same problem. Well, it turns out that the problem varies, sometimes depending on which project source file I'm searching from, and sometimes it doesn't do anything, even in the same source file and cursor position that it previously worked fine on. See "Final Thoughts" below for some details.

I'm currently running FPC 2.7.1 and Lazarus 1.1, on MacOSX 10.7.4 (Lion), both are fresh from the svn repo this morning. Both FPC and Lazarus compiled without error and run as expected (except for the help issue). I apologise for even mentioning this, but all the directories and files have the default OS and make permissions applied, and the make was always done via sudo.

Lazarus is in ~/Sources/lazarus/.
The help stuff is in the default directories under that, i.e. either
{lazarus}/docs/html/, or
{lazarus}/docs/chm/ (and I've tried both). That is where lcl.chm and fcl.chm are located. I have also downloaded and copied a number of related chm files there as well, but for now those 'extras' are gone.

lhelp is built in and lives in {lazarus}/components/chmhelp/lhelp/

Here's what I see, with ChmHelpPkg 0.2 installed, and the following settings in the Tools|Options|Help|Help Options page :

• As built from scratch, ChmHelpPkg is installed, but the CHM Help Viewer fields are all empty (nothing in HelpExe, HelpExeParams, HelpFilesPath, Name, or Tag fields). However, the HelpLabel field is set to 'lazhelp' In this configuration, pressing Ctrl-F1 results in nothing at all. No popup, no disk activity, nothing at all.
  
• With HelpExe pointing to the lhelp binary, and the HelpFilesPath left blank (as per the document's recommendation for lazarus >0.99), I again get no help at all. My expectation, based on the documentation is that this should work, automatically looking for the appropriate chm files in either of the {lazarus}/docs/html or {lazarus}/docs/chm directories.
• With the same config as 2), but with {lazarus}/docs/html (or {lazarus}/docs/chm) (fully qualified paths) as the HelpFilesPath value, I get the following two dialogs, depending on what source file I'm searching in :
• "No help found for this topic" (regardless of the topic : e.g. 'color', 'dialog', 'font', 'format()', 'Application.ProcessMessages', in fact any valid topic seems to fail)
• "A Database entry exists, but no help can be found', with the text 'FPCKeyword_{help topic name}' at the bottom of the dialog.

Unfortunately, although #5 happened to me at least a dozen times, when I reverted the help options to the same settings (verified via screendumps I took at the time), that dialog has not been visible for the past 40 attempts. Go figure.

Final Thoughts
This has been a terribly frustrating exercise for me, and I'm extremely conscious of the "long post". I can't think of a way to post this information any other way - screenshots just don't do it. So while I'm struggling to understand what's happening on this system, I'm also keenly aware that I need to apologise for talking too damn much. For that, I'm sorry.

I was diligently trying to check and document every combination that I've tried over the past 2 days, trying to figure out why the help seemed to work when I first installed lazarus and what I'd done to break it.

Well, it turns out after 4 hours of testing, I've done nothing at all to cause it to change. It just sometimes works for a debugging session or coding session, and then when I come back to the same code, in the same file, on the same line, in the same word, without shutting down, closing the lid, or restarting lazarus, the help refuses to do anything. Or it throws up an error as documented in #4 and #5, sometimes even throwing up both dialogs one after the other! It just....depends.

During the time I was testing this, I touched nothing in any of the source directories, not even to copy or move files around. Nothing changed, except the way the help worked or it didn't.

Based on my experience recently with a very similar and just as bizarre problem with debugging, it's quite possible that there may be an IDE setting that affects the help, but which I'm either unaware, or have overlooked, and that most people think have nothing to do with the problem. So if any of this rings a bell, please let me know!

My next step is to completely remove both FPC and Lazarus, and install completely fresh binary distributions of FPC 2.6.0 and Lazarus 1.0RC1 again and see how that goes.

The reason I've been working with newer releases was because of a number of strange errors I was getting on MacOSX, which I eventually discovered were due to not setting up every new project as a bundle. So I persisted with the newer versions anyway, but I've had enough - I'm not up to speed nearly enough to be able to use the software and debug both the ide and the compiler, and learn the intricacies, and read through all the relevant documentation all at the same time. (I must be getting old... )

I've taken more than enough of everyone's time here. Thanks for the support, I really do appreciate you guys have a terrific community, and I'm glad to be part of it. I'll be even happier when I start to help cleaning up the home page and fixing some of the site problems "in my spare time".

Cheers,
Pete from ɹǝpun uʍop

[BigChimp]

Actually, Lazarus+lhelp on OSX may just be buggy.

Furthermore: the error you saw on no help available for keywords etc is fairly common as not all keywords have been documented.
I'm sure one of the links you saw indicated how to write help in XML format... but that's perhaps another story.

There were some stability problems with lhelp earlier. I would actually advise you to use later versions and report problems you find, even if intermittent. If confirmed (e.g. by other OSX users), they'll have to go into the bug tracker.

I just think you might be one of the few that run that particular system and take the trouble to investigate what's going on.

Myself, I run Laz on Windows, sometimes on Linux, but only very rarely on OSX so can't help you with the OSX specific aspects.

Regards,
BigChimp

[CephasAtheos]

Buggy? What's a bug? I thought they are all "undocumented features"!!

One of the most exciting things (for me) about FPC/Lazarus is the potential to be able to help with things like new documentation, figuring out problems on specific OSes, and improving the existing doco to help everyone else. But there's just so many opportunities! 

It can seem a bit overwhelming, actually, even if you just focus on the features that are most important to you. But, if you can climb the learning curve OK, then even little things will help.

The trick is to ensure that you find out if a problem is just a problem for you, or it's a problem for everyone else... and that can be a little frustrating at first. There's quite a bit of baggage that doesn't help either, but time and hopefully some learning and persistence will fix that.

So I really appreciate the help you guys provide to us new babes in the dark woods.

[CephasAtheos]

Hmm. I forgot to ask a really important question : How can I help to improve lhelp on Mac OS? Or at least determine if it is buggy on this platform? Is there any process for testing these external packages that might help to show if there's an error?

-Thanks!