From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../creating_a_help_content_pack/index.html | 200 +++++++++++++++++++++ files/zh-cn/archive/mozilla/help_viewer/index.html | 22 +++ 2 files changed, 222 insertions(+) create mode 100644 files/zh-cn/archive/mozilla/help_viewer/creating_a_help_content_pack/index.html create mode 100644 files/zh-cn/archive/mozilla/help_viewer/index.html (limited to 'files/zh-cn/archive/mozilla/help_viewer') diff --git a/files/zh-cn/archive/mozilla/help_viewer/creating_a_help_content_pack/index.html b/files/zh-cn/archive/mozilla/help_viewer/creating_a_help_content_pack/index.html new file mode 100644 index 0000000000..2a64c576e7 --- /dev/null +++ b/files/zh-cn/archive/mozilla/help_viewer/creating_a_help_content_pack/index.html @@ -0,0 +1,200 @@ +--- +title: Creating a Help Content Pack +slug: Archive/Mozilla/Help_viewer/Creating_a_Help_Content_Pack +translation_of: Archive/Mozilla/Help_viewer/Creating_a_Help_Content_Pack +--- +

Original doc: http://www.mozilla.org/projects/help.../content_packs I hesitate to call it "original", tho, because I've basically rewritten the entire thing so that it's easier and faster to use to create Help content. The previous document had a lot of places where ideas were simply introduced without explanation, and I've tried to go through things a bit more slowly with better descriptions. This is still very much a work in progress, tho, and I need to complete the rest of it soon (where "complete" means "use what's there that's good, build on the stuff that's not as good, and add other useful information as necessary".

+

This document describes how to integrate HTML help documentation into your application using the Mozilla Help Viewer. Documentation contained in the Help Viewer can be accessed using any XUL application or program that embeds Mozilla.

+

What is a Content Pack?

+

A Content Pack is a packaged set of files that describe Help content. Content Packs include help documents written in XHTML, a content pack descriptor file written in RDF, and a table of contents, index, and glossary (also written in RDF). You can create a content packs which inherit from existing Mozilla Help content packs.

+

The Contents of a Content Pack

+

Content Packs consist of a general pack description file, table of contents, index, search, glossary, and help documents. The help documents are written in XHTML, and the rest are written in RDF. The content pack descriptor file outlines the framework of the contents of the pack by pointing to the files describing the table of contents, index, and glossary RDF files. The table of contents and index files are simple tree-based outlines written in RDF. The glossary file is written in RDF and consists of a simple list of terms with corresponding URLs to the term definition.

+

Creating a Content Pack

+

The Content Pack Descriptor File

+

As mentioned earlier, the content pack descriptor file is written using RDF. If you don't know RDF, that's okay - for our purposes, you won't need to learn very much. If you understand the basics of HTML or (preferably) XML, you'll understand the very basics of the syntax - elements, attributes, and element contents. Understanding the syntax is important because small syntax errors can mean that a whole file won't be loaded correctly. However, while it may seem like this is a disadvantage, it's actually an advantage - if you make an error you'll know immediately, and you should be able to easily figure out what the problem is by directly loading the file in Firefox. Later, when we get to actually writing content, you'll need to know XHTML, but for now knowledge of the syntax should be enough.

+

Open up your favorite text editor and create the file content-pack.rdf. Insert into it the following text:

+
<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#">
+
+</rdf:RDF>
+
+

If you're familiar with HTML or XML, you might recognize this as the container element for the whole document. It serves as a wrapper around the entire contents of the file, marking it as RDF.

+

Next, you'll need to insert a rdf:Description element into the file, inside the rdf:RDF element just created:

+
    <rdf:Description rdf:about="urn:root"
+                     nc:title=""
+                     nc:defaulttopic=""
+                     nc:base="">
+    </rdf:Description>
+
+

Fill in the attributes as follows:

+ +

Next, we need to describe where to find the glossary, index, and table of contents. (We're still not actually to the point where we're describing the actual data in each of these, so we'll just use some filler data for now.) Add the following code inside the rdf:Description element you just created:

+
      <nc:panellist>
+        <rdf:Seq>
+
+        </rdf:Seq>
+      </nc:panellist>
+
+

You'll create the relevant information descriptions within the rdf:Seq element.

+

The location of each of the glossary, index, and table of contents data sources is stored in one rdf:Description element contained within one rdf:li element, like so:

+
            <rdf:Seq>
+                <rdf:li>
+                    <rdf:Description nc:panelid="glossary"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
+                </rdf:li>
+                <rdf:li>
+                    <rdf:Description nc:panelid="toc"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
+                </rdf:li>
+                <rdf:li>
+                    <rdf:Description nc:panelid="index"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/>
+                </rdf:li>
+            </rdf:Seq>
+
+

The Help Viewer UI may or may not provide a panel for each of these data sources. In Firefox 1.0 each data source had a panel. Starting with Firefox 1.1 and the Mozilla 1.8 platform, only the table of contents data source will be displayed. The glossary and index data sources will be + + hidden + - information found only in them will not be displayed unless the user conducts a search of the Help pack that would return glossary or index results.XXX this sentence is ugly - a little rewording help here would be nice

+

A data source description is pretty much the same no matter which type you're defining, and the syntax is pretty simple. Each panel is specified by one rdf:Description element with the following attributes:

+ +
                <!-- Assumptions:
+                     win-toc.rdf contains Windows- and OS/2-specific info,
+                     unix-toc.rdf contains Linux- and Mac-specific info. -->
+                <rdf:li>
+                    <rdf:Description nc:panelid="toc"
+                                     nc:platform="win os2"
+                                     nc:datasources="win-toc.rdf"/>
+                </rdf:li>
+                <rdf:li>
+                    <rdf:Description nc:panelid="toc"
+                                     nc:platform="unix mac"
+                                     nc:datasources="unix-toc.rdf"/>
+                </rdf:li>
+
+

There's one final element to add inside rdf:Seq to complete the content pack descriptor file: an element to describe the Help Viewer's search function. Search automatically goes through all of the elements in the table of contents, index, and glossary, but you might wish to have Search go through more sources of data. One possible source might be an online, dynamically-generated list of added content stored on your web site. To have the Help Viewer search through these additional data sources, define another rdf:li element like so:

+
                <rdf:li>
+                    <rdf:Description nc:panelid="search"
+                                     nc:datasources=""
+                                     nc:emptysearchtext="[No matching items found.]"
+                                     nc:emptysearchlink="chrome://foo/locale/bar.html"/>
+                </rdf:li>
+
+ +

Note that you can use the nc:datasources attribute to inherit content from other content packs. One common use of this is to inherit the small Using the Help Window article provided with the viewer. For example, the following code uses a datasource outside the content pack you have created to include the article in a table of contents:

+
                <rdf:li>
+                    <rdf:Description nc:panelid="toc"
+                                     nc:datasources="chrome://help/locale/help-toc.rdf chrome://foo/locale/help/glossary.rdf"/>
+                </rdf:li>
+
+
+

Each of the different data source types (toc, index, glossary, and search) may be used multiple times (and in the case of platform-specific information, must be used multiple times). However, it is recommended you use a space-separated list of URIs for nc:datasources instead of separate entries, as separate entries will require a slightly longer time to load.

+

The Glossary File

+

The glossary file has the simplest format of all the data sources you'll need because there's only one level of content. (The index, table of contents, and search data sources are more likely to be nested, complicating their formats.) Create a new RDF file (for now let's name it glossary.rdf), and add the following lines to it:

+
<?xml version="1.0"?>
+
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#">
+
+  <rdf:Description rdf:about="urn:root">
+    <nc:subheadings>
+      <rdf:Seq>
+
+
+      </rdf:Seq>
+    <nc:subheadings>
+  </rdf:Description>
+
+</rdf:RDF>
+
+

This forms the outer framework of a glossary description file. To add data to it, add one of the following per entry in your glossary within the rdf:Seq above:

+
        <rdf:li>
+          <rdf:Description nc:name=""
+                           nc:link=""/>
+        </rdf:li>
+
+

The rdf:li element serves purely to contain each separate entry. The rdf:Description element describes the glossary entry. It has two required attributes: nc:name and nc:link. nc:name is the name for the entry - it's what's currently displayed in the glossary as the entry's title. nc:link contains a URI referencing what will be displayed in the viewer when the entry is accessed.

+

The Index File

+
+

One important note on the index file is that there is no automatically generated set of top-level letters (e.g., A for Accessibility and Automation or B for Book and Border). Help documentation may be written in any language, so such automatic splitting is not desirable. You must implement such splitting if you wish to have it.

+
+

The index data source structurally differs from the glossary in that it is more likely to have multiple levels. A single-level index may be accomplished in exactly the same way as a glossary file, but multiple levels can make it easier to navigate to specific information. Let's start with a brief sample RDF file with a single level:

+
<?xml version="1.0"?>
+
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#">
+
+  <rdf:Description rdf:about="urn:root">
+    <nc:subheadings>
+      <rdf:Seq>
+        <rdf:li><rdf:Description nc:link="foo.html" nc:title="Foo"/></rdf:li>
+        <rdf:li><rdf:Description nc:link="baz.html" nc:title="Baz"/></rdf:li>
+      </rdf:Seq>
+    <nc:subheadings>
+  </rdf:Description>
+
+</rdf:RDF>
+
+

There's not much here: a single level containing the two entries "Foo" and "Baz". Now, let's say you want to add an entry "bar" underneath "Foo". How would you do this? First, you need to add an attribute to the "Foo" entry so that you can precisely refer to it. The rdf:ID attribute serves this purpose. It should be unique both within file and within the data sources in your content pack to ensure clarity.

+

 

+
        <rdf:li><rdf:Description rdf:ID="foo" nc:link="foo.html" nc:title="Foo"/></rdf:li>
+
+

Next, add the following to your file just after the existing rdf:Description element:

+
  <rdf:Description rdf:about="#foo">
+    <nc:subheadings>
+      <rdf:Seq>
+        <rdf:li><rdf:Description rdf:ID="bar" nc:link="bar.html" nc:title="bar"/></rdf:li>
+      </rdf:Seq>
+    </nc:subheadings>
+  </rdf:Description>
+
+

Except for the different value for rdf:about, this looks exactly like a top-level entry definition. The difference is a result of how RDF works. In RDF data describes data. Top-level entries describe the root node, urn:root; nested entries describe other entries. You can refer to an entry by giving the entry a unique rdf:ID attribute. Then, to describe that entry, you set an rdf:about attribute to the value of the entry's rdf:ID, prefixed by a #.

+

Nesting as described above works exactly the same no matter how deeply or shallowly nested your entry is. Nesting theoretically can work to any number of levels, but for practical reasons nesting is limited to roughly 20 levels. If you're coming anywhere close to this limit, however, you probably should be considering exactly why you need so much nesting.

+

The Table of Contents File

+

The table of contents file is the most important data source you'll create. The help viewer will display the table of contents when you start the viewer. In some versions of the viewer, it will be the + + only + data source ever directly displayed. It's the primary way to provide a structured view of the help you provide to users.

+

The table of contents also provides the list of topics from which the home page for the viewer will be chosen. Recall that in the content pack descriptor file you included an nc:defaulttopic attribute, which defaulted to "welcome". The value of that attribute is the rdf:ID of the topic you want displayed when the viewer is loaded.

+

The table of contents data source is exactly like an index data source, and if you have a working index data source you could use it as a table of contents with no changes whatsoever. See the instructions on creating glossary and index data sources to learn how to create a table of contents.

+

Additional Search Databases

+

Starting with Firefox 1.1, you can define additional information databases through which the help viewer will search. The data from these may never even be displayed to the user, but if he tries to search through Help, he will see results from these databases.

+

Defining a search database is exactly like defining a table of contents file (and therefore exactly like creating an index file), so follow the instructions there to create additional data sources as you need them.

+

Viewing your Content Pack in the Help Viewer

+

To launch the Help Viewer with your content pack, you need to have chrome://help/content/contextHelp.js loaded into the XUL file that provides the UI to open the help viewer:

+
  <script type="application/x-javascript"
+          src="chrome://help/content/contextHelp.js"/>
+
+

This will allow you to access all of the viewer functions. To open the Help Viewer, run the openHelp() function. It's exactly the same as any JavaScript command, you you can insert it in command elements, oncommand attributes, and other such places. The parameters are described below:

+
openHelp(aTopic, aContentPackSpec);
+
+ +

Here is an example of how Firefox opens its help documentation:

+
openHelp('firefox-help', 'chrome://browser/locale/help/help.rdf');
+
+

Packing It All Up

+
+  
+

diff --git a/files/zh-cn/archive/mozilla/help_viewer/index.html b/files/zh-cn/archive/mozilla/help_viewer/index.html new file mode 100644 index 0000000000..051ffdd64c --- /dev/null +++ b/files/zh-cn/archive/mozilla/help_viewer/index.html @@ -0,0 +1,22 @@ +--- +title: Help Viewer +slug: Archive/Mozilla/Help_viewer +translation_of: Archive/Mozilla/Help_viewer +--- +

Help Viewer: Allows information to be shown to the user inside Mozilla.

+

Introduction

+

Computers and software are incredibly complex. Naturally, then, everyone needs a little help now and then, and getting that help to the user is critical to making applications useful. Consequently, the Mozilla platform provides a cross-platform help viewer along with a framework for providing built-in help documentation. Mozilla's help viewer makes providing documentation an easy job, and this document will describe how you can use it.

+ +

Articles & Tutorials

+ +

Other Resources

+ +
+  
+

-- cgit v1.2.3-54-g00ecf