# The Amaya Architecture

## Abstract

Amaya is a large piece of software. If you want to change it or extend it in some way, you may experiment some difficulty in finding out the right part to be modified in the code. The purpose of this note is to help you understand the Amaya architecture and find your way in the source code.

## Contents

1 Architecture

1.1 Document representations

1.2 Software components

2 Changing and extending Amaya

2.1 Changing menu bars and pull-down menus

2.2 Changing the button bar

2.3 Changing default document presentation

2.4 Creating new views

2.5 Adding new HTML tags and attributes

2.6 Modifying existing commands

2.7 Creating new editing commands

2.8 Adding new structure transformations

2.9 Configuring Amaya

## 1 Architecture

Amaya is an application based on Thot. Thot is a generic tool kit intended to build document based applications, with a structured approach to the document model. Basically, Thot provides a set of document manipulations functions with an API and allows applications to include additional functions through a callback mechanism. It also includes a simple declarative language to generate the user interface of an application.

### 1.1 Document representations

Different document representations are maintained or generated by Amaya:

Document structure and contents
  Each document is represented by a tree within Amaya. This tree represents the document structure. Its leaves contain the actual text. You can see a visual representation of that tree in the Structure view. This tree structure is constrained by some rules that are specified in a Thot structure schema (file `HTML.S` in directory `amaya`), written in the S language (see the language manual).

  Names of element types and attributes in file `HTML.S` are not those that the user actually sees on the screen. Correspondence between internal and external names is given by file `HTML.en` in directory `amaya`.

Document presentation and views
  The internal tree structure only represents the logical structure of HTML documents. The graphical aspect of these documents is specified by a Thot presentation schema (file `HTMLP.P` in directory `amaya`), written in the P language (see the language manual).

  The presentation schema specifies all possible views of HTML documents and the aspect of these documents in each view. It also specify how documents should be formatted for printing.

  Amaya uses a single source file (`HTMLP.P`) to specify different presentation schemas, using conditional compilation (see variables `PAGE`, `BLACK_WHITE`, `US_PAPER`).

HTML output
  While editing, Amaya works on the internal tree structure. HTML files are produced only when saving a document. Then, the tree structure is written in the output file according to a Thot translation schema (file `HTMLT.T` in directory `amaya`), written in the T language (see the language manual).

### 1.2 Software components

The main software components involved in Amaya are the following:

Graphical user interface
  The Amaya user interface contains three types of widgets:
  - A menu bar, at the top of each document window

    This bar and all its menus, including cascading menus, are specified in a Thot application schema (file `EDITOR.A` in directory `amaya`) written in the A language (see the A language manual).

  - A button bar below the menu bar, in the formatted view.

    This button bar is created by Amaya at initialization time (see function `InitDocView` in module `amaya/init.c`).

  - Various dialogue boxes

    Some of these dialogue boxes are standard Thot dialogue boxes, other are created by the Amaya application. Both Thot and Amaya use the Thot dialogue module.

Standard Thot editing functions
  A number of basic editing functions are simply standard Thot functions. The name of these functions start with `Ttc`.
Specific editing functions
  In addition to the standard functions, Amaya has its own editing functions.
  - Some functions are called from the menu bar (see file `EDITOR.A` in directory `amaya`) and are implemented in the C modules of directory `amaya`.
  - Some functions are called from the button bar (see function `InitDocView` in module `amaya/init.c`) and are also implemented in the C modules of directory `amaya`.
  - Some functions are called from standard Thot editing commands. They are defined in file `HTML.A` (directory `amaya`) and implemented in the C modules of directory `amaya`. They implement some specific treatments that are required for tables, pictures, forms, style sheets, etc.
HTML Parsing
  HTML files are parsed by module `html2thot.c` (directory `amaya`), which builds the internal tree structure.
CSS parsing
  Style sheets and CSS syntax in general are parsed by module `HTMLstyle.c.`
Structure transformation
  Structure transformation commands are handled by two modules: `trans.c` and `transparse.c`. These modules are driven by the `HTML.trans` file (directory `amaya`), which specifies the possible transformations.

## 2 Changing and extending Amaya

A number of modifications to Amaya can be made without modifying the C code. As explained above, the behavior of Amaya is defined by a number of schemas and other files that can be modified easily, as they are written in very simple declarative languages. Prior to making any change to the source code, it's worth considering modifications to these files.

### 2.1 Changing menu bars and pull-down menus

You may want to change the user interface. The simplest change you can make is modifying the menu bars and the pull-down menus.

There is a menu bar on top of each window handled by Amaya. Notice that the contents of these menu bars vary according to the view displayed in the window.

All menu bars and the corresponding pull-down menus are defined in file `EDITOR.A` (directory `amaya`). Update that file for defining your own menu bars (it is written in the A language, which is documented in The Thot Application Generation Language). Then, you just have to `make amaya`.

If you want the new (or existing) menus and their items to be available in different languages, don't forget to update the `xx-amayadialogue` file (in directory `config`), where `xx` is the language name (for instance, `en` for English or `fr` for French).

### 2.2 Changing the button bar

You can change the button bar of the formatted view in many ways. You can

- remove buttons (most of them are equivalent to some menu item),
- change their order,
- change their icon,
- add new buttons.

For all these changes, you have to edit the function `InitDocView` in module `amaya/init.c` and to `make amaya`.

### 2.3 Changing default document presentation

Document style can be changed in many ways. In a document, stylistic information can be associated with a given element, with all elements of a given type, with all elements having the same `class` attribute, etc. You can do that with the Style menu (refer to the user's manual), but you may want to change the default presentation of all documents displayed by Amaya. There are two ways to do that:

Using a personal style sheet
  Create a file `.amaya.css` in your home directory or edit it if it exists. This file is written in the CSS1 language.

  When the file is updated you don't need to do anything else. The next document you load or reload will be displayed with the new style sheet.

  These changes only apply to the Formatted view of the documents you display.

Changing the presentation schema used by Amaya
  Edit the `HTMLP.P` presentation schema in directory `amaya`. This file is written in the P language (see the Thot language manual). By editing this file, you may modify the appearance of all documents in any view.

  When the file is updated, you need to compile it with the prs compiler, but typing `make amaya` in the `amaya` directory does the job.

  Changes made that way apply to all documents displayed or edited by all users sharing the same installation of Amaya, but style sheets supersede the presentation schema.

  The presentation schema specifies document presentation on the screen as well as on the paper. To change the layout of printed documents, including page headers and footers, with numbers, running headings, etc., focus on the parts that follow conditions `#ifdef PAGE` in the schema.

### 2.4 Creating new views

You may create new views by editing and compiling file `HTMLP.P` (see above), but this is not enough. You must also edit file `EDITOR.A` to add a new item to the Views menu (see above). This item is associated with a C function that you must create in file `init.c`. You can use functions `ShowStructure` and `ShowAlternate` as examples.

You may specify the default position and size of the view in file `HTML.conf`.

Just `make amaya` when all these changes have been made.

### 2.5 Adding new HTML tags and attribute

To experiment an HTML extension, you must update several files:

HTML.S
  Declare the new element type or attribute in the structure schema `HTML.S`. If you want the external name of the new element or attribute to be different in different languages, update the files `HTML.xx`, where `xx` is the name of the language.
HTMLP.P
  Specify the default presentation of the new element or attribute in the presentation schema `HTMLP.P`. Don't forget to specify the presentation in all views. For the Structure view, some new presentation boxes will probably be needed.
HTMLT.T
  Specify the corresponding HTML syntax in the translation schema `HTMLT.T`.
EDITOR.A
  If it's a new element, add an item to the Types menu or to one of its submenus, to allow the user to create these elements. The new menu item will call a function that you must also write. This function is very simple in most cases (refer to functions corresponding to existing menu items in module `EDITORactions.c`).

  If it's an attribute, the Attributes menu will be updated automatically.

html2thot.c
  To allow Amaya to parse the new tag or attribute, you must update the HTML parser. HTML elements and attributes are declared in tables at the beginning of module `html2thot.c`, as well as the corresponding element or attribute defined in the structure schema `HTML.S`. In most cases, updating these tables is enough.

If the new element or attribute needs some extension to standard editing commands or some new editing commands, see the next two sections.

### 2.6 Modifying existing commands

You can modify Thot standard commands or Amaya specific commands.

File `HTML.A` specifies all extensions and replacements for Thot standard editing commands. You can modify the functions implementing these extensions and replacements. You can also specify additional such functions, by editing file `HTML.A` and writing the code implementing the new functions.

Amaya specific editing functions are those referred to in file `EDITOR.A`. They are implemented in the C modules of directory `amaya`. You can obviously change these implementations.

### 2.7 Creating new editing commands

To create new commands, you have to define their user interface (add a new menu to a menu bar, a new item to an existing menu and/or a new button to the button bar) and to write the code of the corresponding function.

### 2.8 Adding new structure transformations

The last item of the Types menu allows you to transform the structure of the selected elements. When activating that item, you get another menu that presents the choice of the possible transformations.

To offer new transformations, you have to specify them in the `HTML.trans` file (directory `amaya`). You don't need to do anything else (no compilation, no make). The menu of the possible transformations will be updated automatically, according to the current selection and the new contents of the `HTML.trans` file.

### 2.9 Configuring Amaya

Users can configure Amaya in various ways, just by editing some configuration files. This is described in the document Configuring Amaya.