.\"Modified from man(1) of FreeBSD, the NetBSD mdoc.template, and mdoc.samples. .\"See Also: .\"man mdoc.samples for a complete listing of options .\"man mdoc for the short list of editing options .\"/usr/share/misc/mdoc.template .Dd 05/22/2019 \" DATE .Dt HIUTIL 1 \" Program name and manual section number .Os Darwin .Sh NAME \" Section Header - required - don't modify .Nm hiutil .\" The following lines are read in generating the apropos(man -k) database. Use only key .\" words here as the database is built based on the words here and in the .ND line. .\".Nm Other_name_for_same_program(), .\" Use .Nm macro to designate other names for the documented program. .Nd utility for creating and examining Help Viewer indices .Sh SYNOPSIS \" Section Header - required - don't modify .Nm .Fl I Ar FORMAT .Fl Cf Ar file .Op Fl 1agv .Op Fl m Ar NUM .Op Fl s Ar LANG | PATH .Op Fl r Ar URL .Op Fl t Ar EXT .Ar dir \" Underlined argument - use .Ar anywhere to underline .Nm .Op Fl ADEFMST .Fl f Ar file .Sh DESCRIPTION \" Section Header - required - don't modify .Nm is used to create .helpindex files in the Latent Symantic Mapping (LSM) help format and .cshelpindex files in the Spotlight help format. It is also capable of examining Spotlight help indices using the modes listed below. To examine LSM indices, use a version of hiutil earlier than 2.0. .Pp Spotlight help indices are required in macOS Mojave or later. Spotlight indices are not compatible with versions earlier than macOS Mojave. .Pp The macOS help system automatically generates indices for local help books (see ~/Library/Caches/com.apple.helpd/). If your help content will be hosted remotely, you may want to manually generate an index to include with your remote help book. .Pp Creation, management, inspection, and information modes are listed directly below. .Pp .Sy Create and manage modes: .Bl -tag -width -indent \" Differs from above in tag removed .It Fl C, \-create Create an index file at the location you specify. You must provide both a directory of HTML files to index and a path to an output file, which will be overwritten if the ouput file already exists. .It Fl I, \-index-format Pass the index format type as either 'lsm' or 'corespotlight'. .It Fl P, -purge-caches Terminate Help Viewer and helpd if they are running and purge persisted Help Viewer related caches. .El .Pp .Sy Inspection and infomation modes: .Bl -tag -width -indent .It Fl A, \-list-anchors List the index's anchors separated by newlines. .It Fl D, \-list-anchor-dictionary List the index's anchor dictionary in XML. This includes a list of which files contain each anchor. .It Fl E, \-list-index-versions List the index's version dictionary in XML. It describes the system environment on which the index was created. .It Fl F, \-list-files List all the files included in the index, separated by newlines. You can use the \-v option with this mode to get titles and descriptions as well. .It Fl H, \-help Print out usage data. .It Fl M, \-list-min-term-length List the index's minimum term length. .It Fl S, \-list-stopwords List the index's stopwords separated by newlines. .It Fl T, \-list-terms List the terms indexed in each file. .It Fl V, \-version Print out the version of the tool. .El \" Ends the list .Sh GENERAL OPTIONS These can be used with any mode. .Bl -tag -width -indent .It Fl f, \-file Pass in the path to a file, either one to be created or one to be examined. .It Fl v, \-verbose Specify verbose output. Errors are always shown, but passing this argument once prints out warnings also. Passing the argument twice prints out errors, warnings, and progress notes. .El .Sh CREATE OPTIONS These can only be used with the create mode. .Bl -tag -width -indent \" Differs from above in tag removed .It Fl 1 Index one file at a time. The default is to use a queue to index several files in parallel. In combination with -vvv, this option can be useful in determining which file an error message is from. .It Fl a, \-anchors Specify index anchors. The default is to have none. Without this flag, there will be no anchor dictionary in the index. .It Fl e, \-exclude\fR=\fIPATTERN\fR Exclude files that match the specified pattern. Uses NSPredicate's MATCHES comparison method on the file's path relative to the directory being indexed. This option can be passed as many times as necessary, once per pattern. Exclusions take precedence over files included with \-i. .It Fl g, \-generate-summaries Generate summary text. This can be slow, but is useful if you don't have DESCRIPTION meta tags on some pages. .It Fl i, \-include\fR=\fIPATTERN\fR Include files that match the specified pattern. Uses NSPredicate's MATCHES comparison method on the file's path relative to the directory being indexed. The default patterns to index are ".htm" and ".html". If these defaults are undesirable, you may use \-e above to exclude them. This option can be passed as many times as necessary, once per pattern. .It Fl m, \-min-term-length\fR=\fINUM\fR Specify a minimum term length. The value can be 1, 2 or 3. It represents the number of consecutive tokens (typically a character) required for a term not to be ignored by the indexer. Recommended values are 3 for English and 1 for Chinese and other ideographic languages. .It Fl r, \-remote-url\fR=\fIURL\fR Include a remote URL with the index. This is only useful in Type 1 or Type 2 help books, because the URL is in the help bundle's Info.plist for Type 3 books. The URL should be fully qualified. For example: .Pp .Dl Ar https://www.mycompany.com/help_v1/ .It Fl s, \-stopwords\fR=\fILANG\fR|\fIPATH\fR Use stopwords. If you have your own stopwords .plist, provide that path. Otherwise, pass the two-character language code. For example: .Pp .Bl -tag -width 6n -offset indent -compact .It \f(CB en English .It \f(CB es Spanish .It \f(CB de German .It \f(CB fr French .It \f(CB hu Hungarian .It \f(CB it Italian .It \f(CB sv Swedish .El .It Fl l, \-locale\fR=\fILANG\fR Specify a locale for the index. Instead of having to boot into the locale to index, pass the language code or locale identifier here to index for that language. Example locale identifiers: .Pp .Bl -tag -width 6n -offset indent -compact .It \f(CB en_US US English .It \f(CB es_ES Spanish .It \f(CB de German .It \f(CB fr French .It \f(CB hu Hungarian .It \f(CB ru_RU Russian .El .El \" Ends the list .Sh FILES \" File used or created by the topic of the man page .Bl -tag -width -compact .It Pa /usr/share/hiutil/Stopwords.plist .El \" Ends the list .Pp List of default stopwords in different languages .Sh EXAMPLES Create .cshelpindex file from a directory of HTML help: .Pp .Dl hiutil \-I corespotlight \-Caf /pathto/myhelp.cshelpindex /pathto/myhelpdir/ .Pp Inspect the anchors in a .cshelpindex file: .Pp .Dl hiutil \-I corespotlight \-Af /pathto/myhelp.cshelpindex .Pp Verbosely inspect the terms in a .cshelpindex file: .Pp .Dl hiutil \-I corespotlight \-Tvf /pathto/myhelp.cshelpindex .Sh NOTES .Nm requires macOS 10.14 or later.