diff options
| -rw-r--r-- | help-system/help-system-spec.xml | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/help-system/help-system-spec.xml b/help-system/help-system-spec.xml new file mode 100644 index 0000000..ffe1a5d --- /dev/null +++ b/help-system/help-system-spec.xml @@ -0,0 +1,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> |