initial commit

2 files changed, 222 insertions, 0 deletions

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
+---
+<p><span class="comment">Original doc: <a class="external" href="http://www.mozilla.org/projects/help-viewer/content_packs" rel="freelink">http://www.mozilla.org/projects/help.../content_packs</a> 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".</span></p>
+<p>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.</p>
+<h3 id="What_is_a_Content_Pack.3F" name="What_is_a_Content_Pack.3F">What is a Content Pack?</h3>
+<p>A Content Pack is a packaged set of files that describe Help content. Content Packs include help documents written in <a href="cn/XHTML">XHTML</a>, a content pack descriptor file written in <a href="cn/RDF">RDF</a>, 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.</p>
+<h3 id="The_Contents_of_a_Content_Pack" name="The_Contents_of_a_Content_Pack">The Contents of a Content Pack</h3>
+<p>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.</p>
+<h3 id="Creating_a_Content_Pack" name="Creating_a_Content_Pack">Creating a Content Pack</h3>
+<h4 id="The_Content_Pack_Descriptor_File" name="The_Content_Pack_Descriptor_File">The Content Pack Descriptor File</h4>
+<p>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.</p>
+<p>Open up your favorite text editor and create the file <code>content-pack.rdf</code>. Insert into it the following text:</p>
+<pre>&lt;?xml version="1.0"?&gt;
+&lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#"&gt;
+
+&lt;/rdf:RDF&gt;
+</pre>
+<p>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.</p>
+<p>Next, you'll need to insert a <code>rdf:Description</code> element into the file, inside the <code>rdf:RDF</code> element just created:</p>
+<pre>    &lt;rdf:Description rdf:about="urn:root"
+                     nc:title=""
+                     nc:defaulttopic=""
+                     nc:base=""&gt;
+    &lt;/rdf:Description&gt;
+</pre>
+<p>Fill in the attributes as follows:</p>
+<ul>
+ <li><b>rdf:about</b> must be <code>urn:root</code> or your pack won't work. This attribute marks the start point in the RDF graph described by the file, and the Help Viewer searches for this element in order to query for further information (stored in child elements) about the content pack being parsed.</li>
+ <li><b>nc:title</b> is where you specify the title (e.g., "Mozilla Firefox Help") for the Help Window. This attribute is <b>required</b>.</li>
+ <li><b>nc:defaulttopic</b> will hold the <code>rdf:ID</code> of the topic you want displayed when the viewer first loads if none has been specified. This attribute also specifies what topic is loaded when the user hits the Home button in the viewer. We'll get to exactly how to fill in this attribute later. This attribute is <b>optional</b>, with fallback to the value <code>welcome</code>.</li>
+ <li><b>nc:base</b> contains the base URL relative to which the Help content referenced in the descriptor file is located. For example, if your glossary, index, and table of contents RDF files are all located at <code><a class="external" rel="freelink">chrome://myapp/locale/help/*</a></code>, then you could put <code><a class="external" rel="freelink">chrome://myapp/locale/help/</a></code> here and use only the actual file names without path when needed later. You don't actually need this attribute if you don't want it, but it's a useful shorthand to save typing.</li>
+</ul>
+<p>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 <code>rdf:Description</code> element you just created:</p>
+<pre>      &lt;nc:panellist&gt;
+        &lt;rdf:Seq&gt;
+
+        &lt;/rdf:Seq&gt;
+      &lt;/nc:panellist&gt;
+</pre>
+<p>You'll create the relevant information descriptions within the <code>rdf:Seq</code> element.</p>
+<p>The location of each of the glossary, index, and table of contents data sources is stored in one <code>rdf:Description</code> element contained within one <code>rdf:li</code> element, like so:</p>
+<pre>            &lt;rdf:Seq&gt;
+                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="glossary"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/&gt;
+                &lt;/rdf:li&gt;
+                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="toc"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/&gt;
+                &lt;/rdf:li&gt;
+                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="index"
+                                     nc:datasources="chrome://foo/locale/help/glossary.rdf"/&gt;
+                &lt;/rdf:li&gt;
+            &lt;/rdf:Seq&gt;
+</pre>
+<p>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
+ <i>
+  hidden</i>
+ - 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.<span class="comment">XXX this sentence is ugly - a little rewording help here would be nice</span></p>
+<p>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 <code>rdf:Description</code> element with the following attributes:</p>
+<ul>
+ <li><b>nc:panelid</b> specifies the name of the panel, which may be any one of <code>glossary</code>, <code>search</code>, <code>toc</code>, or <code>index</code>. The data source specified by <code>toc</code> will always be displayed, while the other data sources may only be available by searching through the loaded content pack.</li>
+ <li><b>nc:datasources</b> is a space-separated list of RDF datasources used in construction of the structure of referenced topics. Generally, each item in the list will be a URI to an RDF file, but if you're more familiar with RDF you can also refer to a specific node within the RDF file using its <code>rdf:ID</code> attribute.</li>
+ <li><b>nc:platform</b> (added in Mozilla 1.8b2/Firefox 1.1) when present specifies the platforms to which the information stored in the referenced data sources applies. This attribute is useful when some of your help contents only apply to one specific platform. If this attribute is omitted, the information in the data sources applies to
+  <i>
+   all</i>
+  platforms. The attribute is a space-separated list of platform strings. Strings recognized from 1.8 onward are <b>win</b>, <b>mac</b>, <b>os2</b>, and <b>unix</b>; more will be added as required. Unrecognized strings are ignored during parsing. An example of how to use this attribute follows:</li>
+</ul>
+<pre>                &lt;!-- Assumptions:
+                     win-toc.rdf contains Windows- and OS/2-specific info,
+                     unix-toc.rdf contains Linux- and Mac-specific info. --&gt;
+                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="toc"
+                                     nc:platform="win os2"
+                                     nc:datasources="win-toc.rdf"/&gt;
+                &lt;/rdf:li&gt;
+                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="toc"
+                                     nc:platform="unix mac"
+                                     nc:datasources="unix-toc.rdf"/&gt;
+                &lt;/rdf:li&gt;
+</pre>
+<p>There's one final element to add inside <code>rdf:Seq</code> 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 <code>rdf:li</code> element like so:</p>
+<pre>                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="search"
+                                     nc:datasources=""
+                                     nc:emptysearchtext="[No matching items found.]"
+                                     nc:emptysearchlink="chrome://foo/locale/bar.html"/&gt;
+                &lt;/rdf:li&gt;
+</pre>
+<ul>
+ <li><b>nc:panelid</b> should be set to <code>search</code>.</li>
+ <li><b>nc:datasources</b> should be set as with table of contents, index, and glossary definitions.</li>
+ <li><b>nc:platform</b> (added in Mozilla 1.8b2/Firefox 1.1) may be used on search data sources as it's used on table of contents, index, and glossary definitions.</li>
+ <li><b>nc:emptysearchtext</b> specifies the text that is shown when a search through Help returns no results.</li>
+ <li><b>nc:emptysearchlink</b> specifies what URI should be shown when the pseudo-result "no results found" is accessed. This attribute is <b>required</b>. The sample page <code><a class="external" rel="freelink">chrome://help/locale/welcome.xhtml</a></code> has a section on searching which may be a useful link to use here.</li>
+</ul>
+<p>Note that you can use the <code>nc:datasources</code> 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:</p>
+<pre>                &lt;rdf:li&gt;
+                    &lt;rdf:Description nc:panelid="toc"
+                                     nc:datasources="chrome://help/locale/help-toc.rdf chrome://foo/locale/help/glossary.rdf"/&gt;
+                &lt;/rdf:li&gt;
+
+</pre>
+<p>Each of the different data source types (<code>toc</code>, <code>index</code>, <code>glossary</code>, and <code>search</code>) 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 <code>nc:datasources</code> instead of separate entries, as separate entries will require a slightly longer time to load.</p>
+<h4 id="The_Glossary_File" name="The_Glossary_File">The Glossary File</h4>
+<p>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 <code>glossary.rdf</code>), and add the following lines to it:</p>
+<pre>&lt;?xml version="1.0"?&gt;
+
+&lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#"&gt;
+
+  &lt;rdf:Description rdf:about="urn:root"&gt;
+    &lt;nc:subheadings&gt;
+      &lt;rdf:Seq&gt;
+
+
+      &lt;/rdf:Seq&gt;
+    &lt;nc:subheadings&gt;
+  &lt;/rdf:Description&gt;
+
+&lt;/rdf:RDF&gt;
+</pre>
+<p>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 <code>rdf:Seq</code> above:</p>
+<pre>        &lt;rdf:li&gt;
+          &lt;rdf:Description nc:name=""
+                           nc:link=""/&gt;
+        &lt;/rdf:li&gt;
+</pre>
+<p>The <code>rdf:li</code> element serves purely to contain each separate entry. The <code>rdf:Description</code> element describes the glossary entry. It has two required attributes: <code>nc:name</code> and <code>nc:link</code>. <code>nc:name</code> is the name for the entry - it's what's currently displayed in the glossary as the entry's title. <code>nc:link</code> contains a URI referencing what will be displayed in the viewer when the entry is accessed.</p>
+<h4 id="The_Index_File" name="The_Index_File">The Index File</h4>
+<div class="side-note-right">
+ <p>One important note on the index file is that there is <b>no</b> 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.</p>
+</div>
+<p>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:</p>
+<pre>&lt;?xml version="1.0"?&gt;
+
+&lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+         xmlns:nc="http://home.netscape.com/NC-rdf#"&gt;
+
+  &lt;rdf:Description rdf:about="urn:root"&gt;
+    &lt;nc:subheadings&gt;
+      &lt;rdf:Seq&gt;
+        &lt;rdf:li&gt;&lt;rdf:Description nc:link="foo.html" nc:title="Foo"/&gt;&lt;/rdf:li&gt;
+        &lt;rdf:li&gt;&lt;rdf:Description nc:link="baz.html" nc:title="Baz"/&gt;&lt;/rdf:li&gt;
+      &lt;/rdf:Seq&gt;
+    &lt;nc:subheadings&gt;
+  &lt;/rdf:Description&gt;
+
+&lt;/rdf:RDF&gt;
+</pre>
+<p>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 <code>rdf:ID</code> attribute serves this purpose. It should be unique both within file and within the data sources in your content pack to ensure clarity.</p>
+<p> </p>
+<pre class="eval">        &lt;rdf:li&gt;&lt;rdf:Description <b>rdf:ID="foo"</b> nc:link="foo.html" nc:title="Foo"/&gt;&lt;/rdf:li&gt;
+</pre>
+<p>Next, add the following to your file just after the existing <code>rdf:Description</code> element:</p>
+<pre>  &lt;rdf:Description rdf:about="#foo"&gt;
+    &lt;nc:subheadings&gt;
+      &lt;rdf:Seq&gt;
+        &lt;rdf:li&gt;&lt;rdf:Description rdf:ID="bar" nc:link="bar.html" nc:title="bar"/&gt;&lt;/rdf:li&gt;
+      &lt;/rdf:Seq&gt;
+    &lt;/nc:subheadings&gt;
+  &lt;/rdf:Description&gt;
+</pre>
+<p>Except for the different value for <code>rdf:about</code>, 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, <code>urn:root</code>; nested entries describe other entries. You can refer to an entry by giving the entry a unique <code>rdf:ID</code> attribute. Then, to describe that entry, you set an <code>rdf:about</code> attribute to the value of the entry's <code>rdf:ID</code>, prefixed by a <code>#</code>.</p>
+<p>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.</p>
+<h4 id="The_Table_of_Contents_File" name="The_Table_of_Contents_File">The Table of Contents File</h4>
+<p>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
+ <i>
+  only</i>
+ data source ever directly displayed. It's the primary way to provide a structured view of the help you provide to users.</p>
+<p>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 <code>nc:defaulttopic</code> attribute, which defaulted to "welcome". The value of that attribute is the <code>rdf:ID</code> of the topic you want displayed when the viewer is loaded.</p>
+<p>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.</p>
+<h4 id="Additional_Search_Databases" name="Additional_Search_Databases">Additional Search Databases</h4>
+<p>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.</p>
+<p>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.</p>
+<h3 id="Viewing_your_Content_Pack_in_the_Help_Viewer" name="Viewing_your_Content_Pack_in_the_Help_Viewer">Viewing your Content Pack in the Help Viewer</h3>
+<p>To launch the Help Viewer with your content pack, you need to have <code><a class="external" rel="freelink">chrome://help/content/contextHelp.js</a></code> loaded into the XUL file that provides the UI to open the help viewer:</p>
+<pre>  &lt;script type="application/x-javascript"
+          src="chrome://help/content/contextHelp.js"/&gt;
+</pre>
+<p>This will allow you to access all of the viewer functions. To open the Help Viewer, run the <code>openHelp()</code> function. It's exactly the same as any JavaScript command, you you can insert it in <code>command</code> elements, <code>oncommand</code> attributes, and other such places. The parameters are described below:</p>
+<pre>openHelp(aTopic, aContentPackSpec);
+</pre>
+<ul>
+ <li><b>aTopic</b>: the <code>rdf:ID</code> of the topic you want to load as the home page in the help viewer.</li>
+ <li><b>aContentPackSpec</b>: the path to the content pack you want to load.</li>
+</ul>
+<p>Here is an example of how Firefox opens its help documentation:</p>
+<pre>openHelp('firefox-help', 'chrome://browser/locale/help/help.rdf');
+</pre>
+<h3 id="Packing_It_All_Up" name="Packing_It_All_Up">Packing It All Up</h3>
+<div class="noinclude">
+  </div>
+<p></p>
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
+---
+<p>Help Viewer: Allows information to be shown to the user inside Mozilla.</p>
+<h3 id="Introduction" name="Introduction">Introduction</h3>
+<p>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.</p>
+<ul>
+ <li><a class="external" href="http://www.mozilla.org/projects/help-viewer/">Help Viewer Project Page</a></li>
+</ul>
+<h3 id="Articles_&amp;_Tutorials" name="Articles_&amp;_Tutorials">Articles &amp; Tutorials</h3>
+<ul>
+ <li><a href="en/Help_Viewer/Creating_a_Help_Content_Pack">Creating a Help Content Pack</a> <span class="comment">task-oriented, as opposed to spec-type stuff like the link below will be</span></li>
+</ul>
+<h3 id="Other_Resources" name="Other_Resources">Other Resources</h3>
+<ul>
+ <li><a href="en/Help_Viewer/Content_Pack_Specification">Content Pack Specification</a> <span class="comment">a technical description of it, meant primarily to solidify the idea of exactly what constitutes a content pack</span></li>
+</ul>
+<div class="noinclude">
+  </div>
+<p></p>