<?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-ConsoleApplication">
	<title>Console Applications</title>

	<section id="spec-consoleapp-introduction">
		<title>Introduction</title>
		<para>
			A console application is any application that has a command-line or text-based interface and is designed to be used by a human user
			on the command line. Applications need to be present in the standard <envar>PATH</envar>.
		</para>
		<para>
			The file described in this document is built upon the generic component metadata with fields specific for applications (see <xref linkend="sect-Metadata-GenericComponent"/>).
			All tags valid for a generic component are valid for a <literal>console-application</literal> component as well.
		</para>
		<para>
			In order to enhance the available metadata about their application, projects shipping a console application can ship one or more metainfo files
			in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
		</para>

	</section>

	<section id="spec-consoleapp-filespec">
		<title>File specification</title>

		<para>
			The basic structure for a generic component as described at <xref linkend="spec-component-filespec"/> applies.
			Note that the XML root must have the <literal>type</literal> property set to <code>console-application</code>, while in a generic component this
			property can be omitted. This clearly identified this metainfo document as describing an application.
		</para>

		<para>
			The following list describes tags for <literal>console-application</literal> upstream metadata and provides some additional information about the values
			the tags are expected to have.
			If no information is given about a tag, refer to the respective tag in <xref linkend="sect-Metadata-GenericComponent"/>.
		</para>

		<variablelist>
			<varlistentry id="tag-id-console-app">
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For console applications, the <code>&lt;id/&gt;</code> tag value must follow the AppStream ID naming conventions (it should be a reverse-DNS name).
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;metadata_license/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;metadata_license/&gt;</code> tag as described in <xref linkend="tag-metadata_license"/> must be present.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;name/&gt;</term>
			<listitem>
				<para>
					A <literal>name</literal> must be present for console applications. See <xref linkend="tag-name"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;summary/&gt;</term>
			<listitem>
				<para>
					A <literal>summary</literal> must be present for console applications. See <xref linkend="tag-summary"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-consoleapp-provides">
			<term>&lt;provides/&gt; ↪ &lt;binary/&gt;</term>
			<listitem>
				<para>
					This tag is described in detail for generic components at <xref linkend="tag-provides"/>.
				</para>
				<para>
					For console applications, at least one provided <code>&lt;binary/&gt;</code> must be listed in this tag.
				</para>
			</listitem>
			</varlistentry>
		</variablelist>

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

	</section>
</section>
