[kde-doc-english] [kservice] docs/kbuildsycoca5: Update the kbuildsycoca5 man page
Alex Merry
alex.merry at kde.org
Sat Apr 12 11:17:50 UTC 2014
Git commit cec317d944ffb29c7d8c4b866e62a38c2dc7e79c by Alex Merry.
Committed on 01/04/2014 at 23:32.
Pushed by alexmerry into branch 'master'.
Update the kbuildsycoca5 man page
REVIEW: 117320
M +62 -110 docs/kbuildsycoca5/man-kbuildsycoca5.8.docbook
http://commits.kde.org/kservice/cec317d944ffb29c7d8c4b866e62a38c2dc7e79c
diff --git a/docs/kbuildsycoca5/man-kbuildsycoca5.8.docbook b/docs/kbuildsycoca5/man-kbuildsycoca5.8.docbook
index dc39386..0f70d3c 100644
--- a/docs/kbuildsycoca5/man-kbuildsycoca5.8.docbook
+++ b/docs/kbuildsycoca5/man-kbuildsycoca5.8.docbook
@@ -6,17 +6,26 @@
<refentry>
<refentryinfo>
-<title>&kde; User's Manual</title>
+<title>&kde; Frameworks: KService</title>
<author>
<firstname>Darian</firstname>
<surname>Lanx</surname>
+<contrib>Wrote the original documentation.</contrib>
<affiliation>
<address><email>content at openprojects.net</email></address>
</affiliation>
</author>
+<author>
+<firstname>Alex</firstname>
+<surname>Merry</surname>
+<contrib>Updated the documentation for &kde; Frameworks 5.</contrib>
+<affiliation>
+<address><email>alexmerry at kde.org</email></address>
+</affiliation>
+</author>
-<date>2010-01-04</date>
-<releaseinfo>1.1 (&kde; 4.4)</releaseinfo>
+<date>2014-04-01</date>
+<releaseinfo>5.0</releaseinfo>
</refentryinfo>
@@ -27,7 +36,7 @@
<refnamediv>
<refname><command>kbuildsycoca5</command></refname>
-<refpurpose>Rebuilds the system configuration cache.</refpurpose>
+<refpurpose>Rebuilds the KService desktop file system configuration cache.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -35,148 +44,121 @@
<cmdsynopsis>
<command>kbuildsycoca5</command>
-
-<group>
-<arg choice="opt">--nosignal</arg>
-<arg choice="opt">--noincremental</arg>
-<arg choice="opt">--checkstamps</arg>
-<arg choice="opt">--nocheckfiles</arg>
-<arg choice="opt">--global</arg>
-<arg choice="opt">--menutest</arg>
-<arg choice="opt">--track <replaceable>menu-id</replaceable></arg>
-<arg choice="opt">--help</arg>
-<arg choice="opt">--help-qt</arg>
-<arg choice="opt">--help-kde</arg>
-<arg choice="opt">--help-all</arg>
-<arg choice="opt">--author</arg>
-<arg choice="opt">-v, --version</arg>
-<arg choice="opt">--license</arg>
-</group>
+<group choice="opt" rep="repeat"><replaceable class="option">OPTIONS</replaceable></group>
</cmdsynopsis>
</refsynopsisdiv>
+
+
<refsect1>
<title>Description</title>
<para>
-<command>kbuildsycoca5</command>, as part of the &kde; command line
-tools ensures the proper operation of &kde; by reading in all the
-<literal role="extension">.desktop</literal>, <literal
-role="extension">.xml</literal>, and <literal
-role="extension">.protocol</literal> files to construct a binary
-database.
+<command>kbuildsycoca5</command> builds binary cache of the data stored in
+<literal role="extension">.desktop</literal> and MIME type <literal
+role="extension">.xml</literal> files that the KService framework uses to find
+plugins, applications and other services.
</para>
<para>
-&kde; itself accesses this database during operation to provide
-configuration information a program needs to run.
+The KService library uses this database to efficiently provide the information
+requested of it.
</para>
<para>
-This tool is part of ksycoca4, which stands for &kde; System
-Configuration Cache
+Users do not normally need to run this application directly; KService will run
+it if necessary, and if KDED is installed and running it will run
+<command>kbuildsyscoca5</command> whenever any of the files whose data is cached
+are changed.
</para>
-
</refsect1>
+
+
<refsect1>
<title>Options</title>
-
<variablelist>
-<varlistentry>
-<term><option>--nosignal</option></term>
-<listitem>
-<para>Do not signal applications to update</para>
-</listitem>
-</varlistentry>
<varlistentry>
-<term><option>--noincremental</option></term>
+<term><option>--checkstamps</option></term>
<listitem>
-<para>Disable incremental update, re-read everything</para>
+<para>Checks the file timestamps of the cache and the resource directories containing the data to be cached, and only updates the database if any of the resource directories have been modified more recently than the cache. Ignored if <option>--nocheckfiles</option> or <option>--noincremental</option> is set.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--checkstamps</option></term>
+<term><option>--global</option></term>
<listitem>
-<para>Check file timestamps</para>
+<para>Ignores any user-set files (in <varname>XDG_DATA_HOME</varname>). This is currently only supported on Unix systems.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--nocheckfiles</option></term>
<listitem>
-<para>Disable checking files (dangerous)</para>
+<para>Does not rebuild the cache unless something other than a change in the resource files requires it (such as the format of the cache changing, or <varname>XDG_DATA_DIRS</varname> being changed on a Unix system). Ignored if <option>--global</option> is set.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--global</option></term>
+<term><option>--noincremental</option></term>
<listitem>
-<para>Create global database</para>
+<para>Rather than using the existing cache and only updating the information that has changed or been added, start with an empty cache. Ignored if <option>--global</option> is set.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--menutest</option></term>
+<term><option>--nosignal</option></term>
<listitem>
-<para>Perform menu generation test run only</para>
+<para>Ordinarily, <command>kbuildsyscoca5</command> sends a signal over D-Bus once the cache is updated to all the applications that use KService so that they are always working with the latest information. This option suppresses that behaviour.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--track <replaceable>menu-id</replaceable></option></term>
+<term><option>--menutest</option></term>
<listitem>
-<para>Track menu id for debug purposes</para>
+<para>Test the generation of the application menu database. Does not actually build the cache.</para>
</listitem>
</varlistentry>
-<!-- this entire section from here to the end of the section could be an -->
-<!-- entity.. or maybe just so irrelevant as to leave it out -->
-
<varlistentry>
-<term><option>--help</option></term>
+<term><option>--testmode</option></term>
<listitem>
-<para>
-Show help about options
-</para>
+<para>Use the QStandardPaths "test mode" to avoid interfering with user data. This is intended for use with unit tests.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--help-qt</option></term>
+<term><option>--track <replaceable>menu-id</replaceable></option></term>
<listitem>
-<para>
-Show Qt specific options
-</para>
+<para>Track a menu ID for debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--help-kde</option></term>
+<term><option>--author</option></term>
<listitem>
<para>
-Show KDE specific options
+Show author information.
</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--help-all</option></term>
+<term><option>--license</option></term>
<listitem>
<para>
-Show all options
+Show license information.
</para>
</listitem>
</varlistentry>
<varlistentry>
-<term><option>--author</option></term>
+<term><option>-h, --help</option></term>
<listitem>
<para>
-Show author information
+Show a brief help text.
</para>
</listitem>
</varlistentry>
@@ -185,79 +167,49 @@ Show author information
<term><option>-v , --version</option></term>
<listitem>
<para>
-Show version information
+Show version information.
</para>
</listitem>
</varlistentry>
-<varlistentry>
-<term><option>--license</option></term>
-<listitem>
-<para>
-Show license information
-</para>
-</listitem>
-</varlistentry>
</variablelist>
-
</refsect1>
-<refsect1>
-<title>Usage</title>
-<para>
-A standard way to run this program is by simply specifying the following
-command at the prompt
-<userinput><command>kbuildsycoca5</command></userinput>
-</para>
-</refsect1>
<refsect1>
<title>Files</title>
-
<variablelist>
<varlistentry>
-<term><filename>/var/tmp/kde-$USER/ksycoca5</filename></term>
+<term><filename><varname>cachedir</varname>/ksycoca5</filename></term>
<listitem>
-<para>The default directory where the cache files are stored.</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
-</refsect1>
-
-<refsect1>
-<title>Environment Variables</title>
-<variablelist>
-<varlistentry>
-<term>$<envar>KDEDIRS</envar></term>
-<listitem>
-<para>Specifies which directories are part of the KDE
-installations</para>
+<para>The KService cache generated by <command>kbuildsycoca5</command>. On Unix systems, <varname>cachedir</varname> is typically <filename class="directory">~/.config</filename></para>
</listitem>
</varlistentry>
<varlistentry>
-<term>$<envar>KDESYCOCA</envar></term>
+<term><filename><varname>cachedir</varname>/ksycoca5stamp</filename></term>
<listitem>
-<para>Specifies the path to the sycoca database file</para>
+<para>The timestamp and other meta-information about the main cache file. On Unix systems, <varname>cachedir</varname> is typically <filename class="directory">~/.config</filename></para>
</listitem>
</varlistentry>
</variablelist>
-
</refsect1>
+
+
<refsect1>
<title>See Also</title>
+<para>
+<citerefentry><refentrytitle>kded5</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>kdeinit5</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+</para>
+</refsect1>
-<para>kdeinit4</para>
-</refsect1>
<refsect1>
<title>Bugs</title>
-
-<para>There are probably tons of bugs. Use <ulink url="http://bugs.kde.org">bugs.kde.org</ulink> to report them.</para>
-
+<para>There are probably tons of bugs. Use <ulink url="http://bugs.kde.org">KDE's bugtracker</ulink> to report them.</para>
</refsect1>
</refentry>
More information about the kde-doc-english
mailing list