Amaya Frequently Asked Questions
I. Global issues
- Is Amaya an editor or a browser?
- Where can I get Amaya?
- Is Amaya available for MacOS ?
- Can I release Amaya on a CD-ROM?
- Can I make some changes and re-release it?
- Why is Amaya written in C?
- Can I change the dialogue language?
- What does the word "Amaya" mean?
II. Using Amaya
- Amaya doesn't start. What can I do?
- Amaya is very very slow
- Is Amaya compliant with MathML?
- Can I edit tags directly?
- Fonts are too small. What can I do?
- How to change fonts?
- Can I get fonts for Amaya?
- How can I change the default window size?
- Can I see parsing errors detected by Amaya?
- What is the reason for a very liberal structure enforcement?
- How can I update the document title?
- How to get out of a preformatted, a table, or a division?
- Why doesn't Amaya support frames?
- Does Amaya support JavaScript and animated images?
- Amaya stops reading XHTML, MathML, or SVG documents!
- Does Amaya support non-Latin characters?
- Can I use CSS style sheets?
- How can I publish my documents remotely?
- How to control the format of generated dates?
- How to move a division?
- How to move a column or a row of a table?
- How to display two documents side by side?
- Installing Amaya on OpenSuse 12.1
III. Compiling Amaya
- Where can I get the developers documentation?
- Make complains with missing files
- Make fails when compiling the HTML schema
- What do I need to compile?
- I've a problem with ltconfig (or libtool)
- Make complains "test: argument expected"
I.1. Is Amaya an editor or a browser?
Amaya is mainly an authoring tool with browsing features. Link management and remote publishing are key features in a hypertext editor, and these features require seamless integration of editing and browsing features.
I.2. Where can I get Amaya?
You can download the Amaya distribution in various formats, and you can use either ftp or http:
The page at http://www.w3.org/Amaya/User/BinDist.html gives access to a ready to use application for various platforms.
The page at http://www.w3.org/Amaya/User/SourceDist.html gives access to the source code.
I.3. Is Amaya available for MacOS?
Yes dmg packages are now available
- amaya-macosx-x.x.dmg for PowerPC - PowerBook
- amaya-macintel-x.x.dmg for Intel - MacBook
See the distribution page at http://www.w3.org/Amaya/User/BinDist.html
I.4. Can I release Amaya on a CD-ROM?
Yes, and you can even charge for it, provided the copyright is preserved.
I.5. Can I make some changes and re-release it?
Yes, we encourage people to experiment with Amaya and to improve it. It can even be used in commercial software. If you make changes for the better, we encourage you to contact us. You may not make changes and continue to call it by a trademarked term or misrepresent the origin, capabilities, or liabilities associated with its use. You may make valid assertions, such that it is based on the Amaya code, or that it is compliant with a Recommended Specification of the W3C.
I.6. Why is Amaya written in C?
C has a number of advantages that fit well with our purposes. It's a very portable and efficient language. Amaya is also based on a pre-existing editing library, the Thotlib, which was itself written in C. It was natural to continue to develop the Amaya code in C.
A large part of the User Interface is now written in C++.
I.7. Can I change the dialogue language?
By default Amaya works with an English dialogue and comes with an English in-line documentation. Other dialogues (French, German, Spanish, Portuguese, Italian, Finnish, Russian) and other version of the in-line documentation (French, German, Spanish, Russian) are also available provided the user downloads the extra amayadoc file as explained in http://www.w3.org/Amaya/User/BinDist.html
The entry Dialogue language in the dialogue Edit/Preferences/General specifies the language for all of Amaya's menus and dialogue messages. The default language is American English (value en).
At the present time only seven alternate languages are available: English (en), French (fr), German (de), Italian (it), Spanish (es), Portuguese (pt), and Finnish (fi). When launched, Amaya loads dialogue files according to the current dialogue language: en-, fr-, or de-, it-, es-, pt-, or fi- files, respectively. These dialogue files are located in the Amaya/config directory.
I.8. What does the word "Amaya" mean?
The initial name of our editor/browser was Tamaya. A tamaya is a tree that is represented on the logo. We chose that name because we had such a tree in our office and we though that, with some imagination, it could style both the image of the Net and the structure of a Web page. Unfortunately we were not allowed to continue to use the name Tamaya, as it was trade marked and used by a French company. So we decided to drop the first letter (T) and our editor/browser is now named Amaya.
II.1. Amaya doesn't start. What can I do?
The most common reason is that Amaya is not able to generate its temporary working directory.
The following table shows the default position of this directory in different architectures:
Architecture |
AmayaHome Directory Location |
Unix and Mac OSX |
|
Windows 95/ Windows 98 |
|
Windows NT/XP |
|
If this position is not available, you have to force another position with the AMAYA_USER_HOME global variable.
This variable must point to an existing and allowed path directory under which Amaya will generate its working files and sub-directories.
On Windows platforms, you should set that variable from the System Properties (either accessible from the "System" Control Panel or through My Computer -> Properties context menu) "Advanced" page - Environment Variables. This way the setting will be in effect for every process.
set AMAYA_USER_HOME=C:\Documents and Settings\XX\Amaya
Do not leave spaces around the variable name and the value, and don't use quotes.
On Unix platforms
- It could be a problem during the installation procedure:
If the package is not installed with SU rights, the symbolic link
/usr/bin/amaya
is not created and the application cannot be launched.The solution is to install the package with the command
sudo dpkg -i package_name
- It could be a problem with a missing library:
Check missing libraries with
ldd /usr/share/Amaya/wx/bin/amaya_bin
orldd /usr/lib/Amaya/wx/bin/amaya_bin
- If all dynamic libraries needed by the executable file amaya are there,
you can launch amaya with strace to see what is wrong
strace /usr/share/Amaya/wx/bin/amaya_bin
On debian or Ubuntu platforms use
strace /usr/lib/Amaya/wx/bin/amaya_bin
II.2. Amaya is very very slow
AmayaWX uses OpenGL for page rendering. This allows a better support of SVG and animations. The drawback is that Amaya is very dependent on video card's drivers, if a driver is buggy, Amaya will probably crash...
On Unix platforms, Amaya comes with the Mesa library to implement OpenGL primitives. Mesa is a software OpenGL implemetation so Amaya isn't dependent on video card drivers on Unix. If Amaya doesn't start or is very slow on Unix platforms it's something else.
On Windows platforms, Amaya uses hardware OpenGL implementation so Amaya is very dependent on video card's drivers. When the application doesn't start or is very very slow, we suggest that users check:
- Update of their video card driver, if there is an available. This update can be found either on the MicroSoft site (see the driver section) or on the site of the Video card provider.
- Our Windows version includes a patch that fixes the problem (in file
wxWidgets/src/msw/glcanvas.cpp
)
II.3. Is Amaya compliant with MathML?
Yes, but the current implementation of MathML 2.0 in Amaya is not complete yet. It does not implement the Content part of MathML 2.0. The documentation clearly indicates what is available. See section "Known Issues With MathML".
II.4. Can I edit tags directly?
Amaya has been built as a structured document editor. This approach allows it to handle complex documents and highly structured objects such as tables, structured graphics or mathematical expressions. While editing in the HTML or the XHML mode, Amaya works on the document tree, not on its textual representation, which is generated only at save time, in the syntax you choose (plain text, HTML, XHML).
Amaya also allows you to open the source view of the document (entry Views/Show source) and then to edit tags. This is done in a separate but synchronized document. Amaya shows what part of the source document is concerned by the current selection in the formatted document and conversely. Both the source document and the formatted document can be edited. Changes done in any of these two documents are reflected in the other by the File/Synchronize command. Synchronization is also performed automatically when the wiew selection changes.
II.5. Fonts are too small. What can I do?
With Amaya you can zoom in and zoom out, document window by document window. So each document displayed in a zoomed window will be displayed larger or smaller than its normal size according of the current zoom factor. That zoom factor acts on all the displayed information (fonts, images, etc.). Commands that chage the zoom factor are located in the menu Views.
The Edit/Preferences/General menu allows you to change the font zoom factor permanently. By default that zoom factor is 100% (documents are displayed with their own size). That zoom factor affects only font sizes but not other elements (images, etc.).
II.6. How to change fonts?
In order to let you choose your fonts, Amaya works with a Font Configuration
file. By default that Font configuration file is located in the directory
Amaya/config/
:
- The file
"fonts.gl"
is used by Mac OSX and Linux versions of Amaya - The file
"fonts.gl.win"
is used by Windows versions of Amaya
For more information about these configutation files, see http://www.w3.org/Amaya/User/FontConfig.html
II.7. Can I get fonts for Amaya?
Amaya WX versions
Amaya WX works only with TrueType fonts. Amaya distributions comes with Esstix fonts (a large set of mathematical symbols) and a set of free TrueType fonts. When launched, Amaya looks first for some System pre-installed fonts and uses its own fonts if these pre-installed fonts are not available.
On Unix platforms, Amaya WX versions uses 3 configuration files to locate
needed fonts:Amaya/config/fonts.gl
, then
Amaya/config/fonts.gl.rd
, then
Amaya/config/fonts.gl.deb
.
On windows, Amaya WX versions uses one configuration file
Amaya/config/fonts.gl.win
.
Amaya GTK versions
Aamaya GTK works with the X Font Server (Xft). Some System distributions come with pre-installed fonts or fonts packages that auto-install. Some others must be installed by yourself.
If you must install fonts by yourself on a Linux platform, you have to:
- Unzip and/or untar download fonts and install them into
/usr/local/share/fonts
or/usr/X11R6/lib/X11/fonts
- Install them with the command like "
unzip
esstix.zip". We recommand to install them in the directory/usr/local/share/fonts/esstix
- Add this new font directory in the Xft configuration file:
/etc/X11/XftConfig
... dir "/usr/local/share/fonts/XXX"
- Add this new font directory in the right position in the
catalogue
list of/etc/X11/fs/config
This is an example:
catalogue = /usr/local/share/fonts/truetype, /usr/lib/X11/fonts/misc, /usr/lib/X11/fonts/cyrillic, /usr/lib/X11/fonts/75dpi/:unscaled, /usr/lib/X11/fonts/100dpi/:unscaled, /usr/X11R6/lib/X11/fonts/misc:unscaled, /usr/lib/X11/fonts/URW, /usr/lib/X11/fonts/Type1, /usr/lib/X11/fonts/CID, /usr/lib/X11/fonts/Speedo, /usr/lib/X11/fonts/75dpi, /usr/lib/X11/fonts/100dpi, /usr/local/share/fonts/esstix, /usr/local/share/fonts/japanese
- Then generate file descriptors:
fonts.scale
,fonts.dir
andXftCache
has follows:cd /usr/local/share/fonts/XXX ttmkfdir -o fonts.scale mkfontdir xftcache
- Reboot or restart the font server.
Esstix Fonts
Esstix Fonts are available (we provide a esstix.tar.gz
file) at
ftp://ftp.elsevier.nl/pub/styles/esstix/esstix.zipesstix.tar.gz
.
- Get Esstix fonts esstix.tar.gz file
- Install them with the command "
unzip
esstix.zip" or "tar xzf
esstix.tar.gz". We recommand to install them in the directory/usr/local/share/fonts/esstix
- Add this new font directory in the Xft configuration file:
/etc/X11/XftConfig
... dir "/usr/local/share/fonts/esstix"
- Then generate file descriptors:
fonts.scale
,fonts.dir
andXftCache
has follows:cd /usr/local/share/fonts/esstix ttmkfdir -c -m20 -o fonts.scale mkfontdir xftcache
- Reboot or restart the font server.
Amaya Win32 versions
Installation of Esstix fonts on a Windows platform
- Get Esstix fonts (we provide a ESSTIX.zip file)
- Extract the content of this zip file
- Copy fonts included in the ESSTIX directory into the C:\WINDOWS\Fonts directory.
II.8. How can I change the default window size?
Resize your window to the value you'd like, then use the Edit/Preferences/Geometry menu to save the current geometry of the displayed windows. Your modifications won't be lost the next time that Amaya is updated.
You can also request to save automatically the geometry on exit in the Edit/Preferences/General menu.
II.9. Can I see parsing errors detected by Amaya?
Amaya cannot be used to check validity of HTML pages. It accepts valid and invalid HTML documents and tries to dynamically correct errors. For example it's able to add missing end-tags and to move misplaced elements.
When parsing a XHTML document, Amaya checks it for well-formedness and stops as soon as it encounters an error. In that case, Amaya displays an alert box to indicate that the document is incomplete.
In both cases (HTML and XHTML documents) when Amaya finds tags and attributes it does not know or any error, it generates a log file which can be displayed by the command FileShow parsing errors.
II.10. What is the reason for a very liberal structure enforcement?
Amaya has to cope with existing HTML pages, and very few of them validate against the HTML DTD. When designing Amaya, we were faced with a difficult choice:
- Adopt a strict position and reject all invalid pages. Most users would be very disapointed not to be able to see many pages that other Web clients can display;
- Accept invalid pages and let Amaya fix the most common bugs.
We chose the latter option and decided that Amaya should try to fix bugs, but without losing information. If an element is not valid in a given context, Amaya tries to change the structure locally to make that element valid, but it doesn't delete the element or move it to a different place, which could change the document meaning.
The issue is that a DTD only specifies the structure of a document class, not its semantics. When you consider an invalid document, there are often several ways to transform its structure to make it valid, but each transformation may have a different impact on the document semantics. The DTD does not allow you to choose the right transformation.
Another important design decision that has been made for Amaya is that, even if it accepts invalid documents, the structure and markup that it produces is always valid. Obviously, only elements created or changed by Amaya itself are concerned here. Some invalid parts of the original document may remain when the document is saved.
The above remarks only apply to HTML documents. For XHTML, Amaya has a different, very strict behaviour: it stops parsing a document when it encounters a well-formedness error. The motivation is to help XHTML to deploy in a clean way. There are no legacy documents to support.
II.11. How can I update the document title?
The document title, like any other head element, can be edited in the Structure view of the document.
You can also use the specific dialogue Tools/Change title.
II.12. How to get out of a preformatted, a table, or a division?
When the cursor is at the end of a <pre>
formatted
element, hitting the Enter key creates a new line in the <pre>.
To create another element, say a paragraph, before or after the
<pre>
:
- Select the
<pre>
element with the ESC or F2 key or by clicking thepre
in the status bar displayed at the bottom of the window. - Insert an empty element before or after with Insert and
Append entries of the contextual menu.
If the current editing mode is XML (see the Text/XML button at the bottom right), another way to achieve Append action is to press the Enter key.
- Use the Insert menu or the Elements panel to insert the element you want to create.
This works also for a table or a division (<div>
).
II.13. Why doesn't Amaya support frames?
Frames cause lots of problems for the web model, e.g. standard URLs can only point at a frameset or a frame. Links and/or the back button can generate strange results. They also cause troubles to people with disabilities and make editing more complex. Unfortunately frames are not tagged deprecated and some people continue to use them. We recommend people to not use them.
II.14. Does Amaya support JavaScript and animated images?
Due to a lack of manpower, we have no plan to implement them. These features are more important for a browser than for an editor.
II.15. Amaya stops reading XHTML, MathML, or SVG documents!
XHTML is a reformulation of HTML 4.0 in XML1.0. XHML documents must be well formed which is not necessary the case of HTML documents. As soon as the XML parser Expat used by Amaya detects an error in the XHTML code it reports an error in the "Parsing Errors" file and stops parsing.
The most common errors are:
- The document declaration is not conform: the doctype or the namespace is not recognized.
- A closing tag is missing or the starting tag of an empty element doesn't include the final "/".
- An attribute value is not quoted.
- The document includes characters that don't match the document charset.
We recommend people to declare the charset of their documents. It could be declared either in the xml declaration, or/and in the meta element of XHTML documents (see an example below).
<?xml version="1.0" encoding="iso-8859-1"?> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> .... </head>
As the default charset is different for HTML documents and XHTML documents, it often occurs that authors created ISO-latin-1 XHTML documents which don't provide information about the charset. As soon as a character analyzed by the XML parser doesn't match a valid UTF 8 character (it should occur if the document is encoded in ISO-latin-1 but parsed as an UTF 8 file), the document is considered as invalid: the parsing is stopped and an error message is displayed.
In that specific case, you may try to reopen the document with a different charset, ISO-8859-1 or a set of other charset with the menu entry File>Force a Character Coding.
When the XHTML documents is not well formed, Amaya proposes to read the document as a simple HTML file. After that, you will be able to resave it back as an XHTML file with the Save As command.
II.16. Does Amaya support non-Latin characters?
The Unicode support is not completely finished yet. Depending on fonts available on your computer, some characters may or may not be displayed. Not available characters are displayed as small boxes.
II.17. Can I use CSS style sheets?
Amaya supports cascading style sheets (CSS), but the implementation is not complete yet. Many types of selectors and style properties are already available. Each release brings new CSS features. Check the status of the CSS implementation for the current release.
II.18. How can I publish my documents remotely?
Amaya supports remote publishing using the HTTP PUT method but it is not able to save files using FTP.
PUT needs not only to be supported by the web server, but also implemented.
Apache httpd doesn't implement PUT by default ; however, it provides hooks whereby you can install a PUT handler to implement the protocol.
- Read information about Configuring your WWW server with the PUT method
- If you google for "apache http put" you will find some useful articles too.
You can also try to install and activate WebDav module:
II.19. How to control the format of generated dates?
Amaya provides a $Date feature. When saving a file Amaya inserts the current date wherever it encounters a text "date:" between two '$' or special comments. The XHTML/Insert time stamp menu entry allows you to generate this date at the current position in the document.
The format of the generated date depends on a Amaya configuration variable.
ISO_DATE=Yes (default value) generates "YYYY-MM-DD"
YYYY = The year as a decimal number including the century.
MM = The month as a decimal number (range 01 to 12).
DD = The day of the month as a decimal number (range 01 to 31).
ISO_DATE=No generates "DD-MM-YYYY"
DD = The day of the month as a decimal number (range 01 to 31).
MM = The month as a decimal number (range 01 to 12).
YYYY = The year as a decimal number including the century.
II.20 How to move a division?
To copy or cut a division:
- Select a point within the division.
- Click in the status bar (at the bottom of the window) on the
<div>
, or press the F2 (or Esc) key until the<div>
element is selected. - Copy or cut it.
To paste the division before or after another division:
- Select the division like if you want to copy it.
- If you want to paste the copied division before, use the Insert entry of the contextual menu to create an empty element before the division.
- If you want to paste the copied division after, use the
Append entry of the contextual menu to create an empty
element after the division.
If the current editing mode is XML (see the Text/XML button at the bottom right), another way to achieve the Append action is to press the Enter key.
- Paste at that new position.
II.21 How to move a column or a row of a table?
To copy or cut a column:
- Use the Select column entry in the Tools/Edit
table submenu.
You can also start the selection in a cell, extend to another cell in the same column. Hitting the F2 key extends the selection to the whole column. Amaya changes to column selection mode.
- Copy or cut it.
To paste a column before or after another column:
- To paste a column before an existing column, click on a cell in the
existing column and use item Paste before of the
Tools/Edit table submenu.
If the selection is at the beginning of the cell, the Paste command is equivalent to a Paste before command.
- To paste a column after an existing column, click on a cell in the
existing column and use item Paste after of the
Tools/Edit table submenu.
If the selection is not at the beginning of the cell, the Paste command is equivalent to a Paste after command.
To copy or cut a row:
- You start the selection in a cell. Hitting the F2 key until it extends the selection to the whole row.
- Copy or cut it.
To paste a row before or after another row:
- To paste a row before an existing row, click at the beginning of the first cell in the existing row and use the Paste command.
- To paste a row after an existing row, click on a cell but not at the beginning of the first cell and use the Paste command.
II.22 How to display two documents side by side?
You can display two documents side by side in the window by dragging a document tab to the left or right side of the displayed document.
II.23 Installing Amaya on OpenSuse 12.1
See Rigo's mail about installing libraptor
III.1. Where can I get the developer's documentation?
Those who want to extend or change the Amaya application need to read the following documentation:
- Overview of the Amaya architecture.
- The Thot API manual explains how the Thotlib works and gives the list of available functions
- The Thot Application generation manual explains how to generate menus and the mechanism of Thot events.
- The Thot language manual gives the syntax of the S, P and T languages.
- The page Amaya-dev.html gives team conventions for writing the Thotlib and the Amaya code.
III.2. Make complains with missing files
This error occurs when one forgot to create the object subtree before launching the configure process. As explained in the Autoconf page, you have to create first a subtree (obj or any other name) for object code and launch configure to create the Makefile(s):
cd Amaya
mkdir obj
cd obj
../configure
III.3. Make fails when compiling the HTML schema
Thot compilers need a cpp preprocessor:
- If you use GNU tools, configure should invoke the gcc compiler with the
right options. You can check that file Options contains the
following definition:
CPP = gcc -E -x c
- In other cases you have to make sure that the cpp preprocessor is in your PATH.
III.4. What do I need to compile?
The new version of Amaya uses OpenGL (native or Mesa) canvas and wxWidgets toolkit, GTK+2.0 on Linux, Win32 on Windows and Cocoa on MacOSX, raptor.
See the Amaya WX README page.
III.5. I've a problem with ltconfig (or libtool)
Some platforms may have different versions of the autoconf and libtool tools. If you get a message similar to:
libtool: ltconfig version '' does not match ltmain.sh version '1.x.x' Fatal configuration error. See the libtool docs for more information.
Try running the following commands in both the Amaya
and the
libwww directory:
aclocal \
&& libtoolize --force --copy \
&& automake --foreign --force-missing --add-missing --copy \
&& autoconf
Thanks to Maxim Zakharov for this tip.
III.6. Make complains "test: argument expected"
The default shell version that your make command is probably too old. Try using bash instead by invoking the make command in your compilation directory as follows:
make SHELL=/path/to/your/bash