<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>

<section id="sect-Metadata-InputMethod">
	<title>Input Methods</title>

	<section id="spec-imdata-introduction">
		<title>Introduction</title>
		<para>
			It is a nice feature for a software center to allows users the installation of additional input methods.
			This metainfo specification describes how metadata about input methods should be structured.
		</para>
		<para>
			Software components providing an input method can ship one or more files in
			<filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
		</para>
		<para>
			Input method metadata files can – just like all other metainfo files – be translated. See the section about translation for more information.
		</para>
	</section>

	<section id="spec-imdata-example">
		<title>Example file</title>
		<para>
			The input method metainfo file should look like this:
		</para>
		<programlisting language="XML">
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<component type="inputmethod">
  <id>com.github.ibus.mathwriter-ibus.db</id>
  <metadata_license>FSFAP</metadata_license>
  <name>Mathwriter</name>
  <summary>Math symbols input method</summary>
  <description>
    <p>
      The input method is designed for entering mathematical symbols.
    </p>
    <p>
      Input methods are typing systems allowing users to input complex languages.
      They are necessary because these contain too many characters to simply be laid
      out on a traditional keyboard.
    </p>
  </description>
  <url type="homepage">https://github.com/mike-fabian/ibus-table-others</url>
</component>]]></programlisting>
	</section>

	<section id="spec-imdata-filespec">
		<title>File specification</title>
		<para>
			Note that the XML root must have the <literal>type</literal> property set to <literal>inputmethod</literal>.
			This clearly identifies this metainfo document as describing an input method instead of a generic software component.
		</para>

		<variablelist>
			<varlistentry id="tag-id-inputmethod">
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For input methods, the <literal>%{id}</literal> should follow the standard reverse-domain-name scheme.
					For the product name part, it is recommended to take the database filename of the input method.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;metadata_license/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;metadata_license/&gt;</code> tag is required. See <xref linkend="sect-Metadata-GenericComponent"/> for a description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;name/&gt;</term>
			<listitem>
				<para>
					Set a name for your input method.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;summary/&gt;</term>
			<listitem>
				<para>
					A short description of the input method described in this metainfo file.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;description/&gt;</term>
			<listitem>
				<para>
					Add a long description of the input method.
				</para>
				<para>
					Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;screenshots/&gt;</term>
			<listitem>
				<para>
					A screenshot may be included, showing the input method in use in an application.
				</para>
				<para>
					Refer to <xref linkend="tag-screenshots"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;url/&gt;</term>
			<listitem>
				<para>
					This is a recommended tag for links of type <code>homepage</code>.
					Links of type <code>homepage</code> should be a link to the upstream homepage for the application.
					See See <xref linkend="tag-url"/> for a description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;provides/&gt;</term>
			<listitem>
				<para>
					This tag is described for generic components at <xref linkend="tag-provides"/> in detail.
				</para>
				<para>
					You can add one or more children of type <code>&lt;library/&gt;</code> in case you publish some additional shared libraries.
					If not, and there are no public binaries involved, you may omit the <literal>provides</literal> tag for input methods.
				</para>
			</listitem>
			</varlistentry>
		</variablelist>

		<para>
			For a component of type <literal>inputmethod</literal>, the following tags are required and must be present:
			<xref linkend="tag-id-inputmethod"/>, <xref linkend="tag-name"/>,
			<xref linkend="tag-summary"/>, <xref linkend="tag-metadata_license"/>.
		</para>
	</section>
</section>
