Difference between revisions of "Installing Help in the IDE"

From Free Pascal wiki
Jump to navigationJump to search
(→‎Installing INF Help in the IDE: - improved general description of this section)
(32 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 Component Library ([[FCL]]) and the Lazarus Component Library ([[LCL#LCL|LCL]]).
  
=Installing CHM Help for The RTL, FCL and LCL in the Lazarus IDE=
+
The installer or package will probably have already set up Help. If this is not the case, or in case of problems, follow these instructions.
  
==If you are using Lazarus from a package/installer==
+
==Changing the shortcut for context sensitive help==
The installer or package may have already set up help for you. If this is not the case, please follow the instructions under the "installing from subversion" section.
+
Some platforms do not pass the F1 or Ctrl-F1 keys to applications. The key can be changed in the menu under ''Tools / Options / Editor / Key Mappings / Help Menu Commands / Context sensitive help''.
  
==If you are using Lazarus from Subversion==
+
==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.
 +
* Go to $(LazarusDir)\components\chmhelp\lhelp and see if lhelp.exe 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 (OS X: Ctrl-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.
 +
* 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 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 (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.
 +
* If you are on '''Windows''' you can also use the Windows-internal help viewer:
 +
** "HelpExe" should be <code>hh.exe</code>
 +
** "HelpExeParams" must be <code>"%s::%s"</code> (WITH QUOTES, note the double colon).
  
The Lazarus help files can be installed following these easy steps:
+
Now context-sensitive help using F1 (OS X: Ctrl-F1) should work.
<ol>
 
<li>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.</li>
 
<li>Open the project lazarus/components/chmhelp/lhelp/lhelp.lpi</li>
 
<li>Build this project</li>
 
<li>Download the latest stable Lazarus CHM help files from http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/</li>
 
<li>Copy all CHM files to lazarus/docs/html</li>
 
<li>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
 
:"HelpFilesPath" should be, where you put the CHM files</li>
 
</ol>
 
Now context sensitive help using F1 should work.
 
  
=Installing INF Help in the IDE=
+
==Installing CHM help (earlier versions than Lazarus 1.0, e.g. Lazarus 0.9.30.4)==
 +
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 $(LazarusDir)\docs\html\ instead of $(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, not $(LazarusDir)/docs/chm
  
 +
=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.
  
=Installing the Kylix Help in the Lazarus IDE=
+
== 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.
  
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.
+
== 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.
  
==The files needed from Kylix3==
+
== 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.
  
Since many of you have been coding in Kylix, you probably already have these files lying around some place. I suspect that the help system from the free version of Kylix may work as well. These are the files and directories needed from the ''${HOME}/kylix/help'' directory:<br>
+
=Installing Kylix Help in the Lazarus IDE=
<tt><code><br>
 
bin/          k3clx.hlp    k3dbd.cnt    k3.hlp
 
foo            k3.cnt        k3dbd.fts    k3indy.cnt
 
foo~          k3copts.cnt  k3dbd.hlp    k3indy.fts
 
hhintro.txt    k3copts.fts  k3dbx.cnt    k3indy.hlp
 
hoh.cnt        k3copts.hlp  k3dbx.fts    k3iota.cnt
 
hoh.fts        k3crtl.cnt    k3dbx.hlp    k3iota.fts
 
hoh.hlp        k3crtl.fts    k3derrs.cnt  k3iota.hlp
 
hyperhelp.sh*  k3crtl.hlp    k3derrs.fts  k3new.cnt
 
k3.als        k3ctools.cnt  k3derrs.hlp  k3new.fts
 
k3cerrs.cnt    k3ctools.fts  k3dlr.cnt    k3new.hlp
 
k3cerrs.fts    k3ctools.hlp  k3dlr.fts    k3prog.cnt
 
k3cerrs.hlp    k3cw.cnt      k3dlr.hlp    k3prog.fts
 
k3clr.cnt      k3cw.fts      k3dopts.cnt  k3prog.hlp
 
k3clr.fts      k3cw.hlp      k3dopts.fts  lib/
 
k3clr.hlp      k3dap.cnt    k3dopts.hlp
 
k3clx.cnt      k3dap.fts    k3.ftg
 
k3clx.fts      k3dap.hlp    k3.fts
 
<br>
 
</code></tt>
 
<br>
 
Most of the above files may not pertain to Lazarus, such as the k3c* files which relate to C++, but they are harmless to keep around.
 
  
The bare minimum files needed for the context help are these:
+
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.
<tt><code><br>
 
bin/          k3.als    k3clx.fts  k3.cnt  k3.fts  lib/
 
hyperhelp.sh*  k3clx.cnt  k3clx.hlp  k3.ftg  k3.hlp
 
<br></code></tt>
 
  
==The hyperhelp.sh script==
+
For instructions, please see [[Kylix#Installing Kylix Help in the Lazarus IDE|instructions in the Kylix article]]
We do need to dress up the default help script provided with Kylix so that it will work as a standalone app under X.  Note that the last line of the script sets some missing rendering parameters.  Also note the -geometry which positions the window and sets its size.
 
 
 
<syntaxhighlight lang="bash">
 
#!/bin/bash
 
HHHOME="${HOME}/Lazarus/DelphiHelp"
 
XPPATH="${HHHOME}/xprinter"
 
LANG=en_US
 
LC_ALL=en_US
 
locale=${LC_ALL:-${LC_CTYPE:-${LANG:-"C"}}}
 
LD_LIBRARY_PATH+="lib/locale/"${locale}":lib:"
 
XAPPLRESDIR="app-defaults"
 
NLSPATH="lib/locale/%L/%N.cat"
 
export XPPATH HHHOME LANG LC_ALL LD_LIBRARY_PATH XAPPLRESDIR NLSPATH
 
cd $HHHOME
 
bin/hyperhelp k3clx.hlp -m AL\($1,3,,main\)\
 
    -s 0 -d 32159 -display :0.0 -geometry 600x500+100+100 -w
 
</syntaxhighlight>
 
 
 
==My directory tree==
 
This is where I have placed the Kylix Help file directory.  It is under my installation of Lazarus in the user home directory.  The hyperhelp.sh script refers to these locations.
 
 
 
<pre>
 
/home/tom/Lazarus/DelphiHelp/
 
|-- bin
 
`-- lib
 
  `-- locale
 
      |-- de_DE
 
      |-- fr_FR
 
      |-- ja_JP.SJIS
 
      |-- ja_JP.eucJP
 
      `-- ja_JP.eucjp
 
</pre>
 
 
 
==Custom Tool setup in IDE==
 
Finally, set up the new custom tool within Lazarus from the menu 'Tools|Configure custom tools|Add'.  Replace '/home/tom/' with your user home directory path.  This has to be an absolute path to the hyperhelp.sh script.
 
 
 
[[Image:edittool.png]]
 
 
 
==In summary==
 
Just place your cursor in the edit window on the word you want to find help for and press {{keypress|Ctrl|F1}}. The Kylix help will then open up the context sensitive help page for that keyword.
 
  
 
=fpdoc entries of RTL and FCL=
 
=fpdoc entries of RTL and FCL=
Line 113: Line 61:
 
Add the path ''/home/username/yourchoice/fpcdocs'' to Tools / Options / Environment / FPDoc Editor
 
Add the path ''/home/username/yourchoice/fpcdocs'' to Tools / Options / Environment / FPDoc Editor
  
The source editor hints should now show help for TComponent.Name.
+
The source editor hints (e.g. 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 22:35, 27 February 2019

Installing Help in the IDE for the Lazarus Runtime Library (RTL), Free Component Library (FCL) and the Lazarus Component Library (LCL).

The installer or package will probably have already set up Help. If this is not the case, or in case of problems, follow these instructions.

Changing the shortcut for context sensitive help

Some platforms do not pass the F1 or Ctrl-F1 keys 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.

  • Go to $(LazarusDir)\components\chmhelp\lhelp and see if lhelp.exe 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 (OS X: Ctrl-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.
  • 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 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 (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.
  • 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 (OS X: Ctrl-F1) should work.

Installing CHM help (earlier versions than Lazarus 1.0, e.g. Lazarus 0.9.30.4)

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

  • When downloading/extracting the CHM files, extract into $(LazarusDir)\docs\html\ instead of $(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, 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 http://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs

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

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