docs/desktoptojson/man-desktoptojson.8.docbook

0001 <?xml version="1.0" ?>
0002 <!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
0003   <!ENTITY % English "INCLUDE"><!-- change language only here -->
0004 ]>
0005
0006 <refentry lang="&language;">
0007
0008 <refentryinfo>
0009 <title>&kde-frameworks;: KService</title>
0010 <author>
0011 <firstname>Scarlett</firstname>
0012 <surname>Clark</surname>
0013 <contrib>Wrote the original documentation.</contrib>
0014 <affiliation>
0015 <address><email>scarlett@scarlettgatelyclark.com</email></address>
0016 </affiliation>
0017 </author>
0018 <author>
0019 <firstname>Alex</firstname>
0020 <surname>Merry</surname>
0021 <contrib>Edited the documentation.</contrib>
0022 <affiliation>
0023 <address><email>alexmerry@kde.org</email></address>
0024 </affiliation>
0025 </author>
0026
0027 <date>2014-04-02</date>
0028 <releaseinfo>Frameworks 5.0</releaseinfo>
0029 <productname>KDE Frameworks</productname>
0030
0031 </refentryinfo>
0032
0033
0034 <refmeta>
0035 <refentrytitle><command>desktoptojson</command></refentrytitle>
0036 <manvolnum>8</manvolnum>
0037 </refmeta>
0038
0039 <refnamediv>
0040 <refname><command>desktoptojson</command></refname>
0041 <refpurpose>Converts a <filename class="extension">.desktop</filename> file to a <filename class="extension">.json</filename> file.</refpurpose>
0042 </refnamediv>
0043
0044 <refsynopsisdiv>
0045 <title>Synopsis</title>
0046
0047 <cmdsynopsis>
0048 <command>desktoptojson</command>
0049 <arg choice="plain">--input <replaceable>DESKTOP-FILE</replaceable></arg>
0050 <arg choice="plain">--output <replaceable>JSON-FILE</replaceable></arg>
0051 </cmdsynopsis>
0052 <cmdsynopsis>
0053 <command>desktoptojson</command>
0054 <group choice="req">
0055 <arg choice="plain">--version</arg>
0056 <arg choice="plain">--help</arg>
0057 </group>
0058 </cmdsynopsis>
0059
0060 </refsynopsisdiv>
0061
0062
0063
0064
0065 <refsect1>
0066 <title>Description</title>
0067
0068 <para>The KService framework uses information contained in <filename class="extension">.desktop</filename> files to locate services, including plugins for Qt5-based applications and libraries. The Qt5 plugin system, however, uses &JSON; data embedded in the plugin itself. <command>desktoptojson</command> allows the information contained in a <filename class="extension">.desktop</filename> file to also be used as the embedded data for a Qt5 plugin by converting the <filename class="extension">.desktop</filename> file entries into &JSON; data.</para>
0069
0070 <para>The generated &JSON; data is a &JSON; object that maps the entries from the <literal>[Desktop Entry]</literal> group of the <filename class="extension">.desktop</filename> file. Any other groups are ignored. Most entries are just converted to &JSON; strings, but certain entries (such as <literal>Hidden</literal> and <literal>X-KDE-PluginInfo-EnabledByDefault</literal>) are known to be boolean values and converted as such, and similarly some (such as <literal>X-KDE-ServiceTypes</literal> and <literal>X-KDE-PluginInfo-Depends</literal>) are always converted to arrays of strings.</para>
0071 </refsect1>
0072
0073
0074
0075 <refsect1>
0076 <title>Options</title>
0077 <variablelist>
0078
0079 <varlistentry>
0080   <term><option>--input <replaceable>DESKTOP-FILE</replaceable></option></term>
0081 <listitem>
0082 <para>The <filename class="extension">.desktop</filename> file to convert.</para>
0083 </listitem>
0084 </varlistentry>
0085
0086 <varlistentry>
0087 <term><option>--output <replaceable>JSON-FILE</replaceable></option></term>
0088 <listitem>
0089 <para>The file to write the generated &JSON; data to.</para>
0090 </listitem>
0091 </varlistentry>
0092
0093 <varlistentry>
0094 <term><option>--help</option></term>
0095 <listitem>
0096 <para>Show a brief help text.</para>
0097 </listitem>
0098 </varlistentry>
0099
0100 <varlistentry>
0101 <term><option>--version</option></term>
0102 <listitem>
0103 <para>Show version information.</para>
0104 </listitem>
0105 </varlistentry>
0106
0107 </variablelist>
0108 </refsect1>
0109
0110
0111
0112 <refsect1>
0113 <title>Usage</title>
0114 <para>
0115 Most users of this utility will use the &cmake; macro
0116 <function>kservice_desktop_to_json</function> as part of the process of building
0117 a plugin.
0118 <programlisting language="cmake">
0119 <![CDATA[
0120 add_library(myplugin MODULE ${myplugin_SRCS})
0121 kservice_desktop_to_json(myplugin myplugin.desktop)
0122 ]]>
0123 </programlisting>
0124 This will produce the &JSON; file <filename>myplugin.json</filename>, which can be
0125 referenced from the <function>K_PLUGIN_FACTORY_WITH_JSON</function> or
0126 <function>Q_PLUGIN_METADATA</function> macros.
0127 </para>
0128 </refsect1>
0129
0130
0131
0132 <refsect1>
0133 <title>Bugs</title>
0134 <para>Please use <ulink url="https://bugs.kde.org">&kde;'s bugtracker</ulink> to report bugs.</para>
0135 </refsect1>
0136
0137 </refentry>
0138
0139
0140