SDA 3.5 Documentation for INTERFACE

NAME

interface - Modifying the SDA user interface

DESCRIPTION

The user interface for SDA procedures can be changed to practically any language, by modifying some or all of the default English character strings with alternate wording.

The strings to be modified are contained in a number of different files, corresponding to the displays generated by the main SDA interface for selecting options and by the various analysis and codebook programs. This document describes how to find and modify the relevant files.

This document includes the following topics:

Special Language Files
Putting non-English text in DDL and HARC files
- Non-English text in a DDL file
- Non-English text in a HARC file
Specifying the character encoding and font

SPECIAL LANGUAGE FILES

This section describes how to generate a copy of the files with language strings, how to modify them, and where to put the modified files.

GENERATING THE FILES WITH LANGUAGE STRINGS

There are three separate language files that can be modified.

Option Screens
The option screens are those used to specify variables to analyze and options to use. The language strings for the option screens can be obtained by using the ‘-t’ option with the HSDA program:

hsda -t filename1
The HSDA program is located in the /cgi-bin directory.
Analysis Output Analysis output is produced by the various analysis programs (like the TABLES program or the MEANS program) to display the results of the analysis. A copy of those language strings can be obtained by using the ‘-t’ option with the TABLES program:

tables -t filename2
The TABLES program is located in the directory in which the SDA programs have been installed.
Codebook Output The output produced by the XCODEBK program has its own set of language strings. A copy of those strings can be obtained by using the ‘-t’ option with the XCODEBK program:

xcodebk -t filename3
The XCODEBK program is located in the directory in which the SDA programs have been installed.

Once you have a copy of the language files, you can proceed to modify them.

MODIFYING THE LANGUAGE FILES

All of the language files have the same format. There is a keyword, then an equal sign, then the string used by the SDA programs.

Here are a few such strings used for the output from analysis programs:

Here are those same strings converted to Portuguese:

ROWVAR = Var. de linha
COLVAR = Var. de coluna
WGT = Peso
FLT = Var. de Seleção

The first three strings are simple to enter. The fourth one, however, includes characters that are not included in the set of simple ’US-ASCII’ characters. Notice that the Portuguese words in the ‘FLT’ string include a ‘c’ with the cedilla and an ‘a’ with a tilde over it. If you can enter those characters directly into the language file, using your editor or word processing program, that will work fine. If you cannot enter those characters directly, it is possible to use special codes for HTML display.

Special codes for non-ASCII characters

If your keyboard or text editor makes it difficult to enter the characters you want, you can enter special codes for each non- ASCII character. For example, if you wanted the text describing a filter variable to be ’Var. del Seleção’, you could enter that text directly as:

FLT = Var. de Seleção

But if you had difficulty entering all those characters, you could enter the following text with special codes:

The special codes all have the following format:

An ampersand (&)
The special code (here they are ‘ccedil’ and ‘atilde’)
Instead of a short name for each character, it is also possible to give the numeric code. For example, the numeric equivalent for the ‘atilde’ character is ’#227’.
A semicolon (;)

See the referenced Table of Character Entities for a list of the available codes.

Potential problems with the special codes

The special codes will work fine for displaying HTML with a browser. If, however, you want to create a codebook in Microsoft Word format so that you can print it out, you should enter the non-ASCII characters directly from the keyboard or by copying them from another file. Do not use the special codes (with ’&’) in the language file for XCODEBK or in the DDL file. Otherwise, the special codes themselves will print out -- not the characters they are supposed to represent.

WHERE TO PUT THE MODIFIED LANGUAGE FILES

The location of the language files depends on the program for which it is designed.

The language files used by SDA analysis programs (generated by the ‘tables -t’ or the ‘hsda -t’ command) must be put into a specific place, and they must be given specific names.

Directory in which to put the files.
These files are placed in a publicly accessible directory, and the pathname of the directory is given after the ‘LANGUAGE=’ keyword in the GENERAL section of the HARC file. Then all of the datasets referenced in the HARC file will use the language files in that directory.
Name of the files.
The language files in the LANGUAGE directory must have specific names:
- ‘langform’ - the messages used to contruct the option screens
  (the file obtained from ‘hsda -t’ and then modified)
- ‘langan’ - the strings used to construct output from analysis programs
  (the file obtained from ‘tables -t’ and then modified)

The language file used by the XCODEBK program (generated by the ‘xcodebk -t’ command and then modified) can be located anywhere and can be named anything you want.

The location and name of the file is communicated to the XCODEBK program via the ‘LANGfile=filename’ keyword in the XCODEBK command file.
The full pathname of the language file should be given, if it is not located in the same directory as the one in which the codebook program is run.

PUTTING NON-ENGLISH TEXT IN DDL AND HARC FILES

The DDL file and the HARC file already exist for an SDA dataset. Changing the interface to another language requires that certain textual information in those files be put into the desired language instead of English.

NON-ENGLISH TEXT IN A DDL FILE

The variable label, the category labels, and the question text of each variable in a dataset are given in the DDL file. If those fields of the DDL file are written in a language other than English, they will be displayed in that language by the SDA programs.

You can enter non-English text directly into the DDL file as described above for modifying the language files.

If you cannot enter non-ASCII characters directly, you can use the special codes as described above. However, be aware of the potential problems involved with using those special codes, if you want to generate codebooks in Microsoft Word format.

Note that if a DDL file is written with the ’UTF-8’ encoding, it may contain a "byte order mark" (BOM) at the beginning of the file. That BOM is ignored by the MAKESDA program.

NON-ENGLISH TEXT IN A HARC FILE

The HARC file contains (optionally) a number of labels for programs, procedures, and charts. Non-English labels can be provided by putting the desired labels into the HARC file.

You can enter non-English text directly into the HARC file as described above for modifying the language files. If you cannot enter non-ASCII characters directly, you can use the special codes as described above. Since the text in the HARC file is only used to display HTML content by a browser, the use of special codes in the HARC file will not cause any problems for creating or for printing out Word codebooks.

Labels for Programs and Procedures

The main SDA interface allows the user to select which program or procedure is to be executed (tables, means, regress, etc.). Each of those programs and procedures has a default description or label. For example, the default label for the TABLES program is "Frequencies or Crosstabulation." These labels can be changed into some other language (or even into other English labels) by putting the desired label for each program in the HARC file, as described in the relevant section of the HARC document.

Labels and Ordering of Charts

The TABLES and MEANS programs provide the user with a list of charts from which to select the desired chart for each run. Each type of chart has a default description or label. For example, the default label for the TABLES ’stackedbar’ chart is "Stacked Bar Chart." These labels can be changed into some other language (or even into other English labels) by putting the desired label for each chart in the HARC file, as described in the relevant section of the HARC document.

Note that the ordering of the chart options presented to the user on the drop-down list can be modified by simply changing the order of the labels in this section of the HARC file.

Headers and Footers (for the CLASSIC interface)

Text for the headers and footers to display on the option screens, and labels for the programs to select and for other actions to take are entered into the appropriate section of the HARC file

SPECIFYING THE CHARACTER ENCODING AND FONT

The default encoding of characters used by SDA is ’US-ASCII’. However, some documentation files that are converted into DDL files or codebooks may require another encoding to display properly. The character encoding can be specified using the ’CHARSET=’ keyword in the general section of a DDL file.

If the language requires a special font for display, you may have to specify that font using the ’CHARTFONT=’ keyword in the basic dataset section of the HARC file. Otherwise, the charts produced by the TABLES and MEANS programs may not display text correctly. If you run the TABLES or MEANS program in batch mode, there is a corresponding ’CH_FONT=’ keyword that can be specified in the chart options section of the TABLES batch file or the MEANS batch file. See the further discussion in the language document.

DDL	Data Description Language
language	Using non-English languages in SDA