1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY yelp "<application>Yelp</application>">
]>
<article id="index" lang="en">
<articleinfo>
<title>Help System Specification</title>
<copyright>
<year>2003</year>
<holder>Shaun McCance</holder>
</copyright>
<authorgroup>
<author>
<firstname>Shaun</firstname>
<surname>McCance</surname>
<affiliation>
<orgname>GNOME Documentation Project</orgname>
</affiliation>
<address><email>shaunm@gnome.org</email></address>
</author>
</authorgroup>
<revhistory>
<revision>
<revnumber>Help System Specification 0.1</revnumber>
<date>January 2004</date>
</revision>
</revhistory>
<releaseinfo>
This is a DRAFT specification for the freedesktop.org help system.
</releaseinfo>
</articleinfo>
<section id="xhelp-introduction">
<title>Introduction</title>
<para>This DRAFT document defines a new system for installing a locating
help files for applications and other components of the desktop.</para>
<para>Documents are located and categorized dynamically by reading metadata
files from standard locations. The metadata files use the Desktop Entry
format, which is defined by the
<ulink url="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop
Entry Specification</ulink> on freedesktop.org.</para>
<para>A single metadata file describes one document. There is no provision
for describing multiple documents with a single metadata file. This is true
even of variations of the same document. For instance, if a document is
translated into multiple languages, a metadata file must be provided for
each translation. Variations of a single logical document are identified
as such using the <property>ID</property> key, which is discussed in
<xref linkend="xhelp-id"/>.</para>
</section>
<section id="xhelp-metadata">
<title>Metadata File Format</title>
<para>The metadata files use the Desktop Entry format. However, this
specification provides its own set of keys to describe a document. Only
those keys listed in this specification should be considered standard.
For non-standard key usage, see <xref linkend="xhelp-extending"/>.</para>
<para>Since this specification defines its own set of keys, a unique group
header is necessary to identify Desktop Entry files. Thus, Desktop Entry
files for documentation must use the group header
<property>[Documentation]</property>.</para>
<para>Many keys allow arbitrary text for the value. The values for these
keys may contain any character from the following Unicode ranges:</para>
<literallayout>[#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]</literallayout>
<para>Additionally, the escape sequences <literal>\s</literal>,
<literal>\n</literal>, <literal>\t</literal>, <literal>\r</literal>, and
<literal>\\</literal> are supported, meaning ASCII space, newline, tab,
carriage return, and backslash, respectively. Note that these strings
must be encoded in UTF-8, as well as the rest of the file. The
<literal>LegacyMixed</literal> encoding is not supported. Keys which
accept this production for values will be specified as accepting
UTF-8 strings.</para>
<para>The following keys are defined for Desktop Entry files for
documentation:</para>
<variablelist>
<varlistentry>
<term><property>ID</property></term>
<listitem><para>
The <property>ID</property> key is a unique identifier for a document
or set of documents. Variations of the same logical document must
use the same <property>ID</property>. The <property>ID</property>
key is discussed in detail in <xref linkend="xhelp-id"/>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>Title</property></term>
<listitem><para>
The <property>Title</property> key provides the title of the document.
This key accepts any UTF-8 string.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>Description</property></term>
<listitem><para>
The <property>Description</property> key provides a short description
of the document. The <property>Description</property> key is optional.
This key accepts any UTF-8 string.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>Language</property></term>
<listitem><para>
The <property>Language</property> key provides the written language of
the document. The value of this field must be a valid language code as
specified by ISO-639. The value may be <literal>C</literal> for the
POSIX locale. This key is mandatory.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>ContentType</property></term>
<listitem><para>
The <property>ContentType</property> key provides the MIME type of the
document. This key is mandatory. If the document is in an SGML or XML
vocabulary, the properties <property>ContentTypeSystem</property> and
<property>ContentTypeNamespace</property> may also be used to provide
additional information about the file format.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>ContentTypeSystem</property></term>
<listitem><para>
The <property>ContentTypeSystem</property> key provides the system
identifier of an XML or SGML document. This may be used to specify
the particular SGML or XML vocabulary used by the document when the
MIME type is not sufficient. The value of this field should be a URL,
typically pointing to the DTD. This key is optional.
</para></listitem>
</varlistentry>
<varlistentry>
<term><property>ContentTypeNamespace</property></term>
<listitem><para>
The <property>ContentTypeNamespace</property> key provides the namespace
of the top-level element of an XML document. This may be used to specify
the particular XML vocabulary used by the document when the MIME type is
not sufficient. This key is optional.
</para></listitem>
</varlistentry>
</variablelist>
</section>
<section id="xhelp-id">
<title>The <property>ID</property> Key</title>
</section>
<section id="xhelp-extending">
<title>Extending the Format</title>
<para>If one particular party wishes to add a key for personal use, they
should prefix the key with the string <property>X-PRODUCT</property>,
i.e. <property>X-NewDesktop-Foo</property>, following the precedent
set by other IETF and RFC standards.</para>
<para> Alternatively, fields can be placed in their own group, where
they may then have arbitrary key names. If this is the case, the group
should follow the scheme outlined above, i.e. <property>[X-PRODUCT
GROUPNAME]</property> or something similar. These steps will avoid
namespace clashes between different yet similar environments.</para>
</section>
</article>
|
