diff --git a/docs/sources/distrospec/asxml.xml b/docs/sources/distrospec/asxml.xml index 3430671e..e220c383 100644 --- a/docs/sources/distrospec/asxml.xml +++ b/docs/sources/distrospec/asxml.xml @@ -11,7 +11,7 @@ Introduction - AppStream XML files are small textfiles describing all available applications in the distribution's package repositories. + AppStream XML files are small text files describing all available applications in the distribution's package repositories. The XML files might be compressed with GZip. @@ -19,7 +19,7 @@
File naming and location - The XML files must have an unique name, which is usually the distribution's name and version, combined with the name of the repository/origin. + The XML files must have a unique name, which is usually the distribution's name and version, combined with the name of the repository/origin. For example in Debian 8 (Jessie), the filename for the main repository component would be debian-jessie-main.xml.gz. For Fedora 20 (Heisenbug) updates it would be fedora-20-updates.xml.gz. 3rd-party repositories use a vendor name and repository-name combination, for example Ubuntu PPAs might get ppa-ubuntu12.04-username-foobar.xml. @@ -27,7 +27,7 @@ There are two valid locations to store AppStream XML data. /usr/share/app-info/xmls stores all AppStream data which has been installed via software packages, while /var/cache/app-info/xmls stores application data which was downloaded - by the package manager or placed there by other tools (e.g. Limba). + by the package manager or placed there by other tools (for example, Limba). The XML files can either be plain files or be compressed with gzip. It is always a good idea to compress the files, because they tend to become quite large. @@ -36,8 +36,8 @@
General XML structure - The XML starts with an <components> tag as root element. It has all the - <component> tags of different type as children. + The XML starts with a <components> tag as the root element. It has all the + <component> tags of different types as children. Data to fill the different component elements is usually taken from their Desktop files @@ -66,7 +66,7 @@ origin - Defines the repository-id this AppStream XML file belongs to. This usually matches the filename without extension (see the explanation on how to pick a good filename above). + Defines the repository ID this AppStream XML file belongs to. This usually matches the filename without extension (see the explanation on how to pick a good filename above). It is also used to associate the right cached icons with AppStream metadata. This property is required. @@ -93,7 +93,7 @@ Additionally to the type property, every <component/> tag in AppStream distro data may have a priority property, defining the priority of this specific metadata over other metadata from different - AppStream XML files (e.g. from a different repository) which have the same component-id. The value of this tag is an integer, if the + AppStream XML files (for example, from a different repository) which have the same component-id. The value of this tag is an integer, if the property is missing, a value of "0" is assumed. @@ -285,7 +285,7 @@ http://example.com/icons/foobar.png /usr/share/pixmaps/foobar.png]]> - Multiple ]]> tags might be combined for one application, e.g. to define a stock icon + Multiple ]]> tags might be combined for one application, for example to define a stock icon and a cached icon. Software-Centers should always prefer the stock icon, if it is available, and fall back to the other icon types if they can not find it. The libappstream library makes it easy to do that, if you are not accessing the Xapian database manually. @@ -473,7 +473,7 @@ The description tag is structured as described in . This also applies to its translation rules. - The AppStream distro XML generator may shorten overlong lists of releases to a smaller list, e.g. of 4 release tags. + The AppStream distro XML generator may shorten overlong lists of releases to a smaller list, for example of 4 release tags. It may also convert ISO 8601 date properties of the metainfo file into an UNIX timestamp timestamp property. It should avoid generating metadata containing both properties on a release tag. diff --git a/docs/sources/metaspecs/addondata.xml b/docs/sources/metaspecs/addondata.xml index 40c053e1..fdcf8599 100644 --- a/docs/sources/metaspecs/addondata.xml +++ b/docs/sources/metaspecs/addondata.xml @@ -40,7 +40,7 @@ File specification Note that the XML root must have the type property set to addon. - This clearly identified this metainfo document as describing an addon to an existing software. + This clearly identifies this metainfo document as describing an addon to existing software. @@ -49,7 +49,7 @@ For addons, there are no special requirements for what their %{id} should be. - You might want to prefix your id with "addon-" though, to make it easily recognizable. + You might want to prefix your ID with "addon-" though, to make it easily recognizable. @@ -58,11 +58,10 @@ <extends/> - This tag is refers to the id of the component this addon is extending. + This tag is refers to the ID of the component this addon is extending. - So for example if I have a plugin "kipi" which extends the application "Gwenview", I need to refer to - it's identifier like: + For example, if there is a plugin "kipi" which extens the application "Gwenview", it needs to be referred to as: gwenview.desktop]]> diff --git a/docs/sources/metaspecs/codecdata.xml b/docs/sources/metaspecs/codecdata.xml index bef53650..8a911c2b 100644 --- a/docs/sources/metaspecs/codecdata.xml +++ b/docs/sources/metaspecs/codecdata.xml @@ -16,7 +16,7 @@ Codecs can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml. - Codec metadata files can - just likle all other metainfo files - be translated. See the section about translation for more information about that. + Codec metadata files can – just like all other metainfo files – be translated. See the section about translation for more information.
@@ -72,7 +72,7 @@ File specification Note that the XML root must have the type property set to codec. - This clearly identified this metainfo document as describing a codec. + This clearly identifies this metainfo document as describing a codec. @@ -81,7 +81,7 @@ For codecs, there are no special requirements for what their %{id} should be. - But, as for any other component, you should pick a reasonable and unique name. + But, as for any other component, the name must be unique. diff --git a/docs/sources/metaspecs/component.xml b/docs/sources/metaspecs/component.xml index c0a4d810..d2063176 100644 --- a/docs/sources/metaspecs/component.xml +++ b/docs/sources/metaspecs/component.xml @@ -16,7 +16,7 @@ To provide this information, we created the metainfo files, which allow upstream projects to describe the content of their software package. - If a metainfo file provides a <provides/> tag, distributors must also ensure that the package providing the file contain all items referenced + If a metainfo file uses a <provides/> tag, distributors must also ensure that the package providing the file contains all items referenced by that statement, or is installed by a metapackage depending on packages which provide these items. This gives upstream projects a (very light) way to influence distributor packaging. More information about that can be found below. @@ -55,8 +55,8 @@ XML Specification - The XML for a generic component definition starts with an ]]> tag as root element. - The ]]> element must at least have an id, name and releases tag, + The XML for a generic component definition starts with a ]]> tag as the root element. + The ]]> element must at least have an id, name and releases tag; and a provides tag with appropriate children is highly recommended. All possible tags in the generic set are: @@ -66,12 +66,12 @@ <id/> - The ]]> tag is a short and unique identifier for this component. It must contain only ASCII characters, dots, hyphens and numbers, spaces are - not allowed. Specialized metainfo types, such as application or fonts, may apply additional restrictions on the id tag value. + The ]]> tag is a short and unique identifier for this component. It must contain only ASCII characters, dots, hyphens and numbers. Spaces are + not allowed. Specialized metainfo types, such as applications or fonts, may apply additional restrictions on the id tag value. - A general pattern for a valid ID tag is to use a reverse URL scheme, consisting of <tld>.<vendor>.<product>.<type>, e.g. org.kde.gwenview.desktop - or com.hugski.ColorHug2.firmware. + A general pattern for a valid ID tag is to use a reverse URI scheme, consisting of <tld>.<vendor>.<product>.<type>, for example org.kde.gwenview.desktop + or com.hugski.ColorHug2.firmware. Ownership of <vendor>.<tld> in the domain name system guarantees uniqueness of IDs. Note that the value of this tag must be unique across all distributions. In case it is not, distributors are expected to reject the conflicting components @@ -84,34 +84,34 @@ <metadata_license/> - The <metadata_license/> tag indicates the content licence that you are releasing the one - Metainfo XML file under. This is not typically the same as the project licence. Omitting the license value can result + The <metadata_license/> tag indicates the content license that you are releasing the one + Metainfo XML file under. This is typically not the same as the project license. Omitting the license value can result in your data not being incorporated into the distribution metadata (so this is a required tag). A permissive license ensures your data can be combined with arbitrary other data in one file. - Primissive licence names include: + Permissive license names include: - CC0-1.0 + CC0-1.0 - CC-BY-3.0 + CC-BY-3.0 - CC-BY-SA-3.0 + CC-BY-SA-3.0 - GFDL-1.3 + GFDL-1.3 - MIT + MIT - The licence codes correspond to the identifiers found at the SPDX OpenSource License Registry. - For instance, CC-BY-SA-3.0 corresponds to the license at + The license codes correspond to the identifiers found at the SPDX OpenSource License Registry. + For instance, CC-BY-SA-3.0 corresponds to the license at creativecommons.org/licenses/by-sa/3.0. @@ -121,7 +121,7 @@ <name/> - A human-readable name for this software component. For example, if the component id was "libc", its name might be "GNU Standard C Library". + A human-readable name for this software component. For example, if the component ID was "libc", its name might be "GNU Standard C Library". @@ -142,7 +142,7 @@ A long description of this component. Some markup can be used. - Do not assume the format is HTML. Only paragraph (p), ordered list (ol) and unordered list (ul) are supported at this time. + Do not assume the format is HTML. Only paragraph (p), ordered list (ol) and unordered list (ul) are supported at this time. In metainfo files, this tag should be translated by-paragraph, meaning that in a translated file, each translated <p/> child @@ -177,7 +177,7 @@ Should link a FAQ page for this software, to answer some of the most-asked questions in - detail, something which you can not do in the component's description. + detail, something which you cannot do in the component's description. @@ -213,20 +213,20 @@ A release tag can have the properties version, date and timestamp. - The date property can have any time in ISO 8601 format as value and + The date property can have any date in ISO 8601 format as its value and should be present for every release. - The timestamp tag contains the release time in form of a UNIX epoch. This tag should not be used in metainfo files in newly - written metadata, but will still be parsed in case it is present. The the timestamp property is mainly used in generated distro-meadata. + The timestamp tag contains the release time in the form of a UNIX epoch. This tag should not be used in metainfo files in newly + written metadata, but will still be parsed in case it is present. The the timestamp property is mainly used in generated distro-metadata. In case both release-time tags are present, the timestamp tag will take precedence over date. Optionally, the <release/> tag may also have an urgency property, having one of the following values: - low - medium - high - critical + low + medium + high + critical The urgency defines how important it is to install the new release as an update. This is especially important for type=firmware @@ -236,14 +236,14 @@ Each release tag may have a description tag as child, containing a brief description of what is new in the release. - The description tag is structured as described in + The description tag is structured as described in . A release tag may also have one or multiple size tags as children, which define the installed and download size of this component release. This is useful in case the component does not have a corresponding native package in a distribution, for example if it is a Limba bundle or LVFS firmware. The size type is defined via a type property on the size tag, and may assume the value download or installed. - The size itself is set as value and must be given in bytes. + The size itself is set as the value and must be given in bytes. Examples for a valid releases tag: @@ -262,14 +262,15 @@ <provides/> - The provides tag and it's children describe the public interfaces this application provides. + The provides tag and its children describe the public interfaces this application provides. A public interface can be anything which other applications, which are not part of the upstream project, can access or reference. This includes binaries and libraries. Private interfaces should never be added to a provides tag. A provides tag contain a number of children describing the type and name of the provided public interface items. - It is suggested that the build-system auto-generates this tag and it's children. - Currently allowed item types are listed below. If you miss something, file a bug against AppStream so we can add the new type. + It is suggested that the build system auto-generates this tag and its children. + Currently allowed item types are listed below. If you miss something, + file a bug against AppStream so we can add the new type. @@ -314,8 +315,8 @@ A modalias glob representing the hardware types (for example USB, PCI, ACPI, DMI) this component handles. - Useful for installing printer drivers or other USB protocol drivers for smartphones, firmware, kernel drivers which - are not merged upstream yet or whatever else. + Useful for installing printer drivers or other USB protocol drivers for smartphones, firmware, and + out of tree kernel drivers. @@ -334,7 +335,7 @@ <python2/> - Name of a Python2 module this component provides. + Name of a Python 2 module this component provides. @@ -343,7 +344,7 @@ <python3/> - Name of a Python3 module this component provides. + Name of a Python 3 module this component provides. @@ -352,7 +353,7 @@ <dbus/> - Contains the name of a DBus service as property. The type of the service must be specified using the type property + Contains the well-known name of a D-Bus service as its value. The type of the service must be specified using the type property of this tag. Allowed values are user and system. @@ -373,9 +374,9 @@ <mimetypes/> - This tag can contain one or more <mimetype/> children, describing the mime types this application supports. + This tag can contain one or more <mimetype/> children, describing the MIME types this application supports. This tag is especially useful for generic components and addon-type components. For applications, the metadata will automatically - be fetched from their .desktop files by the distribution's metadata generator. + be fetched from their .desktop files by the distribution's metadata generator. Example: @@ -392,11 +393,11 @@ If you include the <project_group/> tag then this identifies your project with a specific upstream umbrella project. - Known values include GNOME, KDE, XFCE, MATE and LXDE, although other umbrella projects like Yorba or Mozilla make sense too. + Known values include GNOME, KDE, XFCE, MATE and LXDE, although other umbrella projects like Yorba or Mozilla make sense too. - You should only identify with an umbrella project if you use all their infrastructure and policies, for instance string freezes dates, bugtracker and source control instance. + You should only identify with an umbrella project if you use all their infrastructure and policies, for instance string freezes dates, bugtracker and source control instance. @@ -410,11 +411,10 @@ It should be a string in SPDX format. Licenses may be combined using and and or logic. Possible values include: - GPL-2.0 - LGPL-3.0+ and GPL-3.0+ - MIT - CC-BY-SA-2.0 - ... + GPL-2.0 + LGPL-3.0+ and GPL-3.0+ + MIT + CC-BY-SA-2.0 A full list of recognized licenses and their identifiers can be found at the SPDX OpenSource License Registry. @@ -459,7 +459,7 @@ type - The type of the image, source for the source image, and thumbnail for a thumbnail image. + The type of the image: source for the source image, and thumbnail for a thumbnail image. In case the type is thumbnail, the width and height properties must be present. @@ -489,7 +489,7 @@ description of what the user can see on the referenced screenshot. - Ideally, all screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620px. + Ideally, all screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620 pixels. They should also be in be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other images where a lossy format like JPEG may compress better. @@ -516,7 +516,7 @@ The <update_contact/> tag is an optional tag which can be added to provide an email address distributors can use to contact the project - about invalid or incomplete metadata, or in case the specification has changed, about old metadata. It can also be used to ask general questions in case of + about invalid or incomplete metadata or – in case the specification has changed – about old metadata. It can also be used to ask general questions in case of an update of the component described in the metadata file. @@ -544,8 +544,8 @@ The tag must have a type property, assuming the value of the translation system which is used. Right now, allowed translation systems and values for type are: - gettext - qt + gettext + qt In case a software components gets its translation from multiple translation domains, the <translation/> tag may be defined more than once. diff --git a/docs/sources/metaspecs/desktopappdata.xml b/docs/sources/metaspecs/desktopappdata.xml index 614f0607..85951611 100644 --- a/docs/sources/metaspecs/desktopappdata.xml +++ b/docs/sources/metaspecs/desktopappdata.xml @@ -10,11 +10,11 @@
Introduction - A desktop application is an application which has a graphica user interface and is commonly used with mouse and keyboard. It also ships a Freedesktop - .desktop file to be visible in application menus. + A desktop application is an application which has a graphical user interface and is commonly used with mouse and keyboard. It also ships a Freedesktop + .desktop file to be visible in application menus. - AppStream generators may pull data from the preexisting .desktop files to represent an application in the AppStream metadata pool. Upstream projects should + AppStream generators may pull data from the preexisting .desktop files to represent an application in the AppStream metadata pool. Upstream projects should ship a small XML file containing additional metadata to describe their application though, to enhance the available metadata. This data includes things like screenshots, long descriptions, icon information and various other things needed to present the application properly to the user. @@ -25,7 +25,7 @@ The metainfo files override any values which are automatically fetched from other sources by the AppStream data generator, which means that its data will always take precedence over - data which has already been defined in a .desktop-file. + data which has already been defined in a .desktop file. Applications can ship one or more files in /usr/share/metainfo/%{id}.appdata.xml. @@ -42,7 +42,7 @@ The basic structure for a generic component as described at applies. Note that the XML root must have the type property set to desktop, while in a generic component this - property can be omitted. This clearly identified this metainfo document as describing an application. + property can be omitted. This clearly identifies this metainfo document as describing an application. @@ -63,7 +63,7 @@ <id/> - For applications, the <id/> tag value must be the same name as the installed .desktop file for the application. + For applications, the <id/> tag value must be the same name as the installed .desktop file for the application. diff --git a/docs/sources/metaspecs/firmwaredata.xml b/docs/sources/metaspecs/firmwaredata.xml index c49050f6..9434c231 100644 --- a/docs/sources/metaspecs/firmwaredata.xml +++ b/docs/sources/metaspecs/firmwaredata.xml @@ -13,7 +13,7 @@ Device firmware can be accompanied by AppStream upstream metadata, to be incorporated by a distribution. Tools like fwupd make use of this metadata to automatically update flashed firmware of devices found in the machine. - Additionally, this component type can also be used for firmware which is loaded to the device at runtime. + Additionally, this component type can also be used for firmware which is loaded onto the device at runtime. Firmware can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml. @@ -69,7 +69,7 @@ File specification Note that the XML root must have the type property set to firmware. - This clearly identified this metainfo document as describing firmware. + This clearly identifies this metainfo document as describing firmware. @@ -78,7 +78,7 @@ For firmware, the value of the <id/> tag must be a unique name for the device the firmware belongs to, constsing of the vendor domain and the - device name. A reverse URL scheme in form of <tld>.<vendor>.<product>.firmware is used, e.g. com.hughski.ColorHug2.firmware. + device name. A reverse URL scheme in the form of <tld>.<vendor>.<product>.firmware is used, for example com.hughski.ColorHug2.firmware. @@ -93,7 +93,7 @@ The <location/> tag specifies a remote location where the firmware .cab can be downloaded from. - The download location needs to be accessibly via HTTP, HTTPS or FTP. + The download location needs to be accessible via HTTP, HTTPS or FTP. Example: diff --git a/docs/sources/metaspecs/fontdata.xml b/docs/sources/metaspecs/fontdata.xml index 3377fa51..b2c3b494 100644 --- a/docs/sources/metaspecs/fontdata.xml +++ b/docs/sources/metaspecs/fontdata.xml @@ -11,15 +11,15 @@ Introduction 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) + 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 meta-info specification describes how metadata for fonts / font collections should be structured. + This meta-info specification describes how metadata for fonts or font collections should be structured. Font packages can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml. - Font metadata files can - just likle all other metainfo files - be translated. See the section about translation for more information about that. + Font metadata files can – just like all other metainfo files – be translated. See the section about translation for more information.
@@ -46,7 +46,7 @@ File specification Note that the XML root must have the type property set to font. - This clearly identified this metainfo document as describing a font. + This clearly identifies this metainfo document as describing a font. @@ -54,7 +54,7 @@ <id/> - For fonts, the %{id} must be the name of the font or font bundle without whitespaces, and must be suffixed + For fonts, the %{id} must be the name of the font or font bundle without whitespace, and must be suffixed with .font. @@ -73,7 +73,7 @@ <name/> - Set a name for your font or font collection. + Set a name for the font or font collection. diff --git a/docs/sources/metaspecs/inputmethoddata.xml b/docs/sources/metaspecs/inputmethoddata.xml index 67d4c33b..6edd3779 100644 --- a/docs/sources/metaspecs/inputmethoddata.xml +++ b/docs/sources/metaspecs/inputmethoddata.xml @@ -10,22 +10,22 @@
Introduction - It is a nice feature for a software center to allows users the installation of additional input-methods. - This meta-info specification describes how metadata about input-methods should be structured. + It is a nice feature for a software center to allows users the installation of additional input methods. + This meta-info specification describes how metadata about input methods should be structured. - Software components providing an input-method can ship one or more files in + Software components providing an input method can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml. - Input-method metadata files can - just likle all other metainfo files - be translated. See the section about translation for more information about that. + Input method metadata files can – just like all other metainfo files – be translated. See the section about translation for more information.
Example file - The input-method meta-info file should look like this: + The input method meta-info file should look like this: @@ -52,7 +52,7 @@ File specification Note that the XML root must have the type property set to inputmethod. - This clearly identified this metainfo document as describing an input-method instead of a generic software-component. + This clearly identifies this metainfo document as describing an input method instead of a generic software component. @@ -60,7 +60,7 @@ <id/> - For input-methods, the %{id} is the same name as the input-method's database filename. + For input methods, the %{id} is the same name as the input method's database filename. @@ -78,7 +78,7 @@ <name/> - Set a name for your input-method. + Set a name for your input method. @@ -87,7 +87,7 @@ <summary/> - A short description of the input-method described in this metainfo file. + A short description of the input method described in this metainfo file. @@ -96,7 +96,7 @@ <description/> - Add a long description of the input-method. + Add a long description of the input method. Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time. @@ -108,7 +108,7 @@ <screenshots/> - A screenshot may be included, showing the input-method in use in an application. + A screenshot may be included, showing the input method in use in an application. Refer to for a detailed description of this tag. @@ -135,7 +135,7 @@ You can add one or more children of type <library/> in case you publish some additional shared libraries. - If not, and there are no public binaries involved, you may omit the provides tag for input-methods. + If not, and there are no public binaries involved, you may omit the provides tag for input methods.