No other HTML tags should be embedded in the Content as they
may not produce the expected results. No hyperlinks or images
are supported!
Note that while the content itself may be localized, the HTML tags
embedded within the content should be left in ASCII.
*BOTH TITLE AND CONTENT MUST BE LOCALIZED!*
2.3 Keywords
Users may search the collection of help articles by specifying one
or more keywords (in the locale's representation) which are matched
against the set of Articles. Those articles whose keyword list has
one or more matches with the user's list will then be viewable.
Each Article may specify a (possibly empty) list of keywords
separated by whitespace and containing no commas or punctuation.
The whitespace in this list of keywords is used only to separate
individual keywords.
Each Keyword in the list must be a string of localizable
alphanumeric text containing no whitespace (punctuation marks such
as "-" may be OK).
*KEYWORDS MUST BE LOCALIZED!*
2.4 See-Also
Each article may refer to other Articles by presenting the user
with a "See-Also" list when the Article is viewed. This user's
view of this list contains the Titles of the specified articles,
and clicking a title causes that article to be presented.
The See-Also list associated with a particular Article consists of
a (possibly empty) list containing Tags of other articles separated
by whitespace and containing no commas or punctuation. The list of
Titles corresponding to these Tags will be displayed to the user in
the same order that it appears in the definition of the Article.
*SEE-ALSO ITEMS ARE NOT TO BE LOCALIZED!*
3. Notes on Representation of Content
The internal representation of the Content component of each
article is as a single (long) Java String.
Java permits the static initialization of Strings to use
catenation on the right-hand side of the assignment.
For example, the Java statements
String s = "foo bar";
and
String s = "foo" + " " + bar;
will result in an identical assignment.
Since the HTML rendering process which displays the resource to
the user ignores whitespace and line breaks, the initializations
of Content strings in the Help ResourceBundle exploit this approach
to make the code more readable and facilitate the localization
process.
Note that the breaking up of the Content string into source lines is
transparent to the application; details of the source file's
appearance can change across localizations (assuming that tag names
are maintained correctly).
As an example, consider the ResourceBundle entry which defines the
Content portion of a help article whose tag is "ToDeletePrinter".
This entry might appear in the ResourceBundle source as
{ "ToDeletePrinter.content",
"This is some help content which would extend across several " +
"lines of text if it were all in a single long string. " +
"Since we can separate the one long string into several " +
"short ones, " +
"the source file is much more easily readable. "
}
4. Previewing Help Article Content
It is possible to use an ordinary HTML browser to view the Content of
all the help Articles in a ResourceBundle. To do so requires the
extraction and formatting of the strings in the ResourceBundle which
comprise the Content portions of all included Articles.
One approach is to create a simple script which acts as a filter; its
input is the pmHelpResources.java ResourceBundle source file and its
output is a stream of HTML which can be saved to a file and viewed in
a browser.
The use of such a script can facilitate the localization process by
enabling localization teams to view a particular version of the
ResourceBundle as work on it progresses.
An example of a script which performs the required formatting and
extraction is as follows:
-----------------------
#!/bin/ksh
#
# Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
# All rights reserved.
#
# This filter accepts a pmHelpResources.java file as input
# and produces formatted HTML as output.
#
while read line; do
echo "$line" | grep '^.*{".*\.tag"' > /dev/null
if [[ $? == 0 ]]; then
print -n "