Difference between revisions of "Installing Help in the IDE"

From Lazarus wiki
Jump to navigationJump to search
m (undo revision 01B9BC by Mai (talk))
(29 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{Adding Kylix Help}}
+
'''Installing Help in the IDE''' for the Lazarus Runtime Library ([[RTL]]), Free Pascal, Free Component Library ([[FCL]]) and the Lazarus Component Library ([[LCL#LCL|LCL]]) and a number of associated  things.
  
=Installing CHM help for the RTL, FCL and LCL in the Lazarus IDE=
+
The installer or package may have already set up Help (or lhelp), depending on how you installed Lazarus. If it is not operational or it is out of date, this page will help you.
  
The installer or package may have already set up help for you. If this is not the case or if you have problems, please follow the instructions below.
+
==Changing the key for context sensitive help==
 +
 
 +
Some platforms do not pass the {{keypress|F1}} key to applications. The key can be changed in the menu under ''Tools > Options > Editor > Key Mappings > Help Menu Commands > Context sensitive help''.
 +
 
 +
==Installing CHM help (Lazarus 1.0 and later)==
  
==Installing CHM help (Lazarus 1.0RC1 and later)==
 
 
Note: these instructions use Windows path notation, but they also apply to other systems with minor changes.
 
Note: these instructions use Windows path notation, but they also apply to other systems with minor changes.
  
* Go to $(LazarusDir)\components\chmhelp\lhelp and see if lhelp.exe exists. Compile $(LazarusDir)\components\chmhelp\lhelp\lhelp.lpi if it doesn't. Although newer versions of Lazarus will compile lhelp if needed the first time you press F1, compiling the lpi yourself won't hurt.
+
* (This step is almost certainly unnecessary, jump to the next one) Go to <tt>$(LazarusDir)\components\chmhelp\lhelp</tt> and see if <tt>lhelp</tt> (Linux, FreeBSD, macOS) or <tt>lhelp.exe</tt> (Windows) exists. Compile $(LazarusDir)\components\chmhelp\lhelp\lhelp.lpi if it does not. Although newer versions of Lazarus will compile lhelp if needed the first time you press {{keypress|F1}}, compiling the lpi yourself won't hurt.
 +
 
 
* Make sure the package '''chmhelppkg''' is installed; it should be installed automatically in newer installers. See the menu Package->Install Packages. It should appear in the left column and is called something like '''ChmHelpPkg 0.2''' (version number may differ). If not, install it and rebuild Lazarus when prompted.
 
* Make sure the package '''chmhelppkg''' is installed; it should be installed automatically in newer installers. See the menu Package->Install Packages. It should appear in the left column and is called something like '''ChmHelpPkg 0.2''' (version number may differ). If not, install it and rebuild Lazarus when prompted.
* Go to $(LazarusDir)\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 the newest archive with the CHM files and unpack the files there.
 
* Additional troubleshooting step (e.g. useful if installing from Subversion): 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. $(LazarusDir)\components\chmhelp\lhelp\lhelp.exe)
 
** "HelpFilesPath" should be where you just put the CHM files. Leave it empty (recommended) to use the default, which includes $(LazarusDir)\docs\html and $(LazarusDir)\docs\chm.
 
  
Now context-sensitive help using F1 should work.
+
* Go to <tt>$(LazarusDir)\docs\chm</tt> and look for <tt>lcl.chm</tt> and <tt>fcl.chm</tt>. If they don't exist, go to http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/ and download the newest archive with the CHM files and unpack the files into that directory.
 +
 
 +
* Additional Troubleshooting step (eg useful if installing from Subversion): go to Tools > Options > "Help Options" and select the "CHM Help Viewer". Check its properties:
 +
** "HelpExe" should be empty in order to use the lhelp you just built (ie <tt>$(LazarusDir)\components\chmhelp\lhelp\lhelp.exe</tt>).
 +
** "HelpFilesPath" should be where you just put the CHM files. Leave it empty (recommended) to use the default, which includes <tt>$(LazarusDir)\docs\html and $(LazarusDir)\docs\chm</tt>.
 +
** If you use several versions of Lazarus, or like to build new ones from time to time, you can put your help files in a different directory, probably above $LazarusDir, and point HelpFilesPath to it.
 +
* If you are on '''Windows''' you can also use the Windows-internal help viewer:
 +
** "HelpExe" should be <tt>hh.exe</tt>
 +
** "HelpExeParams" must be <tt>"%s::%s"</tt> (WITH QUOTES, note the double colon).
 +
 
 +
Now context-sensitive help using {{keypress|F1}} should work.
 +
 
 +
=== Notes ===
 +
 
 +
* On some systems, lhelp has problems the second and subsequent time its activated. An easy solution is to close it after each use, it will startup very quickly the next time you need it.
  
==Installing CHM help (earlier versions than Lazarus 1.0RC1, e.g. Lazarus 0.9.30.4)==
+
* macOS: At least in  Lazarus 2.0.6, lhelp opens with an error (ignore by selecting OK) and blank contents. Use the Folder Open icon to navigate to the directory where you have put the help files and select the <tt>toc.chm</tt> file. The issue is resolved in Lazarus 2.0.10.
Older versions of Lazarus search for CHM files only in $(LazarusDir)\docs\html, not $(LazarusDir)\docs\chm. Therefore, please follow the instructions [[Installing Help in the IDE#Installing CHM help (Lazarus 1.0RC1 and later)|above]] with these differences:
+
 
* When downloading/extracting the CHM files, extract into <your-lazarus-directory>\docs\html\ instead of <your-lazarus-directory>\docs\chm\.
+
==Installing CHM help (earlier than Lazarus 1.0)==
* Note that an empty value (as recommended) in Environment Options/Help Options/CHM Help Viewer/HelpFilesPath will only check $(LazarusDir)/docs/html, not $(LazarusDir)/docs/chm
+
 
 +
Pre-1.0 versions of Lazarus search for CHM files only in <tt>$(LazarusDir)\docs\html</tt> and not in <tt>$(LazarusDir)\docs\chm</tt>. Therefore, please follow the instructions [[#Installing CHM help (Lazarus 1.0 and later)|above]] with these differences:
 +
 
 +
* When downloading/extracting the CHM files, extract into <tt>$(LazarusDir)\docs\html\</tt> and not <tt>$(LazarusDir)\docs\chm\</tt>.
 +
* Note that an empty value (as recommended) in Environment Options > Help Options > CHM Help Viewer > HelpFilesPath will only check <tt>$(LazarusDir)/docs/html</tt> and not <tt>$(LazarusDir)/docs/chm</tt>.
 +
 
 +
==Installing INF help in the IDE==
  
=Installing INF help in the IDE=
 
 
If you have help files in the INF format, please see [http://fpgui.sourceforge.net/docview_ide_integration.shtml "DocView IDE Integration"] for details on how to install such help in the Lazarus IDE. This option will use the fpGUI DocView help viewer to display and search the INF help files.
 
If you have help files in the INF format, please see [http://fpgui.sourceforge.net/docview_ide_integration.shtml "DocView IDE Integration"] for details on how to install such help in the Lazarus IDE. This option will use the fpGUI DocView help viewer to display and search the INF help files.
  
== Where to find INF help files? ==
+
=== Where to find INF help files? ===
 +
 
 
This [http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/ SourceForge] page contains links to download ZIP archives of the FPC Language Reference, RTL, FCL, LCL and fpGUI help in the INF format.
 
This [http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/ SourceForge] page contains links to download ZIP archives of the FPC Language Reference, RTL, FCL, LCL and fpGUI help in the INF format.
  
== Why choose INF help? ==
+
=== Why choose INF help? ===
 +
 
 
* INF help files are much smaller than other help formats, yet contain all of the same information. eg: LCL in HTML format is 187MB, LCL.CHM is 11.6MB, and LCL.INF is only 3.9MB. These sizes are all uncompressed sizes on your hard drive. So if you are limited to internet bandwidth, this is a good option to choose.
 
* INF help files are much smaller than other help formats, yet contain all of the same information. eg: LCL in HTML format is 187MB, LCL.CHM is 11.6MB, and LCL.INF is only 3.9MB. These sizes are all uncompressed sizes on your hard drive. So if you are limited to internet bandwidth, this is a good option to choose.
 
* fpGUI DocView in an optimised help viewer with many advanced features. For example:
 
* fpGUI DocView in an optimised help viewer with many advanced features. For example:
Line 39: Line 60:
 
** If you are visually impaired (or just prefer a specific font family), you can customise the fonts and font sizes to use when displaying help text.
 
** If you are visually impaired (or just prefer a specific font family), you can customise the fonts and font sizes to use when displaying help text.
  
=Installing the Kylix Help in the Lazarus IDE=
+
=== Why avoid INF help? ===
 +
 
 +
*  The INF files available in the above link are from 2010 - they are very out of date, and the INF format is not being regularly maintained for FPC/Lazarus help.
 +
 
 +
== Installing Kylix Help in the Lazarus IDE ==
  
For users who have a legal copy of Kylix, it is possible to add Kylix 3 context-sensitive help files to Lazarus IDE running on Linux x86. The benefit from those help files is that they are very detailed, and also contains the Object Pascal Language Reference help - most of which is applicable to FPC's Object Pascal syntax or the Lazarus LCL. Note that this uses the proprietary HyperHelp program, so is not portable to other platforms.
+
For users who have a legal copy of Kylix, it is possible to add Kylix 3 context-sensitive help files to Lazarus IDE running on Linux x86. The benefit from those help files is that they are very detailed, and also contain the Object Pascal Language Reference help - most of which is applicable to FPC's Object Pascal syntax or the Lazarus LCL. Note that this uses the proprietary HyperHelp program, so is not portable to other platforms.
  
 
For instructions, please see [[Kylix#Installing Kylix Help in the Lazarus IDE|instructions in the Kylix article]]
 
For instructions, please see [[Kylix#Installing Kylix Help in the Lazarus IDE|instructions in the Kylix article]]
  
=fpdoc entries of RTL and FCL=
+
==fpdoc entries of RTL and FCL==
  
 
The fpdoc entries for the FPC sources can be downloaded from svn:
 
The fpdoc entries for the FPC sources can be downloaded from svn:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
 
  cd /home/username/yourchoice/
 
  cd /home/username/yourchoice/
  svn co http://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs
+
  svn co https://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Add the path ''/home/username/yourchoice/fpcdocs'' to Tools / Options / Environment / FPDoc Editor
+
Add the path <tt>/home/username/yourchoice/fpcdocs</tt> to Tools > Options > Environment > FPDoc Editor
  
The source editor hints should now show help for TComponent.Name.
+
The source editor hints (eg as displayed by hovering your mouse over a function/procedure/property) should now show help for TComponent.Name.
  
 
[[Category:Lazarus]]
 
[[Category:Lazarus]]
 
[[Category:Help and Docs]]
 
[[Category:Help and Docs]]
 +
[[Category:CHM]]

Revision as of 01:05, 23 January 2022

Installing Help in the IDE for the Lazarus Runtime Library (RTL), Free Pascal, Free Component Library (FCL) and the Lazarus Component Library (LCL) and a number of associated things.

The installer or package may have already set up Help (or lhelp), depending on how you installed Lazarus. If it is not operational or it is out of date, this page will help you.

Changing the key for context sensitive help

Some platforms do not pass the F1 key to applications. The key can be changed in the menu under Tools > Options > Editor > Key Mappings > Help Menu Commands > Context sensitive help.

Installing CHM help (Lazarus 1.0 and later)

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

  • (This step is almost certainly unnecessary, jump to the next one) Go to $(LazarusDir)\components\chmhelp\lhelp and see if lhelp (Linux, FreeBSD, macOS) or lhelp.exe (Windows) exists. Compile $(LazarusDir)\components\chmhelp\lhelp\lhelp.lpi if it does not. Although newer versions of Lazarus will compile lhelp if needed the first time you press F1, compiling the lpi yourself won't hurt.
  • Make sure the package chmhelppkg is installed; it should be installed automatically in newer installers. See the menu Package->Install Packages. It should appear in the left column and is called something like ChmHelpPkg 0.2 (version number may differ). If not, install it and rebuild Lazarus when prompted.
  • Additional Troubleshooting step (eg useful if installing from Subversion): go to Tools > Options > "Help Options" and select the "CHM Help Viewer". Check its properties:
    • "HelpExe" should be empty in order to use the lhelp you just built (ie $(LazarusDir)\components\chmhelp\lhelp\lhelp.exe).
    • "HelpFilesPath" should be where you just put the CHM files. Leave it empty (recommended) to use the default, which includes $(LazarusDir)\docs\html and $(LazarusDir)\docs\chm.
    • If you use several versions of Lazarus, or like to build new ones from time to time, you can put your help files in a different directory, probably above $LazarusDir, and point HelpFilesPath to it.
  • If you are on Windows you can also use the Windows-internal help viewer:
    • "HelpExe" should be hh.exe
    • "HelpExeParams" must be "%s::%s" (WITH QUOTES, note the double colon).

Now context-sensitive help using F1 should work.

Notes

  • On some systems, lhelp has problems the second and subsequent time its activated. An easy solution is to close it after each use, it will startup very quickly the next time you need it.
  • macOS: At least in Lazarus 2.0.6, lhelp opens with an error (ignore by selecting OK) and blank contents. Use the Folder Open icon to navigate to the directory where you have put the help files and select the toc.chm file. The issue is resolved in Lazarus 2.0.10.

Installing CHM help (earlier than Lazarus 1.0)

Pre-1.0 versions of Lazarus search for CHM files only in $(LazarusDir)\docs\html and not in $(LazarusDir)\docs\chm. Therefore, please follow the instructions above with these differences:

  • When downloading/extracting the CHM files, extract into $(LazarusDir)\docs\html\ and not $(LazarusDir)\docs\chm\.
  • Note that an empty value (as recommended) in Environment Options > Help Options > CHM Help Viewer > HelpFilesPath will only check $(LazarusDir)/docs/html and not $(LazarusDir)/docs/chm.

Installing INF help in the IDE

If you have help files in the INF format, please see "DocView IDE Integration" for details on how to install such help in the Lazarus IDE. This option will use the fpGUI DocView help viewer to display and search the INF help files.

Where to find INF help files?

This SourceForge page contains links to download ZIP archives of the FPC Language Reference, RTL, FCL, LCL and fpGUI help in the INF format.

Why choose INF help?

  • INF help files are much smaller than other help formats, yet contain all of the same information. eg: LCL in HTML format is 187MB, LCL.CHM is 11.6MB, and LCL.INF is only 3.9MB. These sizes are all uncompressed sizes on your hard drive. So if you are limited to internet bandwidth, this is a good option to choose.
  • fpGUI DocView in an optimised help viewer with many advanced features. For example:
    • Loading help files (even multiple help files) are extremely fast
    • You can do full text searches across all help files.
    • Advanced search terms are possible.
    • Search results are based on an advanced algorithm that takes alternative spelling in consideration, and uses a ranking system to give you the best possible results.
    • Help files can be annotated (inline end-user comments can be added)
    • Help topics can be bookmarked, so they can easily be found again.
    • If you are visually impaired (or just prefer a specific font family), you can customise the fonts and font sizes to use when displaying help text.

Why avoid INF help?

  • The INF files available in the above link are from 2010 - they are very out of date, and the INF format is not being regularly maintained for FPC/Lazarus help.

Installing Kylix Help in the Lazarus IDE

For users who have a legal copy of Kylix, it is possible to add Kylix 3 context-sensitive help files to Lazarus IDE running on Linux x86. The benefit from those help files is that they are very detailed, and also contain the Object Pascal Language Reference help - most of which is applicable to FPC's Object Pascal syntax or the Lazarus LCL. Note that this uses the proprietary HyperHelp program, so is not portable to other platforms.

For instructions, please see instructions in the Kylix article

fpdoc entries of RTL and FCL

The fpdoc entries for the FPC sources can be downloaded from svn:

 cd /home/username/yourchoice/
 svn co https://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs

Add the path /home/username/yourchoice/fpcdocs to Tools > Options > Environment > FPDoc Editor

The source editor hints (eg as displayed by hovering your mouse over a function/procedure/property) should now show help for TComponent.Name.