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.
2 Changing and extending Amaya
2.1 Changing menu bars and pull-down menus
2.3 Changing default document presentation
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
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.
Different document representations are maintained or generated by Amaya:
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.
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).
HTMLT.T in directory amaya),
written in the T language (see the language
manual).The main software components involved in Amaya are the following:
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).
This button bar is created by Amaya at initialization time (see
function InitDocView in module
amaya/init.c).
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.
Ttc.EDITOR.A in directory amaya) and are
implemented in the C modules of directory amaya.InitDocView in module
amaya/init.c) and are also implemented in the C modules
of directory amaya.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.html2thot.c (directory
amaya), which builds the internal tree structure.
XHTML files are parsed by modules Xml2thot.c and
XHTMLbuilder.c (directory amaya), which builds
the internal tree structure.
HTMLstyle.c.trans.c and transparse.c. These modules are
driven by the HTML.trans file (directory
amaya), which specifies the possible transformations.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.
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).
You can change the button bar of the formatted view in many ways. You can:
For all these changes, you have to edit the function
InitDocView in module amaya/init.c and to make
amaya.
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:
.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.
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.
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.
To experiment an HTML extension, you must update several files:
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. Don't forget to specify the
presentation in all views. For the Structure view, some new presentation
boxes will probably be needed.HTMLT.T.EDITORactions.c).
If it's an attribute, the Attributes menu will be updated automatically.
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.
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.
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.
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.
Users can configure Amaya in various ways, just by editing some configuration files. This is described in the document Configuring Amaya.
V. Quint
$Date: 2009/03/03 14:58:20 $