This repository was archived by the owner on Jan 30, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 14
Expand file tree
/
Copy pathFileFormat.html
More file actions
780 lines (657 loc) · 16.3 KB
/
FileFormat.html
File metadata and controls
780 lines (657 loc) · 16.3 KB
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>JavaHelp 1.0 - File Formats</title>
</head>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000">
<h1 align=center>
<IMG ALT="JavaHelp" SRC="../images/superhero.big.gif" WIDTH=64>
<br>
JavaHelp<sup><font size="-2">TM</font></sup> 1.0 - File Formats</h1>
<h2 align=center>
<a href="Copyright.html">Copyright 1998-1999 Sun Microsystems</a>
</h2>
<HR>
<h2>Overview</h2>
The JavaHelp system defines the file formats for the meta
data files: HelpSet
file, Map file, and the data for the standard TOC and
Index views.
The file formats used in JavaHelp are based on industry standards:
<ul>
<li>
The HelpSet (help content and meta information) is encapsulated
and compressed using the JAR (Java Archive) format.</li>
<li>
Map, table of contents and index file models are described in
<a href="http://www.w3.org/TR/xml">XML</a>.
<li>
The HelpSet file is based on the Extended Markup Language (XML) as
defined by the World Wide Web Consortium (<A HREF="http://w3c.org/XML/"><tt>http://w3c.org/XML/</tt>)</A>.</li>
<li>
Localization is done following the I18N Java conventions.</li>
</ul>
<p>
JavaHelp provides for an extensible set of navigational types, but predefines
a few types. The standard types are:
<ul>
<LI>
<tt>javax.help.TOCView</tt> for the <A HREF="#toc">Table of Contents.</A></LI>
<LI>
<tt>javax.help.IndexView</tt> for the <A HREF="#index">Index.</A></LI>
<LI>
<tt>javax.help.SearchView</tt> for the <A HREF="#search">Search.</A></LI>
</UL>
The typical files involved in a HelpSet are:
<UL>
<LI>
<A HREF="#HelpSet">HelpSet file</A>: Identifies the map, and navigational
views (e.g. TOCs, indexes and search database files).</LI>
<LI>
<A HREF="#map">Map file(s)</A>: Defines the map that associates topic
IDs used
by the application to refer to HTML topic files.</LI>
<LI>
<A HREF="#toc">Table of contents:</A> Defines the table of contents entries,
their structure,
and the IDs to which they map</LI>
<LI>
<A HREF="#index">Index:</A> Defines the index entries and the IDs to
which they map</LI>
<LI>
<A HREF="#search">Search Database:</A> The search database searched
by the search engine. The default search database is created
using the JavaHelp system <tt>jhindexer</tt> command.
</LI>
<LI>
<A HREF="#content">Content</A>: The HTML topic files that provide information
to help users</LI>
</UL>
<p>
Document Type Definitions (DTDs) for HelpSet, Map, TOC View and Index View
data are included in this specification and can be used for validation.
In each of these cases,
the valid documents are those valid XML documents conformant with the DTD
except that the DOCTYPE section must not have any inner DTD subset
(this is the same restriction used in the W3C SMIL recommended specification).
<p>
<A HREF="http://java.sun.com/products/jdk/1.1/docs/guide/jar/index.html">JAR</A>
is used to encapsulate and compress a HelpSet into a single file.
Encapsulation and compression are not required, but recommended in most
production environments.</P>
<hr>
<A NAME="HelpSet"></A>
<H2>
HelpSet File</H2>
<P>
The HelpSet file is
<a href="I18N.html">localized</a>
following the same naming conventions used with
ResourceBundle. Once a HelpSet file for a given locale
has been found, no additional localization searches are
needed, which is very important in a networked
environment.</P>
<H3>Format</H3>
<p>
HelpSet files are encoded in an XML-based syntax;
The DTD is
<a href="dtd/helpset_1_0.dtd">dtd/helpset_1_0.dtd</a>.
The top level tag is
<tt><helpset></tt>.
A version attribute is optional, when present
its value must be "1.0".
</p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>helpset
<td>HelpSet definition
<td>top-level
<td>none
<td>
<table>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
<tr>
<th><tt>version</tt>="1.0"</th>
<td>(optional) version
</tr>
</table>
</tr>
</table>
<p>
<p>
The HelpSet file is organized into sections within the
<tt><helpset></tt> tag.
There is a section for ID maps,
sections for the navigational views,
and a final section for subhelpsets.
The general outline of a HelpSet file is:</p>
<pre>
<font size="-1">
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
"http://java.sun.com/products/javahelp/helpset_1_0.dtd">
<!-- next is a Processing Instruction (PI).
This is ignored by the Reference Implementation -->
<?MyFavoriteApplication this is data for my favorite application ?>
<helpset version="1.0">
<!-- Global properties -->
<title>My Title</title>
<!-- maps section -->
<maps>
<homeID>my homeID</homeID>
<mapref location="url"/>
</maps>
<!-- Zero or more View sections -->
<view>
<name>TOC</name>
<type>javax.help.TOCView></type>
<data>jar:file:/c:/Program Files/JW3.0/JW3.0.jar!/TOC.xml</data>
</view>
<!-- Optional subHelpSet section >
<subhelpset location="file:/c:/Foobar/HelpSet1.hs"/>
</helpset>
</FONT>
</pre>
<p>
Whenever a relative URL specification appears in a HelpSet, it is to
be interpreted relative to the URL of the HelpSet (note that the constructor
for a HelpSet takes a URL).</p>
<h3>Processing Instructions</h3>
<p>
The reference implementation ignores the Processing Instructions.
<a name="global">
<h3>HelpSet properties</h3></a>
A HelpSet has a title that is used mostly in the presentation.
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>title
<td>Title of the HelpSet
<td>helpset
<td>Actual title
<td>none
</tr>
</table>
<a name="map section">
<h3>ID Map Section</h3></a>
<p>
The second section of a HelpSet file contains information
on the mapping of IDs to URLs used for context sensitive
help. The homeId tag provides the default entry to present
when a HelpSet is first shown.
The mapref tag provides a reference to a map file.
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>maps
<td>Map definition
<td>helpset
<td>empty
<td>none
</tr>
<tr>
<th>homeID
<td>Default ID of the HelpSet
<td>maps
<td>ID string
<td>none
</tr>
<tr>
<th>mapref
<td>URL to map
<td>maps
<td>empty
<td>location, the spec relative to HelpSet
</tr>
</table>
<p>
Finally, an ID Map section corresponding to a Bean
will want to include a topic ID corresponding to the
<a href="Beans.html#beaninfo">BeanInfo.getHelpId()</a>.
If there is a single Bean for this HelpSet file,
the value of
<tt><homeID></tt>
could be used.
If several Beans share the HelpSet file,
several topic IDs are needed</p>
<p>
<h4>Map Example</h4>
The following is an example of a map definition in a HelpSet file:
<pre>
<font size="-1">
<map>
<data>jar:file:/c:Program Files/JWS3.0/JW3.0.jar!/TheMap.map</data>
<data>jar:http://www.sun.com/devpro/JWS3.0Encyclopedia.jar!/TheMap.map</data>
</map>
</font>
</pre>
<p>
<em>NOTE: </em>There is a bug in the JavaHelp 1.0 reference
implementation which only supports one map.
<a name="navigational views">
<h3>Navigational Views Section</h3></a>
<p>
The final sections of a HelpSet file describe the
navigational views, which include tables of contents,
indices, and search. There are three mandatory tags for each
view: <tt><label></tt>, <tt><name></tt>, and <tt><type></tt>.
Additionally, most views will define <data>.
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>view
<td>View definition
<td>helpset
<td>none
<td><tt>xml:lang</tt>
</tr>
<tr>
<th>name
<td>a name identifying the view
<td>view
<td>text of the name
<td>none
</tr>
<tr>
<th>label</th>
<td>a label to show in the presentation
<td>view
<td>text for the label
<td>none
</tr>
<tr>
<th>type
<td>a subclass of NavigatorView
<td>view
<td>name of the class
<td>none
</tr>
<tr>
<th>data
<td>URL spec
<td>view
<td>text of the spec
<td>optional "engine", a class implementing SearchEngine
</tr>
</table>
<p>
The language specified in the <tt>xml:lang</tt> attribute of name
must not be different that of the view, if that was given explicitly.
The language specified in the <tt>xml:lang</tt> attribute of view
must not be different to that the HelpSet, if that was given explicitly.
<p>
<h4>View Example</font></h4>
The following is an example of a view section in a HelpSet file:
<pre>
<font size="-1">
<view>
<name>TOC</name>
<name>Table of Contents</name>
<type>javax.help.TOCView</type>
<data>jar:file:/c:Program Files/JWS3.0/JW3.0.jar!/toc.xml</data>
</view>
</font>
</pre>
<a name="subHelpSet section">
<h3>SubHelpSet Section</h3></a>
<p>
A HelpSet file can statically include other HelpSets
using the <tt><subhelpset></tt> tag.
The HelpSets indicated using this tag are <em>merged</em> automatically
into the HelpSet where the tag is included.
If the URL spec refers to a non-existing file,
the subhelpset tag is silently ignored;
this permits an enclosing HelpSet to refer to subhelpsets that may
or not be installed.
More details about merging can be found in <a href="Merge.html">Merge</a>.
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>subhelpset
<td>Static subHelpSet to merge
<td>helpset
<td>empty
<td>location="URL spec to HelpSet file"
</tr>
</table>
<p>
<hr>
<A NAME="map">
<h2>Map Files</h2></A>
<p>
Each map file provides a mapping of topic IDs to URLs.
Map files are encoded in an XML-based syntax;
The DTD is
<a href="dtd/map_1_0.dtd">dtd/map_1_0.dtd</a>.
The top level tag is
<tt><map></tt>.
A version attribute is optional, when present
its value must be "1.0".
<p>
The main tag is <tt>mapID</tt>
relating a topic ID and a URL specification.
Relative URL
specifications are to be resolved against the absolute URL for
the map file.</p>
A Map can contain only the following two tags:
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>map
<td>A Map
<td>top level
<td>empty
<td>
<table>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
<tr>
<th><tt>version</tt>="1.0"</th>
<td>(optional) version
</tr>
</table>
</tr>
<tr>
<th>mapID
<td>An individual map entry
<td>empty
<td>map
<td>
<table>
<tr>
<th>target="string"</th>
<td>ID
</tr>
<tr>
<th>url="string"</th>
<td>URL spec
</tr>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
</table>
</tr>
</table>
<p>
The following is an example of a simple map file:</p>
<pre>
<FONT size="-1">
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="intro" url="hol/hol.html" />
<mapID target="halloween" url="hol/hall.html" />
<mapID target="jackolantern" url="hol/jacko.html" />
<mapID target="mluther" url="hol/luther.html" />
<mapID target="reformation" url="hol/inforefo.html" />
</map>
</FONT>
</pre>
<p>
Note that the IDs should be unique within the HelpSet
(although they may also appear in a subhelpset of this HelpSet).
</p>
<hr>
<P><A NAME="toc"></A>
<H2>Table of Contents
</H2>
<p>
JavaHelp1.0 specifies one table of contents type:
<tt>javax.help.TOCView</tt>.
This navigational view models a table of contents.
TOC files are encoded in an XML-based syntax;
The DTD is
<a href="dtd/map_1_0.dtd">dtd/toc_1_0.dtd</a>.
The top level tag is
<tt><toc></tt>.
A version attribute is optional, when present
its value must be "1.0".
<p>
A TOC can contain only the following two tags:
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>toc
<td>Table of contents
<td>top level
<td>empty
<td>
<table>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
<tr>
<th><tt>version</tt>="1.0"</th>
<td>(optional) version
</tr>
</table>
</tr>
<tr>
<th>tocitem
<td>Table of contents item. Tags can be nested to create
hierarchical entries.
<td>Text to show in the presentation
<td>toc, tocitem
<td>
<table>
<tr>
<th>target="string"</th>
<td>destination ID
</tr>
<tr>
<th>image="string"</th>
<td>destination ID
</tr>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
</table>
</tr>
</table>
<p>
<h4>Table of Contents Example</h4>
The following is an example of a table of contents file:
<pre>
<font size="-1">
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE toc
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
"http://java.sun.com/products/javahelp/toc_1_0.dtd">
<toc version="1.0">
<tocitem>Introducing JavaHelp
<tocitem target="api" image="image/document.gif">
JavaHelp API
</tocitem>
<tocitem target="platform" image="image/document.gif">
JavaHelp platforms
</tocitem>
</tocitem>
</toc>
</font>
</pre>
<hr>
<A NAME="index"></A>
<h2>Index</h2>
<p>
JavaHelp1.0 specifies one index navigator view:
<tt>javax.help.IndexView</tt>.
This navigational view models an index.
Index files are encoded in an XML-based syntax;
The DTD is
<a href="dtd/map_1_0.dtd">dtd/index_1_0.dtd</a>.
The top level tag is
<tt><index></tt>.
A version attribute is optional, when present
its value must be "1.0".
<p>
An index can contain the following two tags:
<p>
<table border=1 cellpadding=5>
<tr>
<th>Tag
<th>Description
<th>Allowed In
<th>Body
<th>Attributes
</tr>
<tr>
<th>index
<td>Index
<td>top-level
<td>empty
<td>
<table>
<tr>
<th><tt>xml:lang</tt>="lang"</th>
<td>Language for this item
</tr>
<tr>
<th><tt>version</tt>="1.0"</th>
<td>(optional) version
</tr>
</table>
</tr>
<tr>
<th>indexitem
<td>Index item. <tt>indexitem</tt> tags can be nested to
create hierarchical entries.
<td>index, indexitem
<td>text to show in the presentation
<td>
<table>
<tr>
<th>target="string"</th>
<td>destination ID
</tr>
<tr>
<th><tt>xml:lang</tt>="lang"
<td>what language to use
</tr>
</table>
</tr>
</table>
<p>
<h4>Index Example</h4>
The following is an example of an index file:
<pre>
<font size="-1">
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE index
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
"http://java.sun.com/products/javahelp/index_1_0.dtd">
<index version="1.0">
<indexitem>Java Applets
<indexitem target="applet_over">
Overview
</indexitem>
<indexitem>Usage
<indexitem target="applet_insert">
Inserting an applet in a content page
</indexitem>
<indexitem target="applet_editing">
Editing an applet in a content page
</indexitem>
</indexitem>
</indexitem>
</index>
</font>
</pre>
<hr>
<A NAME="content"></A>
<H2>
Help Content</H2>
JavaHelp displays help topic files formatted using HTML version 3.2.
Links are resolved
using the URL protocols supported by the underlying platform.
Lightweight
JComponents can be added to topic pages using the <tt><OBJECT></tt>
tag.
</p>
<hr>
<A NAME="search"></A>
<H2>
Search Database</H2>
<p>
JavaHelp1.0 specifies one search navigator view:
<code>javax.help.SearchView</code>.
This navigational view models a search interacting with a search
database though objects that implement the
<code>javax.help.search</code> package.
The view has an <tt><engine></tt> tag that is the name of
a class that is a subclass of <code>SearchEngine</code>.
That class is responsible for interpreting
the search database that is described by the
URL in <tt><data></tt>.</p>
<hr>
JavaHelp<sup>TM</sup> 1.0
<br>
Send your comments to
<a href="mailto:javahelp-comments@eng.sun.com">
javahelp-comments@eng.sun.com</a>
<br>
<!-- Created: Fri Sep 26 23:43:53 PDT 1997 -->
<!-- hhmts start -->
Last modified: Mon Apr 12 17:07:13 MDT 1999
<!-- hhmts end -->
</body>
</html>