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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article id="index">
<title>Help System Specification</title>
<articleinfo>
<title>Help System Specification</title>
<date>2010-04-30</date>
<authorgroup>
<author>
<firstname>Shaun</firstname>
<surname>McCance</surname>
<affiliation>
<address>
<email>shaunm@gnome.org</email>
</address>
</affiliation>
</author>
</authorgroup>
</articleinfo>
<section id="overview">
<title>Overview</title>
<para>This specification provides a common directory layout and URI
scheme for locally installed help documents. Documents installed and
referenced using this system will have better interoperability between
different desktop environments and help applications.</para>
</section>
<section id="layout">
<title>Directory Layout</title>
<para>A document is a collection of files, possibly from multiple
directories in a path. Documents may be in any format, or even in
multiple formats; see <xref linkend="formats"/> for details. A
document has a <emphasis>document identifier</emphasis> that
identifies it uniquely and specifies where it can be found on
the file system. A document identifier consists of one or more
characters from the following: digits (U+0030-U+0039), letters
(U+0041-U+005A and U+0061-U+007A), hyphen (U+002D), underscore
(U+005F), period (U+002E), and percent (U+0025).</para>
<para>Document identifiers are not explicitly namespaced. To
avoid conflicts, document identifiers should start with the name
of the application or package that provides the document. In many
cases, the name of the application or package alone may be used.
Otherwise, the document identifier should start with the name
of the package or application followed by a hyphen.</para>
<para>Documents are installed under the <filename>help</filename>
subdirectory in <envar>$XDG_DATA_HOME</envar> or in the
<envar>$XDG_DATA_DIRS</envar> path. See the
<ulink url="http://standards.freedesktop.org/basedir-spec/latest/">XDG
Base Directory Specification</ulink> for details on <envar>$XDG_DATA_HOME</envar>
and <envar>$XDG_DATA_DIRS</envar>. Each <filename>help</filename>
directory in the path contains subdirectories for languages. Each
language subdirectory contains subdirectories for documents, where
the name of each subdirectory matches the document identifier of
a document.</para>
<para>The <emphasis>document path</emphasis> for a given document
is the list of directories of the following form:</para>
<programlisting><replaceable>datadir</replaceable>/help/<replaceable>lang</replaceable>/<replaceable>document</replaceable></programlisting>
<variablelist>
<varlistentry>
<term><filename><replaceable>datadir</replaceable></filename></term>
<listitem><para>Either <envar>$XDG_DATA_HOME</envar> or a directory in
the <envar>$XDG_DATA_DIRS</envar> path.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename><replaceable>lang</replaceable></filename></term>
<listitem><para>The language code of a language in the user's
list of preferred languages.</para></listitem>
</varlistentry>
<varlistentry>
<term><filename><replaceable>document</replaceable></filename></term>
<listitem><para>The document identifier of the document.</para></listitem>
</varlistentry>
</variablelist>
<para>The document path is ordered first according to the position of
<filename><replaceable>datadir</replaceable></filename> in the path, then
by the position of <filename><replaceable>lang</replaceable></filename>
in the user's preferred list of languages. So, for example, if the
user's preferred language list is <systemitem>pt_BT:pt:C</systemitem>,
then <filename>~/.local/share/help/pt/beanstalk</filename> would take
precedence over <filename>/usr/share/help/pt_BR/beanstalk</filename>.</para>
</section>
<section id="uri-scheme">
<title>URI Scheme</title>
<para>Documents are referenced using the <systemitem>help:</systemitem>
URI scheme. The <systemitem>help:</systemitem> URI scheme has the
following form:</para>
<programlisting>help:<replaceable>document</replaceable>/<replaceable>page</replaceable>?<replaceable>options</replaceable>#<replaceable>anchor</replaceable></programlisting>
<variablelist>
<varlistentry>
<term><replaceable>document</replaceable></term>
<listitem><para>The document identifier.</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>page</replaceable></term>
<listitem><para>An identifier for a page within the document. Documents
often consist of multiple logical pages, which may not be reflected in
the actual files on the system. The page identifier is optional. If it
is not present, the preceding <systemitem>/</systemitem> character
should be omitted.</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>options</replaceable></term>
<listitem><para>Additional options that can influence how applications
present a document. Options are optional. If they are not present, the
preceding <systemitem>?</systemitem> character should be omitted. If
they are present, they must conform to the
<systemitem>application/x-www-form-urlencoded</systemitem> MIME type.
Options may be used, for example, to override language settings or to
provide keys for conditional processing. This specification makes no
specific recommendations for the options.</para></listitem>
</varlistentry>
<varlistentry>
<term><replaceable>anchor</replaceable></term>
<listitem><para>An anchor point within a page. Applications should
scroll to an appropriate point whenever possible. The anchor is
optional. If it is not present, the preceding <systemitem>#</systemitem>
character should be omitted.</para></listitem>
</varlistentry>
</variablelist>
<para>Page identifiers and anchors may contain any character that is
valid in a document identifier. Some document types may have further
restrictions on page identifiers or anchors.</para>
</section>
<section id="formats">
<title>Help Formats</title>
<para>Documents may be installed in any format. Not all help applications
may recognize and handle the same types of documents. Whenever possible,
help applications should support HTML. Documents may be installed in
multiple formats. Help applications choose which format to use when
multiple formats are present.</para>
<para>For any format, a help application must map the information found
in the <systemitem>help:</systemitem> URI scheme to the information in
that format. This specification contains recommendations for finding
and handling documents in DocBook, Mallard, HTML, and XHTML.</para>
<section id="docbook">
<title>DocBook</title>
<para>DocBook documents have a file named <filename>index.docbook</filename>
in the document path. Any files referenced from the DocBook file, including
XML fragments included through XInclude, should be looked up according to
the document path.</para>
<para>When a help application displays a DocBook document, it will often
display it in multiple pages or chunks, rather than as a single long page.
The page identifier specifies which chunk to display. Not all applications
will split a DocBook document into chunks in the same way, so the page
identifier may not map exactly to the <sgmltag>id</sgmltag> attribute
of an element that is chunked. In this case, the applicaiton displays
the nearest enclosing chunk and treats the page identifier as an anchor
if no anchor was explicitly provided.</para>
</section>
<section id="mallard">
<title>Mallard</title>
<para>Mallard documents have a file named <filename>index.page</filename>
in the document path. Other page files may be different directories in
the document path. Any files referenced in any page file, including XML
fragments included through XInclude, should be looked up according to
the document path.</para>
<para>The page identifier specifies the id of a Mallard page file. The
anchor specifies the id of a section within a Mallard page file.</para>
</section>
<section id="html">
<title>HTML and XHTML</title>
<para>HTML documents have a file named <filename>index.html</filename>
in the document path. XHTML documents have a file named <filename>index.xhtml</filename>
in the document path. Other HTML or XHTML files in the document may
be in different directories in the document path. Any files referenced
in any HTML or XHTML page, including XML fragments included through
XInclude in XHTML, should be looked up according to the document path.</para>
<para>The page identifier specifies the base file name, without the
<filename>.html</filename> or <filename>.xhtml</filename> extension,
of an HTML or XHTML file in the document. The anchor specifies a named
anchor within the HTML or XHTML file.</para>
</section>
</section>
</article>
|