docsetutil(1) BSD General Commands Manual docsetutil(1)
NAME
docsetutil -- Index, search, test, and package documentation sets
SYNOPSIS
docsetutil index [options] docsetpath
docsetutil search [options] docsetpath
docsetutil validate [options] docsetpath
docsetutil dump [options] docsetpath
docsetutil package [options] docsetpath
docsetutil help
DESCRIPTION
Documentation sets are special bundles which hold documentation that can
be loaded and searched by Xcode 3.0 and later.
The docsetutil tool performs several operations on documentation sets.
The tool's primary operations are generating the full-text and API
indexes for a documentation set bundle and then packaging up the documen-
tation set for distribution. When indexing, the tool uses one or more XML
files in the bundle's Resources folder to learn about the contents of the
documentation set. Once the indexes are generated, docsetutil can be
used to test and perform searches on those indexes.
COMMON OPTIONS
Most docsetutil verbs accept the following options:
-localization loc Perform the operation using a particular localization
in the documentation set bundle. Documentation sets
can be localized. This option tells docsetutil which
localization to load or create (when indexing). loc
is a string, such as en or ja , that matches an lproj
folder in the bundle.
-skip-text Do not perform the operation for the full-text index.
For example, when performing a search for an API sym-
bol, you may not want to also perform a full-text
search. Also, because generating the indexes can be
time consuming for large documentation sets, you may
not want to create both indexes while developing and
testing your own documentation set.
-skip-api Do not perform the operation for the API index. Simi-
lar to the -skip-text option.
-node nodePath Perform the operation only on the documents that
reside at or below a particular location in the docu-
mentation set's table-of-contents node hierarchy. The
syntax is a colon-separated list of node names identi-
fying how to navigate to the desired node, starting
with the root node. For example, -node 'Library
Documentation:Tutorial' would limit the operation to a
second-level node (and all of its descendents) named
"Tutorial" below the root node named "Library Documen-
tation". Because there is only one root node, its
inclusion is optional, so the previous example could
just be written as -node 'Tutorial'.
-verbose Print out additional information about the operation
being performed.
-debug Print out detailed information about the operation
being performed, which will likely be useful only when
trying to track down a failure.
VERBS
The operations supported by docsetutil are:
help Display minimal usage information for the tool. help accepts
no options.
index Convert the XML files describing the documentation set into a
binary form and generate a full-text index of the contents of
the documentation.
Common options: -localization, -skip-text, -skip-api, -node,
-verbose, and -debug.
Options:
-fallback path
Documentation sets can distribute their content
between the installed bundle and an alternative loca-
tion, usually a website. This optional value tells
docsetutil where to look (locally) for additional con-
tent that needs to be indexed.
-download
If a node uses an absolute URL for its landing page,
download that page and include it in the full-text
index.
search Search the full-text and API indexes for the specified term(s).
Common options: -localization, -skip-text, -skip-api, -node,
-verbose, and -debug.
Options:
-query str
The string to search for in both the full-text and API
index. This option is required when searching.
When searching the full-text index, str is treated as
a SearchKit query, so you can perform complex queries.
For example, you can use
-query 'Xcode && build*'
to search for all documents that mention Xcode and
also contain a word starting with "build".
When searching the API index, str is normally treated
as an exact, case-insensitive symbol name; no wild
cards are allowed. However, the API search can be con-
strained using the extended syntax
language/type/scope/name, where language is the lan-
guage in which the symbol is defined, type is a spe-
cial identifier that specifies the type of symbol for
which to search, scope is the namespace or container
(such as class) in which the symbol is defined, and
name is the actual name of the symbol. Furthermore,
this syntax performs a case-sensitive search for the
symbol scope and name. If the symbol has no scope
(ie, it is a global symbol), use '-'; if you don't
want to constrain the search with one of the terms use
'*'. To search for all Objective-C symbols defined
inside the NSWindow class, you can do:
-query 'Objective-C/*/NSWindow/*'
validate Examine the indexes for all the files referenced and verify
that those files actually exist in the documentation set (or
its fallback location).
Common options: -localization, -skip-text, -skip-api, -verbose,
and -debug.
Options:
-fallback path
Documentation sets can distribute their content
between the bundle and an alternative location, usu-
ally a website. This optional value tells docsetutil
where to look (locally) for additional content against
which the indexes should be checked. If you indexed
the documentation set with a fallback location, you
should also specify the same (or equivalent) location
when validating the indexes.
dump Print out the contents of the indexes. The table-of-contents
will be printed out in an indented style to reflect the struc-
ture; the set of files that were included in the full-text
index will be listed and grouped according to the document to
which each file belongs and the location at which each document
was found; and brief descriptions of all the symbols in the API
index will be listed.
Common options: -localization, -skip-text, -skip-api, -node,
-verbose, and -debug.
Options:
-toc-depth N
When printing out the table-of-content hierarchy,
descend only N levels deep. N of 0 means display only
the highest level node; do not descend into the hier-
archy. The default value is 5.
-text-depth N
When printing the files from the full-text index, dis-
play the full-text hierarchy of location, document,
and file to a particular depth. N of 0 means display
only the high-level locations (ie, default documenta-
tion set location, the fallback location, or a website
URL) at which nodes were indexed. N of 1 means fur-
ther display the relative path of each node indexed
inside each location. N of 2 means further display
the relative path of each file indexed inside each
node. The default value is 1.
package Generate an XAR archive of the documentation set appropriate
for downloading and installing by Xcode.
Common options: -verbose, and -debug.
Options:
-output packagePath
The path of the archive to create. If this option is
not used, the archive is written to the same folder as
the source documentation set with the same name as the
documentation set, except with the ".docset" extension
changed to ".xar".
-signid identityName
Include a digital signature in the archive using the
specified identity. Xcode will validate this signa-
ture before installing the documentation. docsetutil
searches the current user's keychains for an identity
with the given name.
-atom atomPath
Generate or update an entry about the documentation
set in an Atom feed file at the given location. If no
file exists at the location, yet, docsetutil will cre-
ate a new Atom file there with a single entry about
the documentation set. Xcode is able to subscribe to
RSS and Atom feeds to learn about and download updates
to documentation sets.
-download-url downloadURL
Use the given URL as the download location of the
package in the feed entry. If a new feed entry is
created, but this option is not specified, docsetutil
will use a placeholder in the entry, which you will
need to edit before publishing the feed.
Mac OS November 6, 2011 Mac OS
Mac OS X 10.7 - Generated Sun Nov 6 05:31:47 CST 2011