
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.


