## Creating new elements

### New documents

Amaya allows you to create new local or distant documents. Three types of document are available : XHTML, MathML or SVG.

To create a document, choose the New option in the File menu and select the appropriate type. Then, specify the URI or the local name of the new document (a default name is assigned to the document if no name is specified). After confirmation, Amaya opens a new window with the specified document. If this document already exists, Amaya loads its current version otherwise. a new document with the corresponding root element is created.

### Buttons and types menu

The simplest way to create new elements in a document is to move the insertion point to the desired position and to use the Types menu or the buttons corresponding to the most common elements (image, headings, lists, etc.). These buttons and menu items create the corresponding element at the current position.

In some cases, the desired element cannot be created exactly at the position chosen, because of the constraints imposed by the HTML DTD. Amaya then tries to create the element at the closest position where it is allowed. For instance, if the insertion point is at the end of the last line of a paragraph when you click on the button, Amaya does not create the new heading at that particular position (which would be invalid), but after the paragraph (which is probably what you intended).

In some other cases, Amaya changes the existing structure for creating the desired element. If the insertion point is somewhere within a list item (`LI`) when you create a second level heading (for example with the button, or from the menu), the list item and its enclosing list are automatically split, in order to create the requested heading at the chosen position and to comply with the HTML DTD.

When creating new elements, it is important to select an insertion point, not some text nor a single character: if the current selection is not empty, Amaya tries to transform the selected part into the element type chosen.

Some documentation of how to use element types is available, as well as a briefly annotated list of all the HTML 4.0 elements.

### Structure menu

The Types menu allows you to create only elements that are part of the document `BODY`. To create elements in the document `HEAD`, use the Structure menu from the Structure view. This menu works in the same way as the Types menu: put the caret at the desired position and choose the element type from the Structure menu.

The Structure menu also allows you to create comments, using its Comment entry. Comments are shown only in the Structure view, but they can be inserted at any position in the document.

#### Generated elements

Some HTML elements are constituted by several other elements of different types. For instance, a table contains usually a caption (`CAPTION`) and several rows (`TR`) and several cells (`TD` or `TH`) in each row.

When Amaya creates such elements, it also creates their components. A table is created with a caption and a row containing a single cell. The insertion point is placed automatically in the first of these components. You can enter the content of that component immediately or later. You can move to the next (empty) component with the mouse or with the arrow keys.

### The Enter (or Return) key

When you are writing a new document or a new part in a document, you often create elements sequentially. To do that, just press the Enter (or Return) key. The current element is terminated and a new one is created just after. This applies obviously to paragraphs, but also to other types of elements, such as headings or table cells for instance.

Most often, the new element created is simply a paragraph, whatever the type of the previous element. If you need another element type, you can immediately change the type of that element, by selecting the desired type in the Types menu or by clicking on the corresponding button, but you can also keep typing and change the type later.

#### Multiple Enters at the end of an element

When the insertion point is in an empty element, pressing the Enter key replaces that element by another empty element at the next higher level in the document structure. This feature allows you to create complex nested structures very quickly.

As an example, consider the following structure:

1. The first item in the highest level list.

   A paragraph in the first item.

2. The second item.
   1. First item in the nested list.
   2. Second item in the nested list.
3. Last item in the list.

To create that structure, create first a numbered list with a first item (for example by clicking on the button) and type in the first line. At the end of that first line, press the Enter key: it creates a new paragraph in the item. At the end of this paragraph, press the Enter key: it creates yet another paragraph, but pressing the same key again replaces that paragraph by an empty item 2. At the end of the first line of item 2, create a new list with its first item (for example click on the button). The new list will automatically be nested. Item b. is created by a double Enter at the end of item a. When the insertion point is at the end of item b, create item 3 by four successive Enters. To create the paragraph that follows these lists, press Enter three times when the insertion point is at the end of item 3.

#### Multiple Enters at the beginning of an element

The Enter key works in the same way when the insertion point is at the beginning of an element, but it creates new elements before the current element.

For instance, you can add an initial paragraph in a list item by moving the insertion point before the first character of that item and pressing Enter. If you press Enter twice, you get a new item before the current item. This is useful for inserting a new item before the first one.

This use of the Enter key does not apply only to lists and paragraphs, but to all elements. It is for instance very convenient for creating tables.

#### Exiting anchors or styled character strings

When a paragraph or another block of text is styled - terminated by an anchor or a character string in bold, italic or other such style - moving the insertion point to the end and typing appends characters to the anchor or the styled string. If you want to exit this styled element and enter plain text, just press `Enter` to exit from the anchor or styled element, and type.

When a paragraph or another block of text is styled - starts with an anchor or a styled character string - moving the insertion point to the beginning and typing inserts characters into the anchor or the styled string. If you want to insert before this styled element and enter plain text, just press Enter to exit from the anchor or styled element, and type.

#### Editing definition lists (dl/dt/dd)

The Enter key is also useful for editing definitions lists. Consider the following example:

> Term1
> Term2
>   Definition of both terms.

It is a definition list (`dl`) containing two terms (`dt`) followed by a definition (`dd`). To add a new paragraph within the definition (`dd`), put the caret at the end (after word "terms") and hit the Enter key. If you hit Enter twice, you exit from the current definition (`dd`) and you create a new term (`dt`). At the end of that new term, pressing Enter once allows you to create another new term (`dt`). Pressing Enter twice creates a new definition (`dd`) instead.

If you want to create a new term and its definition before Term1, put the caret at the beginning of "Term1" and press Enter. Type the new term (`dt`). Then press Enter twice: a new definition (`dd`) is created right after the new term.

### Changing the document Title

You can edit the document title (TITLE element) in with the menu entry Types/Change Title. You can also edit the document title in the structure view.

### White-space handling

For the XHTML, MathML, SVG documents as well as for MathML or SVG elements included into a HTML document, Amaya removes the insignificant white-space characters when it loads a document unless they must be explicitly preserved.

Are considered as insignificant white-space characters:

- the end of line characters (#xD et (#xA),
- the tabs characters (#X9),
- the leading spaces of an element,
- the trailing spaces of an element,
- the contiguous spaces (in that case, one space is preserved).

If an author wants to preserve all the characters for some elements, he can use the `xml:space` attribute or the element `PRE` (that element is only valid for XHTML documents). The only possible values for that attribute are "`default`" and "`preserve`". The value "`default`" signals that applications' default white-space treatments are acceptable for these elements. In Amaya, the default treatment removes the insignificant white-space characters for all supported DTD (see above). The value "`preserve`" indicates the intent that applications preserve all the characters, except the first one that immediately follows the end tag of the element where it is specified if that element is an end of line. The `xml:space` attribute is applied to all elements within the content of the element where it is specified, unless overriden with another instance of the `xml:space` attribute. Concerning the XHTML DTD, the element `PRE` causes the same behaviour that the `xml:space` attribute with the value "`preserve`".

Amaya applies the white space handling when it loads a document, not when we are editing it. A consequence is that if you type insignificant white-space characters, its will be visible and saved but will be removed at the next loading. For example, the following source code:

`<p>Amaya removes the<strong> insignificant white-space </strong>when it loads ...</p>`

gives during edition:

    Amaya removes the insignificant white-space when it loads...

and will be saved with that syntax. At the next loading of the document, this code will give:

`Amaya removes the` `insignificant white-space` `when it loads...`

because the leading space and the trailing space of the element `strong` are considered as insignificant and are removed.

The correct source code would be:

`<p>Amaya removes the <strong>insignificant white-space</strong> when it loads ...</p>`