<?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-Fonts">
	<title>Fonts</title>

	<section id="spec-fontdata-introduction">
		<title>Introduction</title>
		<para>
			A software center can allow users to install additional fonts using font metadata.
			Also, applications can use font metadata to find missing fonts (e.g. a special methematical font is needed)
			in the distribution's software sources.
			This meta-info specification describes how metadata for fonts / font collections should be structured.
		</para>
		<para>
			Font packages can ship one or more files in <filename>/usr/share/appdata/%{id}.metainfo.xml</filename>.
		</para>
		<para>
			Font metadata files can - just likle all other metainfo files - be translated. See the section about translation for more information about that.
		</para>
	</section>

	<section id="spec-fontdata-example">
		<title>Example file</title>
		<para>
			A minimal font metainfo file can look like this:
		</para>
		<programlisting language="XML">
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<component type="font">
  <id>LinuxLibertine.font</id>
  <metadata_license>CC0</metadata_license>
  <name>Linux Libertine</name>
  <summary>Linux Libertine fonts</summary>
  <provides>
    <font file="LinLibertine_R.otf">Linux Libertine O</font>
    <font file="LinLibertine_M.otf">Linux Libertine Mono</font>
  </provides>
</component>]]></programlisting>
	</section>

	<section id="spec-fontdata-filespec">
		<title>File specification</title>
		<para>
			Note that the XML root must have the <literal>type</literal> property set to <code>font</code>.
			This clearly identified this metainfo document as describing a font.
		</para>

		<variablelist>
			<varlistentry>
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For fonts, the <literal>%{id}</literal> must be the name of the font or font bundle without whitespaces, and must be suffixed
					with <code>.font</code>.
				</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="tag-metadata_license"/> for a description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;name/&gt;</term>
			<listitem>
				<para>
					Set a name for your font or font collection.
				</para>
			</listitem>
			</varlistentry>

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

			<varlistentry>
			<term>&lt;description/&gt;</term>
			<listitem>
				<para>
					Add a long description of your font. Some rules apply (will soon be split out to a "description guidelines" section).
				</para>
				<para>
					Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.
				</para>
				<para>
					See the generic component <xref linkend="tag-description"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;screenshots/&gt;</term>
			<listitem>
				<para>
					A screenshot presents your font to the outside world.
				</para>
				<para>
					If the font metadata does not define an own screenshot, the AppStream generator is supposed to render one or multiple
					sample images using the respective font.
				</para>
				<para>
					See the generic component <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 the generic component <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 in detail for generic components at <xref linkend="tag-provides"/>.
				</para>
				<para>
					You should add one or more children of type <code>&lt;font/&gt;</code> to make the font filenames and names known to the system.
					If this tag is not present, the <literal>name</literal> and <literal>id</literal> tag values can be used by the
					distribution's AppStream-generator to recreate this tag.
				</para>
			</listitem>
			</varlistentry>
		</variablelist>

	</section>
</section>
