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

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

1

*(macOS only)*

2

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

5

## Application Bundle Layout

6

7

A typical [[Application Bundle|application bundle]] with an Apple Help Book bundle should resemble this layout:

8

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

```

63

64

## Main Menu

65

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.

67

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:

69

70

``` pascal

71

...

72

Uses

73

LCLIntf, MacOSAll;

74

...

75

function GetResourcesPath(): string;

76

var

77

pathRef: CFURLRef;

78

pathCFStr: CFStringRef;

79

pathStr: shortstring;

80

begin

81

pathRef := CFBundleCopyBundleURL(CFBundleGetMainBundle());

82

pathCFStr := CFURLCopyFileSystemPath(pathRef, kCFURLPOSIXPathStyle);

83

CFStringGetPascalString(pathCFStr, @pathStr, 255, CFStringGetSystemEncoding());

84

85

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

86

end;

87

88

procedure TForm1.MenuItem_MyAppHelpClick(Sender: TObject);

89

var

90

helpPath: String;

91

begin

92

helpPath := GetResourcesPath + 'MyApp.help';

93

OpenDocument(helpPath);

94

end;

95

```

96

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.

98

99

## Application Info.plist

100

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.

102

104

Help Book directory name

105

Help Book identifier

106

```

107

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).

109

110

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

111

112

``` xml

113

<key>CFBundleHelpBookFolder</key>

114

<string>myapp.help</string>

115

<key>CFBundleHelpBookName</key>

116

117

```

118

119

## Help Book Info.plist

120

121

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

122

123

``` pascal

124

<?xml version="1.0" encoding="UTF-8"?>

125

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

126

127

<dict>

128

<key>CFBundleDevelopmentRegion</key>

129

130

<key>CFBundleIdentifier</key>

131

<string>org.sentry.myapp.help</string>

132

<key>CFBundleInfoDictionaryVersion</key>

133

134

<key>CFBundlePackageType</key>

135

136

<key>CFBundleShortVersionString</key>

137

138

<key>CFBundleSignature</key>

139

140

<key>CFBundleVersion</key>

141

142

<key>HPDBookAccessPath</key>

143

<string>index.html</string>

144

<key>HPDBookIconPath</key>

145

<string>images/chip3_32x32.ico</string>

146

<key>HPDBookIndexPath</key>

147

<string>help.helpindex</string>

148

<key>HPDBookTitle</key>

149

150

<key>HPDBookType</key>

151

152

<key>HPDBookUsesExternalViewer</key>

153

154

</dict>

155

</plist>

156

```

157

158

## Creating Help Book pages

159

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".

161

162

``` html

163

<?xml version="1.0" encoding="UTF-8"?>

164

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">

165

166

167

<head>

168

<title>My App Table of Contents</title>

169

170

</head>

171

172

173

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>

175

176

<ul>

177

<li id="Page1"><a href="Page1.html">Introduction</a></li>

178

<li id="Page2"><a href="Page2.html">Combo Boxes</a></li>

179

</ul>

180

181

</body>

182

</html>

183

```

184

185

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

186

187

``` html

188

<?xml version="1.0" encoding="UTF-8"?>

189

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN">

190

191

192

<head>

193

<title>Introduction</title>

194

195

196

197

</head>

198

<body>

199

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>

201

<p>My App is a very useful application for all users of all ages!</p>

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>

203

<p>The Windows version of My App has been tested on Windows XP, Windows 7 and Windows 10.</p>

204

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>

206

</body>

207

</html>

208

```

209

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:

211

212

```text

213

hiutil -Caf help.helpindex .

214

```

215

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.

217

218

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

219

220

Also note the

221

222

line which ensures that the anchors are indexed along with the file content.

223

224

## Updating cached Help Books

225

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:

227

228

``` bash

229

#!/bin/sh

230

killall helpd

231

rm -rf ~/Library/Caches/com.apple.help*

232

rm -rf ~/Library/Preferences/com.apple.help*

233

```

234

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.

236

237

## Sample MyApp with Help Book

238

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".

240

241

![](/wiki-images/3/3a/MyAppMenu.png)

242

243

Compiled MyApp: [Download](https://www.sentry.org/lazarus/MyApp.zip) (2.2MB).

244

245

Full project source code is available from [SourceForge](https://sourceforge.net/p/lazarus-wiki-projects/code/ci/master/tree/laz_helpbook/).

246

247

## See also

248

249

- [[Application Bundle|macOS Application Bundle]]

250

- [[macOS property list files]]

251

252

---

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).*

254

Category: Code Snippets

255

Category: Help and Docs

256

Category: Platform-sensitive development

257

Category: Tutorials

258

Category: macOS