CDDL HEADER START

The contents of this file are subject to the terms of the

Common Development and Distribution License, Version 1.0 only

(the "License"). You may not use this file except in compliance

with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

or http://www.opensolaris.org/os/licensing.

See the License for the specific language governing permissions

and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each

file and include the License file at usr/src/OPENSOLARIS.LICENSE.

If applicable, add the following below this CDDL HEADER, with the

fields enclosed by brackets "[]" replaced with your own identifying

information: Portions Copyright [yyyy] [name of copyright owner]

CDDL HEADER END

Localization Notes for the Solaris Print Manager

3/16/99

1. Overview

The help documentation tree consists of a collection of Articles,

each relating to a specific dialog, message, procedure, or

other topic. The text, keywords, and metadata comprising the

entire set of Articles is delivered in a single (large)

ResourceBundle per locale.

Each article consists of several parts, all of which must be

defined within the ResourceBundle. These parts are called Tag,

Title, Content, Keywords, and See-Also. Title, Content, and

Keywords must be localized while Tag and See-Also must not.

The Tag is an identifier unique to each Article. The application

uses Tags to refer to specific Articles. The ResourceBundle uses

each Article's Tag to form the keys which identify the

strings comprising the Article.

The strings used as keys to identify the various parts of the

articles in the ResourceBundle are in the form of a dotted pair,

where the left side identifies the Tag of the Article to which

this string belongs and the right side describes which part of

that Article the string embodies.

The suffixes used to identify the Tag, Title, Content, Keywords,

and See-Also parts of a help article's resources are ".tag",

".title", ".content", ".keyword", and ".seealso" respectively.

Examples: The key "ToAddPrinter.title" is associated with a

localizable string that represents the title of the article whose

tag is "ToAddPrinter". The key "ToDeletePrinter.content" refers to

a localizable string which contains the content of the help article

itself.

2. Structure of Help Articles

2.1 Tags

Each Article is associated with a unique identifier called a Tag.

Tags are used internally and are never directly visible to users.

A Tag is a case-sensitive string of alphanumeric 7-bit ASCII

characters containing no embedded whitespace or punctuation.

For convenience, an article's Tag is usually formed by taking the

title and removing whitespace and punctuation; for example,

the article titled "Troubleshooting Printer Problems" might have

the Tag "TroubleShootingPrinterProblems". Note that this is a

mnemonic device only and in no way engenders a dependency between

the non-localizable Tag, which must be embedded in the

application's source code, and the article's title itself, which

must be localized.

*TAGS ARE NOT TO BE LOCALIZED!*

2.2 Title and Content

Each Article must contain a Title and some Content.

The Title is an arbitrary localizable string which will be

presented to the user upon viewing its associated Article.

The Content of an Article consists of a block of localizable text

which may contain a limited set of embedded HTML tags (subject to

restrictions described below).

Since the Content is displayed in a window whose size may be

adjusted by the user, its layout cannot be completely controlled by

the author. The Help display relies on word-wrapping and HTML

formatting to ensure correct appearance.

The viewable Content of an Article is authored in a tiny subset of

HTML which can be reliably rendered in the Help component. The

intention is to provide a simple facility for controlling the

appearance of the text and for handling paragraph and line breaks.

The supported capabilities are:

. Emphasize sections of text by bolding: <b> ... </b>

. Line breaks: <br>

. Paragraph breaks: <p>

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, by Sun Microsystems, Inc.

# 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 "<br> <h2> "

print -n `echo "$line" | sed s/'\.'/\ / | \

sed s/\"/\ /g | awk '{print \$2}'`

print " </h2>"

fi

echo "$line" | grep '^\".*+$' | sed s/^\"//g | sed s/\"\ +\$//

done

-----------------------

Usage of this script (assuming it is named 'extract') would be:

% extract < pmHelpResources.java > content.html

5. Support

For further assistance please contact:

Claude Noshpitz, clauden@eng.sun.com.