<?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 (for example, if a special mathematical font is needed)
			in the distribution's software sources.
			This metainfo specification describes how metadata for fonts or font collections should be structured.
		</para>
		<para>
			Font packages can ship one or more files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
		</para>
		<para>
			Font metadata files can – just like all other metainfo files – be translated. See the section about translation for more information.
		</para>
		<note>
			<para>
				A <literal>font</literal> component is in most cases not describing a single font, but rather a collection of fonts that
				are grouped together, usually by their art style or font-family.
			</para>
			<para>
				To make the individual fonts known to the system, use the <xref linkend="tag-font-provides"/> tag.
			</para>
		</note>
	</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>com.latofonts.Lato</id>
  <metadata_license>MIT</metadata_license>
  <project_license>OFL-1.1</project_license>

  <name>Lato</name>
  <summary>A sanserif type­face fam­ily</summary>
  <description>
    <p>
      Lato is a sanserif type­face fam­ily designed in the Sum­mer 2010 by Warsaw-​​based designer
      Łukasz Dziedzic (“Lato” means “Sum­mer” in Pol­ish). In Decem­ber 2010 the Lato fam­ily
      was pub­lished under the open-​​source Open Font License by his foundry tyPoland, with
      sup­port from Google.
    </p>
  </description>

  <provides>
    <font>Lato Regular</font>
    <font>Lato Italic</font>
    <font>Lato Bold</font>
    <font>Lato Light</font>
    <font>Lato Light Italic</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 identifies this metainfo document as describing a font.
		</para>

		<variablelist>
			<varlistentry>
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For fonts, the <literal>%{id}</literal> must follow the reverse-DNS scheme as described for generic components.
					For the product name part, it is recommended to take the the name of the font or font bundle without whitespace.
				</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 the 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. 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 id="tag-font-provides">
			<term>&lt;provides/&gt; ↪ &lt;font/&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's full-names known.
					The full-name should be the same as given in the font file for the English language.
					If no full-name is set, a space-separated combination of the font's <literal>family</literal> and <literal>style</literal>
					is used instead.
					The font <emphasis>must</emphasis> have a <literal>family</literal> defined to be included.
				</para>
				<para>
					The full-name entry should show the complete name of a typeface in its
					“natural” form, including style and character set information (if any), and
					without abbreviations. This is the name that some systems and applications
					look at to determine full, unabbreviated font menu names.
				</para>
				<para>
					If you want to query the full-name and its <literal>family</literal> and <literal>style</literal> to see what needs to
					be added to this tag, you can use the <command>fc-query</command> utility of Fonconfig:
				</para>
				<screen><command>fc-query</command> --format='FN: %{fullname[0]}\nFS: %{family[0]} %{style[0]}\n' <userinput>FONT-FILENAME</userinput></screen>
				<para>
					Examples:
				</para>
				<programlisting language="XML"><![CDATA[<provides>
  <font>Lato Heavy Italic</font>
  <font>Noto Kufi Arabic Bold</font>
  <font>Liberation Serif Bold Italic</font>
  <font>FontAwesome Regular</font>
</provides>]]></programlisting>
				<para>
					If no <code>&lt;font/&gt;</code> tags were defined, the AppStream catalog data generator should try to extract them from the actual font files found in the
					software package/bundle.
				</para>
				<para>
					In every case, the names given in the provides tag <emphasis>must</emphasis> match the metadat the fonts contain themselves. If the data of the font files
					is incomplete, the data can not be extended by the <code>&lt;font/&gt;</code> tag.
					This is important because the AppStream generator may use the data to pick the right fonts, and because applications expect the exact font they requested
					via AppStream to be present on the system after the component was installed (and not one which has different metadata).
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-font-languages">
				<term>&lt;languages/&gt;</term>
				<listitem>
					<para>
						This tag gives information about the locale a font supports.
					</para>
					<para>
						This tak allows specifying the main locale (and thereby scripts) the font can be used with.
						It does not have to contain an extensive list, as the AppStream metadata generator will try get obtain that
						information from the font files themselves, but it is useful to define to hint the generator in the right direction.
					</para>
					<para>
						If samples of the font are rendered as screenshots by the catalog metadata generator, the locale mentioned in the
						metainfo file will be preferred over automatically (or heuristically) defined ones.
					</para>
					<para>
						You can use the following command to determine which languages a font supports:
					</para>
					<screen><command>fc-query</command> --format='%{lang}\n' <userinput>FONT-FILENAME</userinput></screen>
					<para>
						Tag example:
					</para>
					<programlisting language="XML"><![CDATA[<languages>
  <lang>de</lang>
  <lang>en</lang>
  <lang>cn</lang>
</languages>
]]></programlisting>
				</listitem>
			</varlistentry>
		</variablelist>

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

	</section>
</section>