Integrated Help TOC lazarus / 13-General ---------------------------------------------------------------------- TurboRascal · 2012-08-17 21:53 I'm really delighted how smoothly the chm help works out of the box in Lazarus 1.x -     all FPC and LCL documentation is included so practically every keyword gets proper context based help i lhelp. There is only one thing I see as a glitch, how the Help menu works. Namely, there is only the Online Help command which opens up a browser with a document linking to the web based documentation. There is no other Help command which would open the local help and it's the only help item which doesn't seem to be configurable for opening chm help. There already exists toc.chm which seems to me as a perfect candidate for opening from the help menu if one wishes to browse all the help chms... This puzzles me; why is it so, is there a workaround for it, and will it change anytime soon? ---------------------------------------------------------------------- marcov · 2012-08-17 22:32 Afaik the lazarus (IDE) help is not available as CHM. Only FPC help and LCL are available. gentoc (the script that creates the toc.chm index) , works with CHMs only. ---------------------------------------------------------------------- BigChimp · 2012-08-17 22:46 Marco, I don't see how your post answers Arny's question? Or perhaps I misunderstood him. Arny, do you mean: the help menu has Help/Online Help which opens a browser, but no other option, say Help/Offline Help, which opens the CHM help files? So the only way to open CHM files is by pressing F1? If that's your question, I think that's a very valid one. I'd expect a Help/Help menu (which could perhaps be implemented internally by the chmhelppkg package???). The Help/Online Help button should be below that... ---------------------------------------------------------------------- TurboRascal · 2012-08-17 23:13 Quote from: marcov on August 18, 2012, 12:32:38 amAfaik the lazarus (IDE) help is not available as CHM. Only FPC help and LCL are available. gentoc (the script that creates the toc.chm index) , works with CHMs only. Yes, there is no IDE help itself, but still it would be great to be able to open the existing FPC and LCL documentation which is available, and opening toc.chm which points to those documents from the Help menu would be quite nice. Quote from: BigChimp on August 18, 2012, 12:46:03 amMarco, I don't how your post answers Arny's question? Or perhaps I misunderstood him. Arny, do you mean: the help menu has Help/Online Help which opens a browser, but no other option, say Help/Offline Help, which opens the CHM help files? So the only way to open CHM files is by pressing F1? If that's you question, I think that's a very valid one. I'd expect a Help/Help menu (which could perhaps be implemented internally by the chmhelppkg package???). The Help/Online Help button should be below that... That's right, that is exactly the problem I'm addressing... BTW, toc.chm doesn't point to everything but LCL documentation, although it is titled "Free Pascal/Lazarus documentation overview"... It would be great if that link is also added and a Help menu command in IDE implemented to call it. ---------------------------------------------------------------------- BigChimp · 2012-08-17 23:24 Quote from: TurboRascal on August 18, 2012, 01:13:25 amBTW, toc.chm doesn't point to everything but LCL documentation, although it is titled "Free Pascal/Lazarus documentation overview"... It would be great if that link is also added and a Help menu command in IDE implemented to call it. See this bug: http://bugs.freepascal.org/view.php?id=22110 which I think should address what you want: i.e. pressing F1 or help should give you all help files not only the file associated with the keyword under the cursor when pressing F1. ---------------------------------------------------------------------- TurboRascal · 2012-08-18 00:48 Actually, I'm quite ok with the F1 behavior as context help, that works similar to the Delphi's help system. I just miss accessing a help index/contents from IDE, in any way, be it by a key combo or a menu command... ---------------------------------------------------------------------- BigChimp · 2012-08-18 05:20 I understand. My point was that having lhelp open all chm files will at least give you an overview of all available help files, whether you press F1 for context-sensitive help or a Help key combo or menu command, which shouldn't. This way, searching for concepts that may exist in another (or multiple) chm file is possible To me there isn't much difference between the toc.chm and directly showing the help files in lhelp as the former only shows the titles and a brief description of the files, but I can understand you'd want to see it.... and of course, opening toc.chm if not doing context- sensitive help makes sense. ---------------------------------------------------------------------- marcov · 2012-08-18 10:28 Quote from: BigChimp on August 18, 2012, 12:46:03 amMarco, I don't see how your post answers Arny's question? Or perhaps I misunderstood him. The point is that the current CHM help distribution is mainly crafted for the textmode IDE. Since the lookup function worked with lazarus too, it is now also integrated in lazarus. Progress on IDE help ( non FPC/LCL/fpdoc) has been slow. (if not outright dead) The bit about the TOC file is just background info. Toc.chm is the main TOC of the textmode IDE help (since it can't blend TOCs atm, this is the workaround). It is in the distribution for the textmode IDE, not for Lazarus Quote Arny, do you mean: the help menu has Help/Online Help which opens a browser, but no other option, say Help/Offline Help, which opens the CHM help files? So the only way to open CHM files is by pressing F1? I took Amy's question as "what would be needed to have an unified help menu", not as "can there be an additional item" ---------------------------------------------------------------------- TurboRascal · 2012-08-18 12:25 Quote from: marcov on August 18, 2012, 12:28:29 pmI took Amy's question as "what would be needed to have an unified help menu", not as "can there be an additional item" Well, that really seems the simplest solution to me - every other help item in Options (the context-sensitive ones) have the ability to open either a html or a chm file. Only the one called from the Help menu does not, so I guess it would be the quickest solution for all-chm help... ---------------------------------------------------------------------- BigChimp · 2012-08-18 12:39 So Arny, your point would presumably be: 1. change the Help/Online Help menu entry to Help/Help 2. let that open the toc.chm 3. let the toc.chm show not only all chms but also a link to the online help page Marco's point: the existing toc.chm is meant for the textmode IDE, so presumably a new toc.chm specific for Lazarus will need to be generated/distributed?!? Sorry, but I like some things to be spelled out... it helps prevent confusion... and... it helps make it something ripe for a bugreport then ---------------------------------------------------------------------- marcov · 2012-08-18 19:48 QuoteSorry, but I like some things to be spelled out... IMHO that is a commendable quality :-) Quote from: BigChimp on August 18, 2012, 02:39:14 pmMarco's point: the existing toc.chm is meant for the textmode IDE, so presumably a new toc.chm specific for Lazarus will need to be generated/distributed?!? The toc.chm generating tool could be extended to get a template passed by cmdline instead of hardcoding it. Then a different title/logo and additional link would be doable. ---------------------------------------------------------------------- TurboRascal · 2012-08-19 00:56 Quote from: BigChimp on August 18, 2012, 02:39:14 pmSo Arny, your point would presumably be: 1. change the Help/Online Help menu entry to Help/Help 2. let that open the toc.chm 3. let the toc.chm show not only all chms but also a link to the online help page Marco's point: the existing toc.chm is meant for the textmode IDE, so presumably a new toc.chm specific for Lazarus will need to be generated/distributed?!? Sorry, but I like some things to be spelled out... it helps prevent confusion... and... it helps make it something ripe for a bugreport then In essence that's it except that I'd be quite satisfied even if it shows the current toc.chm. It misses the link to lcl.chm though, so I guess that might be one change which would be desirable, albeit not necessary. Also I don't understand what online help page you refer to, there is only that html doc you get when you click Online Help, and it doesn't really show anything but links to the online versions of help already included in chms. In essence all that is needed is something similar to that page that actually points to the chms instead of the web, and the curent "online help" page would be unnecessary anymore. The only "online help" link in the Help menu could be one pointing to the wiki since that is the best online help source besides the references which are already in the chms... Of course, there could be another option of IDE help which is not present as Marco pointed out, but at some time someone will hopefully write something... So this might be my proposition for possible Help menu items: IDE Help/Manual - pointing to an IDE chm help or perhaps simply a PDF manualHelp contents - pointing to a toc.chm (current or a new one) which further points to the already present reference chmsOnline help - pointing to the Wiki ---------------------------------------------------------------------- BigChimp · 2012-08-19 02:02 Sure, a PDF manual. Mr Feature Creep Next, you'll want it searchable, cross platform, with context-sensitive help - hey, perhaps a bit like the chm viewer we have now (More seriously, having the chms as pdf would be nice - and they already exist for the FPC part of things. Presumably you could create an lcl.pdf using fpdoc - though on Linux only) Quote from: TurboRascal on August 19, 2012, 02:56:11 amAlso I don't understand what online help page you refer to, there is only that html doc you get when you click Online Help Yes, that's the one that appears after you press Help/Online Help, right? If you would like your proposition implemented, I'd suggest you raise an issue in the bugtracker... ---------------------------------------------------------------------- marcov · 2012-08-19 11:18 In my previous message the last line somehow was omitted. It was about http://svn.freepascal.org/cgi- bin/viewvc.cgi/trunk/gentoc.pp?root=docs&view=log being a simple script. It will also generate an entry for the LCL and lazutils (the latter since yesterday) when run in a directory with these in them. To make it more dynamical, one could expand it with the option of a template or something.  (now it constructs the html by hand, since it is so simple, but it could be done using a template) and a file with filename - descriptions to override the hardcoded ones. It is very, very simple code. --------- A LCL pdf is possible I think. But the major problem with LCL.* is not if it is searchable etc, but its contents. The last time I checked, not even all description per unit in the toplevel TOC were filled in. ---------------------------------------------------------------------- BigChimp · 2012-08-19 11:41 Quote from: marcov on August 19, 2012, 01:18:11 pmIn my previous message the last line somehow was omitted. It was about http://svn.freepascal.org/cgi- bin/viewvc.cgi/trunk/gentoc.pp?root=docs&view=log being a simple script. It will also generate an entry for the LCL and lazutils (the latter since yesterday) when run in a directory with these in them. To make it more dynamical, one could expand it with the option of a template or something.  (now it constructs the html by hand, since it is so simple, but it could be done using a template) and a file with filename - descriptions to override the hardcoded ones. It is very, very simple code. Nice. Let's hope it gets used by the Laz devs when generating the docs About the descriptions: you mention templates might be used, but couldn't you inspect the actual chm and extract the title from it in some way? Quote from: marcov on August 19, 2012, 01:18:11 pmA LCL pdf is possible I think. But the major problem with LCL.* is not if it is searchable etc, but its contents. The last time I checked, not even all description per unit in the toplevel TOC were filled in. I disagree with the Michael Van Canneyt school of "we don't add documentation to the PDF until the entire unit is documented". I'd rather have a partially filled document that invites people to add content than nothing. Of course, if the amount of content is extremely low, it would look a bit silly, but I'd think the lcl has a lot of documentation already. Additionally, even listing the bare function/class names has sense: because these names mean something, it will help people find functionality they need. That's actually one of my pet peeves with the FPC packages documentation: how is one to know there is e.g. a zip implementation if it isn't mentioned? (Disclaimer: below is one of those "it's wrong and it should be fixed just not by me because I don't know how or what to fix exactly" rants, I know. Sorry for that, and I do appreciate the hard work that has gone into help. It's just that I think it somehow should be easier) Apart from that, perhaps it really is time to modify the online help web pages so that users can add/edit missing documentation using their browser (as I think Michael suggested some time ago in one of the mailing lists). Presumably the chms can be changed to add a "go online to edit this page" link to the bottom of each help page... To me, despite the huge amount of work done on the fpdoc system, editing help and especially creating new help isn't that straightforward or intuitive. How to call the package name? Why is the help content called a descripton? Why can't you drag and drop links from e.g. code? Perhaps improvements in the Lazarus doc editor could also be made... such as: run your edits through fpdoc/xmllint to see if the resulting code makes sense - e.g. link typos are either not there or are on purpose (i.e. links to as yet undocumented features) ---------------------------------------------------------------------- TurboRascal · 2012-08-19 13:01 Quote from: BigChimp on August 19, 2012, 04:02:29 amSure, a PDF manual. Mr Feature Creep Next, you'll want it searchable, cross platform, with context-sensitive help - hey, perhaps a bit like the chm viewer we have now (More seriously, having the chms as pdf would be nice - and they already exist for the FPC part of things. Presumably you could create an lcl.pdf using fpdoc - though on Linux only) But there already IS lcl.chm file! Why make it a pdf when chm is already a better solution for class reference? I mentioned pdf only as an option for the _non-existing_ IDE manual, because it's easier to do - a quick and dirty job could be to create a document, slap many IDE screenshots in it and write short descriptions for everything on them... and here comes a basic IDE manual for the totally clueless I don't really see my propositions as a case of "creeping featuritis", the changes I propose are actually quite small (read it again ). Ok, perhaps I didn't write clearly enough... Quote from: marcov on August 19, 2012, 01:18:11 pm... It was about http://svn.freepascal.org/cgi- bin/viewvc.cgi/trunk/gentoc.pp?root=docs&view=log being a simple script. It will also generate an entry for the LCL and lazutils (the latter since yesterday) when run in a directory with these in them. ... So you say toc.chm should also link to lcl.chm if I understood correctly? The toc.chm I got with Lazarus does not... ---------------------------------------------------------------------- marcov · 2012-08-19 13:31 Amy:  I assume they took the 2.6.0 FPC documentation, added lcl.chm, but didn't regenerate the toc.chm file. Try http://www.stack.nl/~marcov/toc.chm  (also knows "lazutils.chm") ---------------------------------------------------------------------- TurboRascal · 2012-08-19 13:43 Quote from: marcov on August 19, 2012, 03:31:44 pmTry http://www.stack.nl/~marcov/toc.chm  (also knows "lazutils.chm") This one does link to the lcl.chm and lazutils.chm, thanks! It's strange that Lazarus comes with the file lacking that Lazarus-specific part... I've checked both in the 1.0RC1 release and trunk and it's the same. Perhaps a bug should be filed for this? Now, if only we had a Help menu item which would invoke that file, that's it. I guess that calls for another bug report? ---------------------------------------------------------------------- BigChimp · 2012-08-19 13:54 Quote from: TurboRascal on August 19, 2012, 03:01:56 pmQuote from: BigChimp on August 19, 2012, 04:02:29 amSure, a PDF manual. Mr Feature Creep Next, you'll want it searchable, cross platform, with context- sensitive help - hey, perhaps a bit like the chm viewer we have now (More seriously, having the chms as pdf would be nice - and they already exist for the FPC part of things. Presumably you could create an lcl.pdf using fpdoc - though on Linux only) Quote from: TurboRascal on August 19, 2012, 02:56:11 amAlso I don't understand what online help page you refer to, there is only that html doc you get when you click Online Help But there already IS lcl.chm file! Why make it a pdf when chm is already a better solution for class reference? I mentioned pdf only as an option for the _non-existing_ IDE manual, because it's easier to do - a quick and dirty job could be to create a document, slap many IDE screenshots in it and write short descriptions for everything on them... and here comes a basic IDE manual for the totally clueless I don't really see my propositions as a case of "creeping featuritis", the changes I propose are actually quite small (read it again ). Ok, perhaps I didn't write clearly enough... Quote from: marcov on August 19, 2012, 01:18:11 pm... It was about http://svn.freepascal.org/cgi- bin/viewvc.cgi/trunk/gentoc.pp?root=docs&view=log being a simple script. It will also generate an entry for the LCL and lazutils (the latter since yesterday) when run in a directory with these in them. ... So you say toc.chm should also link to lcl.chm if I understood correctly? The toc.chm I got with Lazarus does not... Uhm Arny, could you mess with the quote tags a bit please? QuoteBut there already IS lcl.chm file! Why make it a pdf when chm is already a better solution for class reference? I mentioned pdf only as an option for the _non-existing_ IDE manual So you meant that? Sorry, I must have skimmed that part. I mistakenly thought you'd meant LCL. There are, BTW already some manuals written. Motaz on this forum has written one. There's one in French which is fairly comprehensive. It just lacks somebody to slam them into the docs folder and perhaps pretty them up. See the wiki (documentation article I'd think) for details on links etc. ---------------------------------------------------------------------- BigChimp · 2012-08-19 13:57 Quote from: TurboRascal on August 19, 2012, 03:43:10 pmThis one does link to the lcl.chm and lazutils.chm, thanks! It's strange that Lazarus comes with the file lacking that Lazarus-specific part... I've checked both in the 1.0RC1 release and trunk and it's the same. Perhaps a bug should be filed for this? Now, if only we had a Help menu item which would invoke that file, that's it. I guess that calls for another bug report? Yes & yes ---------------------------------------------------------------------- TurboRascal · 2012-08-19 15:04 Quote from: BigChimp on August 19, 2012, 03:54:14 pmUhm Arny, could you mess with the quote tags a bit please? Messing with the quote tags above - done Quote from: BigChimp on August 19, 2012, 03:54:14 pmSo you meant that? Sorry, I must have skimmed that part. I mistakenly thought you'd meant LCL. Quote from: BigChimp on August 19, 2012, 03:54:14 pmThere are, BTW already some manuals written. Motaz on this forum has written one. There's one in French which is fairly comprehensive. It just lacks somebody to slam them into the docs folder and perhaps pretty them up. See the wiki (documentation article I'd think) for details on links etc. I'm not too much concerned wit the IDE help/manual ATM - after all, I (mostly) know how to use the IDE (until something occasionally changes) As everybody else, I'm currently more concerned with scratching an itch. To me, the most useful feature is the ability to easily access and browse programmer's technical references anytime from the help menu, so I'm proposing changes in that direction. Quote from: BigChimp on August 19, 2012, 03:57:50 pmYes & yes So, if no one objects or informs me there already are such reports posted, I'll post the bug reports... ---------------------------------------------------------------------- TurboRascal · 2012-08-19 19:32 Quote from: BigChimp on August 18, 2012, 07:20:49 amI understand. My point was that having lhelp open all chm files will at least give you an overview of all available help files, whether you press F1 for context-sensitive help or a Help key combo or menu command, which shouldn't. This way, searching for concepts that may exist in another (or multiple) chm file is possible To me there isn't much difference between the toc.chm and directly showing the help files in lhelp as the former only shows the titles and a brief description of the files, but I can understand you'd want to see it.... and of course, opening toc.chm if not doing context- sensitive help makes sense. When we're at it, just a comment for this since I saw you filed a bug report. For what I can see, the choice of the proper chm file in context help is handled the same way as in Delphi, by popping up the dialog asking you to choose if you need the same keyword from say, RTL or LCL... If I understand correctly what you're asking, that feature seems to be an already done solution... ---------------------------------------------------------------------- BigChimp · 2012-08-20 05:33 I think you don't understand correctly... If I press F1 on an LCL identifier, lhelp pops up with LCL help. Now I can't search for RTL or other concepts then as their CHMs don't open. This is not nice if you don't know if you are using the best keyword/tool for the job (example: don't know if it's documented already but there is DirectoryExistsUTF8 in Lazarus and DirectoryExists in FPC). I also can't browse other help files. I'd have to open the other chms manually in lhelp for this to happen.l ---------------------------------------------------------------------- Leledumbo · 2012-08-20 05:46 QuoteIf I press F1 on an LCL identifier, lhelp pops up with LCL help. I can't search for RTL or other concepts then as their CHMs don't open. I also can't browse other help files.That's weird... I even have my chm help settings empty and lhelp knows which chm to open... (not only for identifiers, but keywords are also supported) ---------------------------------------------------------------------- BigChimp · 2012-08-20 05:51 Quote from: Leledumbo on August 20, 2012, 07:46:48 amThat's weird... I even have my chm help settings empty and lhelp knows which chm to open... (not only for identifiers, but keywords are also supported) I'm not saying it doesn't know what chm file it should open. I edited the post above, hope it helps clarify what I mean. ---------------------------------------------------------------------- Leledumbo · 2012-08-20 06:19 OK, I see what you mean is since lhelp only opens 1 specific chm, you can't search for other things from currently opened lhelp. ---------------------------------------------------------------------- BigChimp · 2012-08-20 06:28 Yep. And you can't browse through them either. That might be partially worked around by opening toc.chm, but: 1. you'll have to first manually open the chms via the links there anyway 2. toc.chm doesn't get opened when starting lhelp (because the only way it is started now is with context-sensitive help which should end up e.g. in lcl.chm, never in toc.chm) Edit: hint: the patch in the issue works too well: it fixes the issue by opening all chm and all other help files (including online help) the first time the system starts lhep. I need help from somebody to strip it down to only opening the chms ---------------------------------------------------------------------- TurboRascal · 2012-08-20 07:34 Quote from: BigChimp on August 20, 2012, 08:28:34 amYep. And you can't browse through them either. That might be partially worked around by opening toc.chm, but: 1. you'll have to first manually open the chms via the links there anyway 2. toc.chm doesn't get opened when starting lhelp (because the only way it is started now is with context-sensitive help which should end up e.g. in lcl.chm, never in toc.chm) Ah, now I see... you actually want more or less the same thing as I do - the ability to open any help file at will. The only difference is that you want it when you already get context help open, while I want to get that from the menu. I guess both options would be welcome and make the help system closer to Delphi's... ---------------------------------------------------------------------- BigChimp · 2012-08-20 08:14 Yep. QuoteSo, if no one objects or informs me there already are such reports posted, I'll post the bug reports...Did you get a chance to file those reports - or were there already bug reports on this? Haven't seen anything related come up. ---------------------------------------------------------------------- TurboRascal · 2012-08-20 15:42 Quote from: BigChimp on August 20, 2012, 10:14:27 amDid you get a chance to file those reports - or were there already bug reports on this? Haven't seen anything related come up. I've checked on the mantis too, the only report the relevant search returns is yours. So I guess I'll file the reports...