summaryrefslogtreecommitdiffstats
path: root/help-system/help-system-spec.xml
blob: ffe1a5d4cb6c64f27d740ff90334b7b05d235e29 (plain)
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>