Difference between revisions of "Add an Apple Help Book to your macOS app"

From Free Pascal wiki
Jump to navigationJump to search
m (Re-arrange sections)
(→‎See also: New section)
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
No professional macOS application should be without a functioning Apple Help Book. Unfortunately Apple make it harder than it should be for developers to create an Apple Help Book because their documentation is significantly out of date (2013 anyone?) and the Apple Help Viewer has undergone significant change in recent versions of the operating system. For the full details on how to add an Apple Help Book to your application, along with sample code, read on.
+
{{Platform only|macOS}}
 +
{{LanguageBar}}
  
−
====Main Menu====
+
No professional macOS application should be without a functioning Apple Help Book. Unfortunately Apple make it harder than it should be for developers to create an Apple Help Book because the official documentation is significantly out of date (2013 anyone?) and the Apple Help Viewer has undergone significant change in recent versions of the operating system. For the full details on how to add an Apple Help Book to your application, along with sample code, read on.
  
−
If you have not already done so, you need to add a TMainMenu component to your form, and create a TMenuItem named Help. A Search menu item will then automatically be added to your Help menu when you run your application.  
+
== Application Bundle Layout ==
 +
 
 +
A typical [[Application Bundle|application bundle]] with an Apple Help Book bundle should resemble this layout:
 +
 
 +
+-- MyApp.app/                                                  [application bundle]
 +
      |
 +
      +-- Contents/
 +
            |
 +
            +-- MacOS/
 +
            |    |
 +
            |    +-- MyApp                                      [application executable]
 +
            +-- Resources/
 +
            |    |
 +
            |    +-- MyApp.icns
 +
            |    |
 +
            |    +-- MyApp.help/                                [Help Book bundle]
 +
            |          |
 +
            |          +-- Contents/
 +
            |                |
 +
            |                +-- Resources/
 +
            |                |    |                             
 +
            |                |    +-- en.lproj/                [for English]
 +
            |                |    |    |
 +
            |                |    |    +-- help.helpindex    [generated by the macOS help indexer hiutil]
 +
            |                |    |    |
 +
            |                |    |    +-- index.html        [table of contents - do not index]
 +
            |                |    |    |
 +
            |                |    |    +-- page1.html
 +
            |                |    |    |
 +
            |                |    |    +-- ...
 +
            |                |    |    |
 +
            |                |    |    +-- pageN.html
 +
            |                |    |    |
 +
            |                |    |    +-- InfoPlist.strings  [see [[macOS_property_list_files#Localizing_an_Info.plist|Localizing an Info.plist]]]
 +
            |                |    |
 +
            |                |    +-- fr.lproj/                [for French]
 +
            |                |    |    |
 +
            |                |    |    +-- help.helpindex    [generated by the macOS help indexer hiutil]
 +
            |                |    |    |
 +
            |                |    |    +-- index.html        [table of contents - do not index]
 +
            |                |    |    |
 +
            |                |    |    +-- page1.html
 +
            |                |    |    |
 +
            |                |    |    +-- ...
 +
            |                |    |    |
 +
            |                |    |    +-- pageN.html
 +
            |                |    |    |
 +
            |                |    |    +-- InfoPlist.strings
 +
            |                |    |
 +
            |                |    +-- images/         
 +
            |                |    |    |
 +
            |                |    |    +-- chip3_32x32.ico    [icon used in help pages]
 +
            |                |   
 +
            |                +-- Info.plist                    [Help Book plist]
 +
            |
 +
            +-- Info.plist                                      [application plist]
 +
 
 +
== Main Menu==
 +
 
 +
If you have not already done so, you need to add a TMainMenu component to your application form, and create a TMenuItem with a caption name of "Help". macOS will then automatically add a Search menu option to your Help menu when you run your application.  
  
 
You also need to add a menu item to your Help menu to open your application help file at its table of contents. Once you have added the My App Help menu item, create an OnClick event handler containing the following code:
 
You also need to add a menu item to your Help menu to open your application help file at its table of contents. Once you have added the My App Help menu item, create an OnClick event handler containing the following code:
  
−
<source lang="pascal">
+
<syntaxhighlight lang="pascal">
 
...
 
...
 
Uses
 
Uses
Line 21: Line 81:
 
   pathCFStr := CFURLCopyFileSystemPath(pathRef, kCFURLPOSIXPathStyle);
 
   pathCFStr := CFURLCopyFileSystemPath(pathRef, kCFURLPOSIXPathStyle);
 
   CFStringGetPascalString(pathCFStr, @pathStr, 255, CFStringGetSystemEncoding());
 
   CFStringGetPascalString(pathCFStr, @pathStr, 255, CFStringGetSystemEncoding());
−
  CFRelease(pathRef);
 
−
  CFRelease(pathCFStr);
 
  
 
   Result := pathStr + '/Contents/Resources/';
 
   Result := pathStr + '/Contents/Resources/';
Line 32: Line 90:
 
begin
 
begin
 
   helpPath := GetResourcesPath + 'MyApp.help';
 
   helpPath := GetResourcesPath + 'MyApp.help';
−
   OpenDocument(helpPath );
+
   OpenDocument(helpPath);
 
end;
 
end;
−
</source>
+
</syntaxhighlight>
 +
 
 +
{{Tip|If you wish to '''NOT''' have macOS automatically add a Search option to your Help menu then, when you create the Help menu item, add a trailing space after Help in the menu item's caption property and the Search option will not show up in your application's Help menu.}}
 +
 
 +
== Application Info.plist ==
  
−
====Application Info.plist====
+
One of the most important files is the application [[macOS_property_list_files#Info.plist|Info.plist]]. Two keys need to be added or Spotlight will not index your help file. If your help file is not indexed, then even trying to open it will result in a perplexing "Not available" error page in the Apple Help Viewer. If you are using Xcode, then add these keys.
−
One of the most important files is the application Info.plist. Two keys need to be added or Spotlight will not index your help file. If you help file is not indexed, then even trying to open it will result in a perplexing "Not available" error page in the Apple Help Viewer. If you are using Xcode, then add these keys.
 
  
 
   Help Book directory name
 
   Help Book directory name
Line 44: Line 105:
 
The Help Book directory name should refer to the Help Book bundle name (eg MyApp.help). This directory should be located in the application bundle Contents/Resources directory. The Help Book identifier is simply the name of your help (eg My App Help).
 
The Help Book directory name should refer to the Help Book bundle name (eg MyApp.help). This directory should be located in the application bundle Contents/Resources directory. The Help Book identifier is simply the name of your help (eg My App Help).
  
−
If you are editing the Info.plist file in a text editor, then add these keys and value strings:
+
If you are editing the <tt>Info.plist</tt> file in a text editor, then add these keys and their value strings:
  
−
<source lang="text">
+
<syntaxhighlight lang="xml">
 
  <key>CFBundleHelpBookFolder</key>
 
  <key>CFBundleHelpBookFolder</key>
 
  <string>myapp.help</string>
 
  <string>myapp.help</string>
 
  <key>CFBundleHelpBookName</key>
 
  <key>CFBundleHelpBookName</key>
 
  <string>My App Help</string>
 
  <string>My App Help</string>
−
</source>
+
</syntaxhighlight>
  
−
====Help Book Info.plist====
+
== Help Book Info.plist ==
  
 
Below is a basic Help Book Info.plist for an application called "My App".
 
Below is a basic Help Book Info.plist for an application called "My App".
  
−
<source lang="pascal">
+
<syntaxhighlight lang="pascal">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
Line 90: Line 151:
 
</dict>
 
</dict>
 
</plist>
 
</plist>
−
</source>
+
</syntaxhighlight>
  
−
====Creating Help Book pages====
+
== Creating Help Book pages ==
  
−
Apple Help Book pages are simply HTML files. You need to create an index.html which is the table of contents for your application Help Book. You also need to ensure that this file is not indexed or it will show up in the Apple Help Viewer as a blank entry. You do this by adding the noindex meta tag to the file. Here is an example for "My App".
+
Apple Help Book pages are simply HTML files. You need to create an <tt>index.html</tt> page which is the table of contents for your application Help Book. You also need to ensure that this file is not indexed or it will show up in the Apple Help Viewer as a blank entry. There is also usually little point indexing pages which just contain links to other pages. You do this by adding the noindex meta tag to the file. Here is an example <tt>index.html</tt> page for "My App".
  
−
<source lang="html">
+
<syntaxhighlight lang="html" highlight=7>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
Line 117: Line 178:
 
</body>
 
</body>
 
</html>
 
</html>
−
</source>
+
</syntaxhighlight>
  
 
A sample page 1 for "My App" is set out below. Note:
 
A sample page 1 for "My App" is set out below. Note:
  
−
<source lang="html">
+
<syntaxhighlight lang="html">
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
Line 142: Line 203:
 
     </body>
 
     </body>
 
</html>
 
</html>
 +
</syntaxhighlight>
  
−
</source>
+
Once you have created the HTML pages for your Help Book, you need to index them. You do this from a Terminal using the macOS command line utility called <tt>hiutil</tt>. The man page (<tt>man hiutil</tt> in an Applications > Utilities > Terminal) details all the information you may ever need to know. A simple example to create an index file and include anchors:
−
 
 
−
Once you have created the HTML pages for your Help Book, you need to index them. You do this from a Terminal using the macOS utility called hiutil. The man page ("man hiutil" from a Terminal) details all the information you may ever need to know. A simple example:
 
  
−
<source lang="text">
+
<syntaxhighlight lang="text">
−
   hiutil -Caf helpindex.help .
+
   hiutil -Caf help.helpindex .
−
</source>
+
</syntaxhighlight>
  
−
This will index all the HTML files in the current directory and create the index file named helpindex.help in the same directory (do not omit the trailing full stop which signifies the current directory). It will also index any help anchors should you use them for contact-sensitive help; note that macOS applications rarely, if ever, implement context sensitive help.
+
This will index all the HTML files in the current directory and create the index file named helpindex.help in the same directory (do not omit the trailing full stop which signifies the current directory). It will also index any help anchors should you use them for context-sensitive help; note that macOS applications rarely, if ever, implement context-sensitive help.
  
−
An example of a help anchor is in the sample page 1 HTML file above; specifically the:
+
An example of a help anchor is included in the sample page 1 HTML file above; specifically the: <syntaxhighlight lang="html" inline><a name="Introduction"></a></syntaxhighlight> line.
−
<source lang="html"><a name="Introduction"></a></source>
 
  
−
Also note the <source lang="html"><meta name="robots" content="index, anchors" /></source> which ensures that the anchors are indexed along with the content.
+
Also note the <syntaxhighlight lang="html" inline><meta name="robots" content="index, anchors" /></syntaxhighlight> line which ensures that the anchors are indexed along with the file content.
  
−
====Updating cached Help Books====
+
== Updating cached Help Books ==
  
 
macOS caches an Apple Help Book after first use which can be perplexing when you are developing a Help Book and do not see your changes. The way to overcome this is to run the following shell script from a Terminal after a change:
 
macOS caches an Apple Help Book after first use which can be perplexing when you are developing a Help Book and do not see your changes. The way to overcome this is to run the following shell script from a Terminal after a change:
Line 171: Line 230:
 
Note: those are tildes (~) and not dashes (-) before /Library; this only affects the current user's Apple Help cache and Apple Help preferences, not the system-wide ones.
 
Note: those are tildes (~) and not dashes (-) before /Library; this only affects the current user's Apple Help cache and Apple Help preferences, not the system-wide ones.
  
−
====Bundle layouts====
+
== Sample MyApp with Help Book ==
  
−
A typical application bundle with an Apple Help Book bundle should resemble this layout:
+
The Apple Help Book facility can be frustrating the first time you set out to create an Apple Help Book. In an effort to make it a little easier, you can download a minimal "My App" example (blank form with Main Menu and Help Menu) on which the above examples have been based. Note: the first time you run MyApp.app and choose the Help Menu, no entries will show in the Search if you start typing "my app" apart from the menu items. Give it a few seconds and delete the "my app" in the search box and the two sample entries should show up in a few seconds after you again type "my".
  
−
+-- MyApp.app/                                                  [application bundle]
+
[[Image:MyAppMenu.png|300px|]]
−
      |
 
−
      +-- Contents/
 
−
            |
 
−
            +-- MacOS/
 
−
            |    |
 
−
            |    +-- MyApp                                      [application executable]
 
−
            +-- Resources/
 
−
            |    |
 
−
            |    +-- MyApp.icns
 
−
            |    |
 
−
            |    +-- MyApp.help/                                [Help Book bundle]
 
−
            |          |
 
−
            |          +-- Contents/
 
−
            |                |
 
−
            |                +-- Resources/
 
−
            |                |    |                             
 
−
            |                |    +-- en.lproj/                [for English]
 
−
            |                |    |    |
 
−
            |                |    |    +-- help.helpindex    [generated by the macOS help indexer hiutil]
 
−
            |                |    |    |
 
−
            |                |    |    +-- index.html  [table of contents - do not index]
 
−
            |                |    |    |
 
−
            |                |    |    +-- page1.html
 
−
            |                |    |    |
 
−
            |                |    |    +-- ...
 
−
            |                |    |    |
 
−
            |                |    |    +-- pageN.html
 
−
            |                |    |    |
 
−
            |                |    |    +-- InfoPlist.strings
 
−
            |                |    |
 
−
            |                |    +-- fr.lproj/                [for French]
 
−
            |                |    |    |
 
−
            |                |    |    +-- help.helpindex    [generated by the macOS help indexer hiutil]
 
−
            |                |    |    |
 
−
            |                |    |    +-- index.html        [table of contents - do not index]
 
−
            |                |    |    |
 
−
            |                |    |    +-- page1.html
 
−
            |                |    |    |
 
−
            |                |    |    +-- ...
 
−
            |                |    |    |
 
−
            |                |    |    +-- pageN.html
 
−
            |                |    |    |
 
−
            |                |    |    +-- InfoPlist.strings
 
−
            |                |    |
 
−
            |                |     +-- images/         
 
−
            |                 |    |    |
 
−
            |                |    |    +-- chip3_32x32.ico    [icon used in help pages]
 
−
            |                |   
 
−
            |                +-- Info.plist                    [Help Book plist]
 
−
            |
 
−
            +-- Info.plist                                      [application plist]
 
  
 +
Compiled MyApp: [https://www.sentry.org/lazarus/MyApp.zip Download] (2.2MB).
  
 +
Full project source code is available from [https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/laz_helpbook/ SourceForge].
  
−
====Sample MyApp with Help Book====
+
== See also ==
−
 
 
−
The Apple Help Book facility can be frustrating the first time you set out to create an Apple Help Book. In an effort to make it a little easier, you can download a minimal "My App" example (blank form with Main Menu and Help Menu) on which the above examples have been based. Note: the first time you run MyApp.app and choose the Help Menu, no entries will show in the Search if you start typing "my app" apart from the menu items. Give it a few seconds and delete the "my app" in the search box and the two sample entries should show up in a few seconds after you again type "my".
 
−
 
 
−
[[Image:MyAppMenu.png|300px|]]
 
  
−
MyApp Download (2.2MB): https://www.sentry.org/lazarus/MyApp.zip
+
* [[Application Bundle|macOS Application Bundle]]
 +
* [[macOS property list files]]
  
−
[[Category:Mac OS X]]
 
 
[[Category:macOS]]
 
[[Category:macOS]]
 
[[Category:Help and Docs]]
 
[[Category:Help and Docs]]
 
[[Category:Platform-sensitive development]]
 
[[Category:Platform-sensitive development]]
 +
[[Category:Code Snippets]]
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]

Latest revision as of 06:20, 28 December 2021

macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide

│ English (en) │

No professional macOS application should be without a functioning Apple Help Book. Unfortunately Apple make it harder than it should be for developers to create an Apple Help Book because the official documentation is significantly out of date (2013 anyone?) and the Apple Help Viewer has undergone significant change in recent versions of the operating system. For the full details on how to add an Apple Help Book to your application, along with sample code, read on.

Application Bundle Layout

A typical application bundle with an Apple Help Book bundle should resemble this layout: 

+-- MyApp.app/                                                  [application bundle]
     |
     +-- Contents/
           |
           +-- MacOS/
           |     |
           |     +-- MyApp                                      [application executable]
           +-- Resources/
           |     |
           |     +-- MyApp.icns
           |     |
           |     +-- MyApp.help/                                [Help Book bundle]
           |           |
           |           +-- Contents/
           |                 |
           |                 +-- Resources/
           |                 |     |                               
           |                 |     +-- en.lproj/                [for English]
           |                 |     |     |
           |                 |     |     +-- help.helpindex     [generated by the macOS help indexer hiutil]
           |                 |     |     |
           |                 |     |     +-- index.html         [table of contents - do not index]
           |                 |     |     |
           |                 |     |     +-- page1.html
           |                 |     |     |
           |                 |     |     +-- ...
           |                 |     |     |
           |                 |     |     +-- pageN.html
           |                 |     |     |
           |                 |     |     +-- InfoPlist.strings  [see Localizing an Info.plist]
           |                 |     |
           |                 |     +-- fr.lproj/                [for French] 
           |                 |     |     |
           |                 |     |     +-- help.helpindex     [generated by the macOS help indexer hiutil]
           |                 |     |     |
           |                 |     |     +-- index.html         [table of contents - do not index]
           |                 |     |     |
           |                 |     |     +-- page1.html
           |                 |     |     |
           |                 |     |     +-- ...
           |                 |     |     |
           |                 |     |     +-- pageN.html
           |                 |     |     |
           |                 |     |     +-- InfoPlist.strings 
           |                 |     |
           |                 |     +-- images/          
           |                 |     |     |
           |                 |     |     +-- chip3_32x32.ico    [icon used in help pages]
           |                 |     
           |                 +-- Info.plist                     [Help Book plist]
           |
           +-- Info.plist                                       [application plist]

Main Menu

If you have not already done so, you need to add a TMainMenu component to your application form, and create a TMenuItem with a caption name of "Help". macOS will then automatically add a Search menu option to your Help menu when you run your application.

You also need to add a menu item to your Help menu to open your application help file at its table of contents. Once you have added the My App Help menu item, create an OnClick event handler containing the following code: 

...
Uses
  LCLIntf, MacOSAll;
...
function GetResourcesPath(): string;
var
  pathRef: CFURLRef;
  pathCFStr: CFStringRef;
  pathStr: shortstring;
begin
  pathRef := CFBundleCopyBundleURL(CFBundleGetMainBundle());
  pathCFStr := CFURLCopyFileSystemPath(pathRef, kCFURLPOSIXPathStyle);
  CFStringGetPascalString(pathCFStr, @pathStr, 255, CFStringGetSystemEncoding());

  Result := pathStr + '/Contents/Resources/';
end;

procedure TForm1.MenuItem_MyAppHelpClick(Sender: TObject);
var
  helpPath: String;
begin
  helpPath := GetResourcesPath + 'MyApp.help';
  OpenDocument(helpPath);
end;
Note-icon.png

Tip: If you wish to NOT have macOS automatically add a Search option to your Help menu then, when you create the Help menu item, add a trailing space after Help in the menu item's caption property and the Search option will not show up in your application's Help menu.

Application Info.plist

One of the most important files is the application Info.plist. Two keys need to be added or Spotlight will not index your help file. If your help file is not indexed, then even trying to open it will result in a perplexing "Not available" error page in the Apple Help Viewer. If you are using Xcode, then add these keys. 

 Help Book directory name
 Help Book identifier

The Help Book directory name should refer to the Help Book bundle name (eg MyApp.help). This directory should be located in the application bundle Contents/Resources directory. The Help Book identifier is simply the name of your help (eg My App Help).

If you are editing the Info.plist file in a text editor, then add these keys and their value strings: 

 <key>CFBundleHelpBookFolder</key>
 <string>myapp.help</string>
 <key>CFBundleHelpBookName</key>
 <string>My App Help</string>

Help Book Info.plist

Below is a basic Help Book Info.plist for an application called "My App". 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>en</string>
	<key>CFBundleIdentifier</key>
	<string>org.sentry.myapp.help</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundlePackageType</key>
	<string>BNDL</string>
	<key>CFBundleShortVersionString</key>
	<string>22</string>
	<key>CFBundleSignature</key>
	<string>hbwr</string>
	<key>CFBundleVersion</key>
	<string>22</string>
	<key>HPDBookAccessPath</key>
	<string>index.html</string>
	<key>HPDBookIconPath</key>
	<string>images/chip3_32x32.ico</string>
	<key>HPDBookIndexPath</key>
	<string>help.helpindex</string>
	<key>HPDBookTitle</key>
	<string>My App Help</string>
	<key>HPDBookType</key>
	<string>3</string>
	<key>HPDBookUsesExternalViewer</key>
	<false/>
</dict>
</plist>

Creating Help Book pages

Apple Help Book pages are simply HTML files. You need to create an index.html page which is the table of contents for your application Help Book. You also need to ensure that this file is not indexed or it will show up in the Apple Help Viewer as a blank entry. There is also usually little point indexing pages which just contain links to other pages. You do this by adding the noindex meta tag to the file. Here is an example index.html page for "My App". 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>My App Table of Contents</title>
  <meta name="robots" content="noindex"> 
</head>
	
<body class="Normal">

  <H1><img style="margin: 0.0px 12.0px 0.0px 0.0px;" height="32.0" src="../images/chip3_32x32.ico" width="32.0" />Table of Contents</H1>

  <ul>
      <li id="Page1"><a href="Page1.html">Introduction</a></li>
      <li id="Page2"><a  href="Page2.html">Combo Boxes</a></li>
  </ul>
	  
</body>
</html>

A sample page 1 for "My App" is set out below. Note: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <title>Introduction</title>
        <meta name="robots" content="index, anchors" />
        <meta name="description" content="My App Introduction" />
        <meta name="keywords" content="introduction, operating system" />
    </head>
    <body>
        <a name="Introduction"></a>
        <H1><img style="margin: 0.0px 12.0px 0.0px 0.0px;" height="32.0" src="../images/chip3_32x32.ico" width="32.0" />Introduction</H1>
	<p>My App is a very useful application for all users of all ages!</p>
        <p>The macOS version of My App has been tested on macOS Sierra 10.12.6 , macOS High Sierra 10.13.6 and macOS Mojave 10.14.5.</p>
        <p>The Windows version of My App has been tested on Windows XP, Windows 7 and Windows 10.</p>

        <p>The latest version of the My App application is available from the web site at <a href="https://www.sentry.org/">www.sentry.org</a>.</p>
    </body>
</html>

Once you have created the HTML pages for your Help Book, you need to index them. You do this from a Terminal using the macOS command line utility called hiutil. The man page (man hiutil in an Applications > Utilities > Terminal) details all the information you may ever need to know. A simple example to create an index file and include anchors: 

  hiutil -Caf help.helpindex .

This will index all the HTML files in the current directory and create the index file named helpindex.help in the same directory (do not omit the trailing full stop which signifies the current directory). It will also index any help anchors should you use them for context-sensitive help; note that macOS applications rarely, if ever, implement context-sensitive help.

An example of a help anchor is included in the sample page 1 HTML file above; specifically the: <a name="Introduction"></a> line.

Also note the <meta name="robots" content="index, anchors" /> line which ensures that the anchors are indexed along with the file content.

Updating cached Help Books

macOS caches an Apple Help Book after first use which can be perplexing when you are developing a Help Book and do not see your changes. The way to overcome this is to run the following shell script from a Terminal after a change: 

#!/bin/sh
killall helpd
rm -rf ~/Library/Caches/com.apple.help*
rm -rf ~/Library/Preferences/com.apple.help*

Note: those are tildes (~) and not dashes (-) before /Library; this only affects the current user's Apple Help cache and Apple Help preferences, not the system-wide ones.

Sample MyApp with Help Book

The Apple Help Book facility can be frustrating the first time you set out to create an Apple Help Book. In an effort to make it a little easier, you can download a minimal "My App" example (blank form with Main Menu and Help Menu) on which the above examples have been based. Note: the first time you run MyApp.app and choose the Help Menu, no entries will show in the Search if you start typing "my app" apart from the menu items. Give it a few seconds and delete the "my app" in the search box and the two sample entries should show up in a few seconds after you again type "my".

MyAppMenu.png

Compiled MyApp: Download (2.2MB).

Full project source code is available from SourceForge.

See also

Retrieved from "http://wiki.freepascal.org/index.php?title=Add_an_Apple_Help_Book_to_your_macOS_app&oldid=148790"