Add an Apple Help Book to your macOS app: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(macOS only)
2	2
3	3		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.
4	4
5	5		## Application Bundle Layout
6	6
7	7		A typical [[Application Bundle\|application bundle]] with an Apple Help Book bundle should resemble this layout:
8	8
9		-	~~`+-- MyApp.app/ [application bundle]`\~~
10		-	~~` \|`\~~
11		-	~~` +-- Contents/`\~~
12		-	~~` \|`\~~
13		-	~~` +-- MacOS/`\~~
14		-	~~` \| \|`\~~
15		-	~~` \| +-- MyApp [application executable]`\~~
16		-	~~` +-- Resources/`\~~
17		-	~~` \| \|`\~~
18		-	~~` \| +-- MyApp.icns`\~~
19		-	~~` \| \|`\~~
20		-	~~` \| +-- MyApp.help/ [Help Book bundle]`\~~
21		-	~~` \| \|`\~~
22		-	~~` \| +-- Contents/`\~~
23		-	~~` \| \|`\~~
24		-	~~` \| +-- Resources/`\~~
25		-	~~` \| \| \| `\~~
26		-	~~` \| \| +-- en.lproj/ [for English]`\~~
27		-	~~` \| \| \| \|`\~~
28		-	~~` \| \| \| +-- help.helpindex [generated by the macOS help indexer hiutil]`\~~
29		-	~~` \| \| \| \|`\~~
30		-	~~` \| \| \| +-- index.html [table of contents - do not index]`\~~
31		-	~~` \| \| \| \|`\~~
32		-	~~` \| \| \| +-- page1.html`\~~
33		-	~~` \| \| \| \|`\~~
34		-	~~` \| \| \| +-- ...`\~~
35		-	~~` \| \| \| \|`\~~
36		-	~~` \| \| \| +-- pageN.html`\~~
37		-	~~` \| \| \| \|`\~~
38		-	~~` \| \| \| +-- InfoPlist.strings [see `[[macOS property list files\|Localizing an Info.plist]]`]`\~~
39		-	~~` \| \| \|`\~~
40		-	~~` \| \| +-- fr.lproj/ [for French] `\~~
41		-	~~` \| \| \| \|`\~~
42		-	~~` \| \| \| +-- help.helpindex [generated by the macOS help indexer hiutil]`\~~
43		-	~~` \| \| \| \|`\~~
44		-	~~` \| \| \| +-- index.html [table of contents - do not index]`\~~
45		-	~~` \| \| \| \|`\~~
46		-	~~` \| \| \| +-- page1.html`\~~
47		-	~~` \| \| \| \|`\~~
48		-	~~` \| \| \| +-- ...`\~~
49		-	~~` \| \| \| \|`\~~
50		-	~~` \| \| \| +-- pageN.html`\~~
51		-	~~` \| \| \| \|`\~~
52		-	~~` \| \| \| +-- InfoPlist.strings `\~~
53		-	~~` \| \| \|`\~~
54		-	~~` \| \| +-- images/ `\~~
55		-	~~` \| \| \| \|`\~~
56		-	~~` \| \| \| +-- chip3_32x32.ico [icon used in help pages]`\~~
57		-	~~` \| \| `\~~
58		-	~~` \| +-- Info.plist [Help Book plist]`\~~
59		-	~~` \|`\~~
60		-	~~` +-- Info.plist [application plist]`~~
	9	+	```
	10	+	+-- MyApp.app/ [application bundle]
	11	+	\|
	12	+	+-- Contents/
	13	+	\|
	14	+	+-- MacOS/
	15	+	\| \|
	16	+	\| +-- MyApp [application executable]
	17	+	+-- Resources/
	18	+	\| \|
	19	+	\| +-- MyApp.icns
	20	+	\| \|
	21	+	\| +-- MyApp.help/ [Help Book bundle]
	22	+	\| \|
	23	+	\| +-- Contents/
	24	+	\| \|
	25	+	\| +-- Resources/
	26	+	\| \| \|
	27	+	\| \| +-- en.lproj/ [for English]
	28	+	\| \| \| \|
	29	+	\| \| \| +-- help.helpindex [generated by the macOS help indexer hiutil]
	30	+	\| \| \| \|
	31	+	\| \| \| +-- index.html [table of contents - do not index]
	32	+	\| \| \| \|
	33	+	\| \| \| +-- page1.html
	34	+	\| \| \| \|
	35	+	\| \| \| +-- ...
	36	+	\| \| \| \|
	37	+	\| \| \| +-- pageN.html
	38	+	\| \| \| \|
	39	+	\| \| \| +-- InfoPlist.strings [see Localizing an Info.plist]
	40	+	\| \| \|
	41	+	\| \| +-- fr.lproj/ [for French]
	42	+	\| \| \| \|
	43	+	\| \| \| +-- help.helpindex [generated by the macOS help indexer hiutil]
	44	+	\| \| \| \|
	45	+	\| \| \| +-- index.html [table of contents - do not index]
	46	+	\| \| \| \|
	47	+	\| \| \| +-- page1.html
	48	+	\| \| \| \|
	49	+	\| \| \| +-- ...
	50	+	\| \| \| \|
	51	+	\| \| \| +-- pageN.html
	52	+	\| \| \| \|
	53	+	\| \| \| +-- InfoPlist.strings
	54	+	\| \| \|
	55	+	\| \| +-- images/
	56	+	\| \| \| \|
	57	+	\| \| \| +-- chip3_32x32.ico [icon used in help pages]
	58	+	\| \|
	59	+	\| +-- Info.plist [Help Book plist]
	60	+	\|
	61	+	+-- Info.plist [application plist]
	62	+	```
61	63
62	64		## Main Menu
63	65
64	66		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.
65	67
66	68		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:
67	69
68	70		``` pascal
69	71		...
70	72		Uses
71	73		LCLIntf, MacOSAll;
72	74		...
73	75		function GetResourcesPath(): string;
74	76		var
75	77		pathRef: CFURLRef;
76	78		pathCFStr: CFStringRef;
77	79		pathStr: shortstring;
78	80		begin
79	81		pathRef := CFBundleCopyBundleURL(CFBundleGetMainBundle());
80	82		pathCFStr := CFURLCopyFileSystemPath(pathRef, kCFURLPOSIXPathStyle);
81	83		CFStringGetPascalString(pathCFStr, @pathStr, 255, CFStringGetSystemEncoding());
82	84
83	85		Result := pathStr + '/Contents/Resources/';
84	86		end;
85	87
86	88		procedure TForm1.MenuItem_MyAppHelpClick(Sender: TObject);
87	89		var
88	90		helpPath: String;
89	91		begin
90	92		helpPath := GetResourcesPath + 'MyApp.help';
91	93		OpenDocument(helpPath);
92	94		end;
93	95		```
94	96
95	97		> 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.
96	98
97	99		## Application Info.plist
98	100
99	101		One of the most important files is the application [[macOS property list files\|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.
100	102
101		-	~~` Help Book directory name`\~~
102		-	~~` Help Book identifier`~~
	103	+	```
	104	+	Help Book directory name
	105	+	Help Book identifier
	106	+	```
103	107
104	108		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).
105	109
106	110		If you are editing the `Info.plist` file in a text editor, then add these keys and their value strings:
107	111
108	112		``` xml
109	113		<key>CFBundleHelpBookFolder</key>
110	114		<string>myapp.help</string>
111	115		<key>CFBundleHelpBookName</key>
112	116		<string>My App Help</string>
113	117		```
114	118
115	119		## Help Book Info.plist
116	120
117	121		Below is a basic Help Book Info.plist for an application called "My App".
118	122
119	123		``` pascal
120	124		<?xml version="1.0" encoding="UTF-8"?>
121	125		<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
122	126		<plist version="1.0">
123	127		<dict>
124	128		<key>CFBundleDevelopmentRegion</key>
125	129		<string>en</string>
126	130		<key>CFBundleIdentifier</key>
127	131		<string>org.sentry.myapp.help</string>
128	132		<key>CFBundleInfoDictionaryVersion</key>
129	133		<string>6.0</string>
130	134		<key>CFBundlePackageType</key>
131	135		<string>BNDL</string>
132	136		<key>CFBundleShortVersionString</key>
133	137		<string>22</string>
134	138		<key>CFBundleSignature</key>
135	139		<string>hbwr</string>
136	140		<key>CFBundleVersion</key>
137	141		<string>22</string>
138	142		<key>HPDBookAccessPath</key>
139	143		<string>index.html</string>
140	144		<key>HPDBookIconPath</key>
141	145		<string>images/chip3_32x32.ico</string>
142	146		<key>HPDBookIndexPath</key>
143	147		<string>help.helpindex</string>
144	148		<key>HPDBookTitle</key>
145	149		<string>My App Help</string>
146	150		<key>HPDBookType</key>
147	151		<string>3</string>
148	152		<key>HPDBookUsesExternalViewer</key>
149	153		<false/>
150	154		</dict>
151	155		</plist>
152	156		```
153	157
154	158		## Creating Help Book pages
155	159
156	160		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".
157	161
158	162		``` html
159	163		<?xml version="1.0" encoding="UTF-8"?>
160	164		<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
161	165
162	166		<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
163	167		<head>
164	168		<title>My App Table of Contents</title>
165	169		<meta name="robots" content="noindex">
166	170		</head>
167	171
168	172		<body class="Normal">
169	173
170	174		<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>
171	175
172	176		<ul>
173	177		<li id="Page1"><a href="Page1.html">Introduction</a></li>
174	178		<li id="Page2"><a href="Page2.html">Combo Boxes</a></li>
175	179		</ul>
176	180
177	181		</body>
178	182		</html>
179	183		```
180	184
181	185		A sample page 1 for "My App" is set out below. Note:
182	186
183	187		``` html
184	188		<?xml version="1.0" encoding="UTF-8"?>
185	189		<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">
186	190
187	191		<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
188	192		<head>
189	193		<title>Introduction</title>
190	194		<meta name="robots" content="index, anchors" />
191	195		<meta name="description" content="My App Introduction" />
192	196		<meta name="keywords" content="introduction, operating system" />
193	197		</head>
194	198		<body>
195	199		<a name="Introduction"></a>
196	200		<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>
197	201		<p>My App is a very useful application for all users of all ages!</p>
198	202		<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>
199	203		<p>The Windows version of My App has been tested on Windows XP, Windows 7 and Windows 10.</p>
200	204
201	205		<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>
202	206		</body>
203	207		</html>
204	208		```
205	209
206	210		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:
207	211
208	212		```text
209	213		hiutil -Caf help.helpindex .
210	214		```
211	215
212	216		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.
213	217
214	218		An example of a help anchor is included in the sample page 1 HTML file above; specifically the: `<a name="Introduction"></a>` line.
215	219
216	220		Also note the
217	221
218	222		line which ensures that the anchors are indexed along with the file content.
219	223
220	224		## Updating cached Help Books
221	225
222	226		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:
223	227
224	228		``` bash
225	229		#!/bin/sh
226	230		killall helpd
227	231		rm -rf ~/Library/Caches/com.apple.help*
228	232		rm -rf ~/Library/Preferences/com.apple.help*
229	233		```
230	234
231	235		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.
232	236
233	237		## Sample MyApp with Help Book
234	238
235	239		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".
236	240
237	241		![](/wiki-images/3/3a/MyAppMenu.png)
238	242
239	243		Compiled MyApp: [Download](https://www.sentry.org/lazarus/MyApp.zip) (2.2MB).
240	244
241	245		Full project source code is available from [SourceForge](https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/laz_helpbook/).
242	246
243	247		## See also
244	248
245	249		- [[Application Bundle\|macOS Application Bundle]]
246	250		- [[macOS property list files]]
247	251
248	252		---
249	253		From the Free Pascal wiki, page "Add an Apple Help Book to your macOS app", as it stood on 2021-12-28 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
250	254		Category: Code Snippets
251	255		Category: Help and Docs
252	256		Category: Platform-sensitive development
253	257		Category: Tutorials
254	258		Category: macOS

Back to history