manpagez: man pages & more
man docsetutil(1)
Home | html | info | man
docsetutil(1)             BSD General Commands Manual            docsetutil(1)


     docsetutil -- Index, search, test, and package documentation sets


     docsetutil index [options] docsetpath
     docsetutil search [options] docsetpath
     docsetutil validate [options] docsetpath
     docsetutil dump [options] docsetpath
     docsetutil package [options] docsetpath
     docsetutil help


     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.


     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.


     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.

               -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.
                        If a node uses an absolute URL for its landing page,
                        download that page and include it in the full-text

     search    Search the full-text and API indexes for the specified term(s).

               Common options: -localization, -skip-text, -skip-api, -node,
               -verbose, and -debug.

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

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

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

               -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
© 2000-2021
Individual documents may contain additional copyright information.