# Configuring Amaya

Amaya uses different configuration files to get initial values for global parameters, dialogs, shortcuts, window size and position, user's style sheet, etc. You can change most of the configuration parameters by means of specific preferences menus. This document gives a walk-thru of the different preference menu, then gives more specific information on how to configure the keyboard shortcuts.

## Conventions

### The Amaya/Config directory

This is the directory where most of the default values and all the dialogue messages are stored. The directory's parent is the one where you installed Amaya.

### The AmayaHome directory

Amaya stores the user preferences as well as other user configuration files in a directory which we call the AmayaHome directory. The following table shows where this directory is stored under different architectures:

architecture | AmayaHome directory
Unix | $HOME/.amaya
Windows 95 | AMAYA-INSTALL-DIR\users\username or, if the user didn't login to Windows, AMAYA-INSTALL-DIR\users\default
Windows NT | c:\winnt\profiles\username\amaya

The AmayaHome directory is preserved even while installing new versions of Amaya and may contain the following files:s

- thot.rc : the user preferences, changed thru the preferences menu.
- amaya.keyboard (Unix) or amaya.kb (Windows) : this file defines Amaya keyboard shortcuts.
- amaya.css : contains the user's style sheet.
- dictionary.DCT : Amaya provides a multilingual spell checker. By default the spell checker works with two dictionaries: the English dictionary and the French dictionary (these two dictionaries can be downloaded from W3C servers ). When the user wants to register a new word, the spell checker creates or updates the "user's personal dictionary".

Note: the amaya.keyboard/amaya.kb and amaya.css files are loaded at launch time. If you change them, you'll need to quit and restart Amaya to take them into account.

### The AmayaTemp directory

Amaya stores all the temporary files it creates during its execution in a directory which we call the AmayaTemp directory. The following table shows where this directory is stored under different architectures:

architecture | AmayaTemp directory
Unix | $HOME/.amaya
Windows | c:\temp\amaya (default value)

Amaya creates files in this directory while browsing remote documents or printing a document. The cache is stored in this directory. The user may change both the AmayaTemp and cache directories by means of the General Preferences and Cache menus.

Amaya always tries to delete all the temporary files it creates. However, if Amaya crashes, the temporary files won't be deleted. This won't impact subsequent executions of Amaya.

## The Preferences menus

These menus are found under the Special/Preference menu. There are five different preference menus available: general, publishing, cache, proxy, colors, and geometry. In all of these menus, we find three common action buttons:

Apply
  This button will validate and store the options shown in the menu.
Defaults
  This button will restore, but not save, the default values. You need to use the Apply button to validate the options.
Done
  This button dismisses the menu.

### General preferences

Home Page
  Specifies the page that Amaya will load when launched or when he presses the home page button..

Amaya user home (Windows platforms only, not shown in the figure)

  Specifies the directory where the user preferences are stored. The user can't change the location of this directory.
Amaya temporary directory (Windows platforms only, not shown in the figure)
  Specifies the directory where Amaya will store its temporary files, for example, while printing a document. If not specified, the defaul temporary directory will be c:\temp

  amaya. Note that changing this directory won't erase the precedent one. You'll have to do it yourself. If the cache is located under the previous temporary directory, a new cache will be created under the new directory.

Double click delay (Unix platforms only)
  This option allows one to control the delay under which two mouse clicks are classed as a double-click. This option is only taken into account at launch time.
Menu Font size (Unix platforms only)
  Specifies the font size of all the Amaya menus. This option is only taken into account at launch time.
Zoom
  It's possible to zoom in and zoom out, document window by document window. Each document displayed within a zoomed window will be displayed larger or smaller than its real size according of the current zoom.

  Amaya has a default zoom value equal to 0 (documents are displayed by default as they are). This option allows you to change the default zoom value. The change is reflected immediately upon all the open document windows.

Dialogue language
  Specifies the language for all of Amaya's menus and dialogue messages. The default language is English (value `en_US`). At the moment, only three languages are available: English (`en`), French (`fr`), and Germand (de). When launched, Amaya loads dialogue files according to the current dialogue language: en-, fr-, or de- files. These dialogue files are located in the Amaya/config directory.

  In Thot, a document is specified according to a schema. In Amaya, the dialogue message that are displayed when parsing a document or when saving it under a specific schema are given in the Amaya/amaya/HTML.code file, where the code suffix is a language abbreviation (e.g., `en` or `fr`). This file has 4 sections:

  - extension: not used by Amaya
  - presentation: not used by Amaya
  - export: give the text displayed for each translation schema ("Save As" command)
  - translation: give the text displayed for each element and attribute in the Thot HTML structure.

  It's possible to adapt Amaya to new ISO-Latin-1 languages by writing corresponding dialogue files. These dialogue files have to be located in the same directory`` Amaya/config`,``` and must use the right ISO 639 code as a prefix (it- for Italian, de- for German, etc.). The specific HTML.code file also has to be created.

Enable multi-key
  The optional input method (Multi-Key) is based on a two key sequence beginning with the "accent" followed by the "letter". For example to obtain a 'ã' first press '~' then type 'a'. To obtain a '~' you have to press '~' twice. The table below gives available key sequences:

  accent-letter | ~ | ` | ' | " | * | ^
  a A | ã Ã | à À | á Á | ä Ä | å Å | â Â
  c C |  | ç Ç |  |  |  |
  e E |  | è È | é É | ë Ë |  | ê Ê
  i I |  | ì Ì | í Í | ï Ï |  | î Î
  n N | ñ Ñ |  |  |  |  |
  o O | õ Õ | ò Ò | ó Ó | ö Ö | ø Ø | ô Ô
  u U |  | ù Ù | ú Ú | ü Ü |  | û Û
  y Y |  | Ý | ý Ý | ÿ |  |

Show background images
  Controls whether bacground images should be shown. This option is only effective when loading a new document.
Double click activates link
  Since the first version of Amaya, users need to double click on a link to activate it. This allows to differentiate between the edition of a link or its activation. You can override this behavior by disactivating this option.

### Publishing preferences

Use ETAGS and preconditions
  HTTP/1.1 introduces new headers that allow to avoid the lost updates problem when publishing. With this mechanism, you can detect conflicts when two users are publishing the same document.
Verify each PUT with a GET
  If you don't trust your server, this option tells Amaya to retrieve each document as soon as it has been published and compare it with the copy stored in your workstation. If the documents differ, Amaya will warn you.
Default name for URLs finishing in '/'
  An HTTP server usually associate the URLs that finish in '/' with a default name, e.g., Overview.html. This option allows you to specify the default name that Amaya should use when publishing such a URL. Please consult your Webmaster to find out what's the default name that applies to your server.

### Cache preferences

Amaya provides a cache thru libwww. By default, the cache is enabled by default and is stored in the AamayaTemp/libwww-cache directory. This menu also provides a Flush Cache button, for erasing the cache directory.

Enable cache
  Activates or desactivates the cache
Cache protected documents
  By default, documents which are protected by a password are stored in the cache. You can use this flag to override this behavior.
Disconnected mode
  Always retrieves documents from the cache.
Ignore Expires: header
  Doesn't expire cache entries.
Cache directory
  Gives the parent directory for the libwww-cache directory. Note that changing this directory won't erase the contents of the precedent one. You'll have to do it yourself.
Cache size
  Gives the size, in megabytes, of the cache repository.
Cache entry size limit
  Gives the maximum size for a cache entry.

### Proxy preferences

You can specify a proxy and a set of domains which should be access without a proxy by means of this menu.

HTTP proxy
  Gives the proxy that should be used for HTTP requests. The syntax is similar to that of a URL (note that there's no end '/'):

      HTTP_PROXY=http://groucho.marx.edu:1028
                                              proxy FQDN --^      ^---- optional proxy port

No proxy on these domains
  Gives a list of space separated domains which you want to access directly, without a proxy:

      NO_PROXY=harpo.marx.edu zeppo.marx.edu chico.marx.edu
                                                    FQDN --^           ^--- space separated entries

### Color preferences

This menu allows you to change the foreground and background colors for the document and the menus. These changes will be effective when you open a new window. Note that only the Unix version provides entries for changing the menu colors. To do so under Windows, you'll need to use the standard Windows configuration control, found in the Control Panel directory.

The color changes will be effective when you open a new document window or when reloading a document.

Under Windows, you can change the colors by means of a color palette. The Unix interface is a bit clumsy for the moment and you have to type in the color name. If you type an invalid color name, the default colors will be used instead.

### Geometry preferences

This menu allows you to save the current geometry values of the different views of a document (Formatted, structure, alternate, links, and Table of Contents.) or to restore the default values. Note that the values that are saved are those belonging to the views of the document where you called this menu. These changes will be reflected when you open new document windows.

### Language negotation preferences

If a document exists in different languages and your server is configured to do language negotiation, you can use this menu to enter your language preferences (first one has the highest priority). Try browsing this press release, which exists in French, English, and Japanese versions. By changing the language negotiation to the ISO codes for the above languages ( fr, en, or jp), you can transparently request any of these versions.

## Keyboard Shortcuts

It is useful to be able to invoke menu commands directly from the keyboard. The Thot toolkit provides a facility that let user accomplish this by means of an application keyboard shortcuts file. This file defines a list of associations between a keyboard sequence an the invoked corresponding command.

The syntax used to define an association is:

     Directive = KeySeq ':' IdentCommand ;
     KeysSeq = KeySet [ ',' KeySet ] ;
     KeySet = [ Modifier ] [ 'Shift' ] Key ;
     Key = '<Key>' KeyValue / '<Key>' SpecialKey ;
     Modifier = 'Ctrl' / 'Alt' / 'Meta' ;
     KeyValue = 'a' / 'b' / ... ;
     SpecialKey = 'Escape' / 'Delete' / 'Space' / 'BackSpace' /
                  'Return' / 'Up' / 'Down' / 'Left' / 'Right' /
                  'Home' / 'End' / 'F1' / ... / 'L1' / ... / 'R1' / ... ;
     IdentCommand = 'TtcInsertChar(' Char ')' / NAME '()' ;
     Char = KeyValue / OctalValue ;  OctalValue = '\' NUMBER ;

For an example, see the standard amaya.keyboard file, which is located in the config directory.

The list of available commands is:

- Moving commands:
  - TtcNextChar, TtcPreviousChar: move chararcter by character.
  - TtcNextLine, TtcPreviousLine, TtcStartOfLine, TtcEndOfLine: move line by line.
  - TtcNextElement, TtcPreviousElement, TtcChildElement, TtcParentElement: move element by element.
  - TtcPageDown, TtcPageUp, TtcPageTop, TtcPageEnd: move page to page.
- In `File` menu:

  New, OpenDoc, OpenDocInNewWindow, Reload, GotoPreviousHTML, GotoNextHTML, SaveDocument, SaveDocumentAs, SetupAndPrint, PrintAs TtcCloseDocument, AmayaClose

- In Edit menu:

  TtcUndo, TtcRedo, TtcCutSelection, TtcCopySelection, TtcPaste, TtcDeleteSelection, SetBrowserEditor, TtcSearchText, EnSpellCheck, FrSpellCheck, TransformType.

- In `Structure Types` menu:

  CreateBase, CreateMeta, CreateLinkInHead, CreateScript, CreateStyle, CreateComment.

- In Types menu:

  CreateParagraph, CreateImage, CreateHeading1, CreateHeading2, CreateHeading3, CreateHeading4, CreateHeading5, CreateHeading6, CreateList, CreateNumberedList, ThotCreateMenu, ThotCreateDirectory, CreateDefinitionList, CreateDefinitionTerm, CreateDefinitionDef, CreateHorizontalRule, CreateBlockQuote, CreatePreformatted, CreateAddress, CreateToggle, CreateRadio, CreateOption, CreateTextInput, CreateTextArea, CreateSubmit, CreateReset, CreateAreaRect, CreateAreaCircle, CreateAreaPoly, CreateDivision, CreateNOSCRIPT, CreateObject, CreateParameter, CreateIFrame, CreateInlineMath, CreateMath, CreateMROOT, CreateMSQRT, CreateMFRAC, CreateMSUBSUP, CreateMSUB, CreateMSUP, CreateMUNDEROVER, CreateMUNDER, CreateMOVER, CreateMROW, CreateMMULTISCRIPTS, CreateMTABLE., CreateTable, CreateCaption, CreateTHead, CreateTBody, CreateTFoot, CreateRow, CreateDataCell, CreateHeadingCell, DeleteColumn.

- In `Links` menu:

  CreateOrChangeLink, CreateTarget, DeleteAnchor.

- In `Views` menu:

  TtcSwitchButtonBar, TtcSwitchCommands, ShowMapAreas, ShowTargets, ZoomIn, ZoomOut, ShowStructure, ShowAlternate, ShowLinks, ShowToC.

- In `Style` menu:

  TtcChangeCharacters, TtcChangeColors, TtcChangeFormat, ChangeBackgroundImage, CreateClass, ApplyClass, LinkCSS, OpenCSS, DisableCSS, EnableCSS, RemoveCSS, CreateElemEmphasis, CreateElemStrong, CreateElemCite, CreateElemDefinition, CreateElemCode, CreateElemVariable, CreateElemSample, CreateElemKeyboard, CreateElemAbbr, CreateElemAcronym, CreateElemINS, CreateElemDEL, CreateElemItalic, CreateElemBold, CreateElemTeletype, CreateElemBig, CreateElemSmall, CreateSub, CreateSup, CreateQuotation, CreateBDO.

- In `Special` menu:

  SectionNumbering, MakeBook, CleanCache.

- In `Help` menu:

  HelpAmaya, HelpAtW3C, HelpBrowsing, HelpSelecting, HelpSearching, HelpViews, HelpCreating, HelpLinks, HelpChanging, HelpTables, HelpMath, HelpImageMaps, HelpStyleSheets, HelpAttributes, HelpPublishing, HelpPrinting, HelpNumbering, HelpMakeBook, HelpConfigure.