Creating Elements in Amaya

Amaya

## Creating elements

### Editing modes

Amaya offers two editing modes:

- The XML mode is very efficient for manipulating different types of XML structures, but it requires from the user a good knowledge of the document structure. The simple manipulations performed through a few keystrokes in the XML mode are generic: they can be performed for any type of element from any XML vocabulary, whatever their semantics. It works well with HTML text, but also with MathML equations or SVG drawings.
- The Text mode allows users to handle HTML elements in the same way as in a word processor. That mode does not apply to other XML vocabularies.

You can easily switch editing mode (Text/XML) by clicking on the corresponding button in the bottom right corner of the window.

### Buttons and menus

Entries of the Insert menu, and the corresponding buttons in the Elements tool, let you create new elements within a document. To use these commands, place the insertion point at the desired position and choose the element type.

The Elements tool allows you to immediately

- insert - or replace the current selection by - an XHTML element among the following:
  division ( ), headings ( , ,), paragraph (P), table (), target anchor or target element (), link anchor (), bulleted list (), numbered list (), definition list (), definition term (), definition (), image (), object ().
- open/close - or enclose the current selection by - an XHTML inline element:
  emphasis (), strong (), `code` (), insertion (), deletion (), superscript (), and subscript ().

Note: With the Lite profile, only a subset of these buttons and menu entries are available.

For more information about these elements see the list of all HTML 4.0 elements.

### Insertion point

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.

Sometimes elements can not be created at the chosen location because of the constraints imposed by the HTML language. Amaya then tries to create the element at the closest valid position in the document structure. For example, if the insertion point is within a paragraph, at the end of the last line, when you click on the heading button , Amaya creates the new heading after the paragraph, not within it.

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

### Hidden elements submenu

To create elements in the document `head`, use the Insert/Hidden elements submenu. These elements are displayed only in the structure and source views. The structure view should then be open. Put the cursor at the desired position and choose the element type from the Hidden elements submenu.

The Hidden elements submenu also enables you to create comments. Comments are shown only in the structure and source views, 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 usually contains a caption (`caption`), several rows (`tr`), and several cells (`td` or `th`) in each row.

When Amaya creates such elements, it also creates their components. To create a table Amaya displays a dialog that lets you choose to create it with or without a caption. You can also choose the number of rows and columns you want and other presentation options. The insertion point is placed automatically in the first generated cell. 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.

HTML defines inline elements that allow you to attach style to character strings. See Creating HTML Style Elements to create such elements.

### The Enter key

When you are writing a new document or a new part in a document, you can create elements sequentially by pressing the `Enter` key. The current element is terminated and a new one is created immediately after. The type of the new element depends on the HTML DTD.

When the cursor is at the end of a preformatted or a division element (`pre` or `div`), hitting the `Enter` key creates a new line in the `pre` or a new paragraph in the `div`.

In some cases the behaviour of the `Enter` key depends on the current editing mode:

- XML mode:

  To create a paragraph after a `pre` or a division after a `div`, you have to select the whole `pre` or `div` element, press the `F2` key, and press `Enter`. In the same way, you can create a new paragraph after a table by selecting the whole table and pressing `Enter`.

  When a whole element like `h2` or `li` is selected, the `Enter` key creates a new `h2` or `li`.

- Text mode:

  When the cursor is at the beginning or at the end of a list item (`li`), a new sibling list item element of same type is created, instead of a new paragraph within the list item. In addition, in an empty list item, the `Enter` key creates a paragraph that breaks the list.

  When the cursor is within elements such as `p`, `address`, `dt`, `h1`, `h2`, etc. (they are called block elements), the `Enter` key splits the element into two sibling elements of same type.

  When the insertion point is in HTML elements such as `strong`, `em`, `code`, `span`, `a`, etc. (they are called inline elements), the `Enter` key splits the inline element and the event is transmitted to the parent element. As inline elements may be nested in a HTML structure, the split may happen at several levels, until the event reaches a block or list item element, which processes the event as explained above.

  When the `Enter` key is hit at the beginning or at the end of a block element, a new paragraph (`p` element) is created, whatever the type of the current block element.

When the new element created is simply a paragraph, you can change the element type by selecting the desired type from the Insert menu or by clicking the corresponding button in the Element tool. You can also keep typing and change the element type later on.

#### Exiting anchors, inline elements, etc.

When a paragraph or another block of text is terminated by an anchor or a character string in bold, italic or other such inline element, moving the insertion point to the end and typing new text appends characters to the anchor or the inline element.

In XML mode only
  To exit an inline element and enter plain text: move the cursor to the end of the anchor or style element, and then press `Enter` and continue typing after the element.
  The same method can be used to enter plain text at the beginning of a block starting with an inline element. Move the cursor to the beginning of the anchor or style element, and then press `Enter` and continue typing before the element.
In Text and XML mode
  All Information type and Character elements can be set On/Off with the same command or button of the Elements tool.
  The Insert or Append commands of the Edit menu or contextual menu can be used to insert before the beginning or after the end of the inline element.

#### Creating nested structures

In XML editing mode (only), 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 list

   A paragraph in the first item

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

To create the above structure:

1. Click the Numbered List button to create the first item in the list.
2. Type in the list item text, and press the `Enter` key once. Amaya creates a new paragraph within the list item.
3. Type the paragraph text, and press the `Enter` key twice. The first `Enter` creates another paragraph element, but the second `Enter` removes that paragraph and creates a second list item in the original list.
4. Type in the second list item content.
5. Click the Numbered List button to create a new list. The new list is automatically nested within the first list.
6. Type the text for the first item in the new, nested list, and press the `Enter` key twice to create a new item in the nested list.
7. Type the text for the second list item, and press the `Enter` key four times to create a new list item in the original list.
8. Type the final list item, and then press the `Enter` key three times to close the original list and start a new paragraph after the list.

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 example, to add a list item between the first two items in the above structure, place the cursor at the beginning of the second list item, and press the `Enter` key twice.

Note: In XML mode, this use of the `Enter` key does not apply only to lists and paragraphs, but to all elements.

To move down/up list items:

The `Tab` command allows one to move down list items to a sub-list provided there is a previous item. As an example when the selection is within "The second item in the list.", pressing `Tab` will generate the following structure:

1. The first item in the list

   A paragraph in the first item

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

The `Shift Tab` command allows one to move up list items to the enclosing list. As an example when the selection is within "First item in the nested list.", pressing `Shift Tab` will generate the following structure:

1. The first item in the list

   A paragraph in the first item

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

### The Delete and Backspace keys

The behavior of the `Delete` and `Backspace` keys does not depend on the editing mode.

- If the insertion point is at the beginning or at the end of a block element and the `Delete` or `Backspace` key is hit, the whole content of the next (resp. previous) sibling element is merged with the content of the element that includes the insert point.
- When the insertion point is in inline elements the `Backspace` and `Delete` keys only delete characters, crossing inline element boundaries without any action on the structure. However, when an inline element becomes empty by deletions, it is itself deleted.

### Changing the document title

To edit the document title:

- Open the Tools menu and choose Change title.

Note:
You can also edit the document title from the structure view.

### Insert time stamp

The Tools/Insert time stamp menu entry allows you to insert the current date either in the ISO format (YYY-MM-DD) or in the European format (DD-MM-YYYY). The date format is set by the Preference menu.

Once the date is inserted, Amaya automatically updates it every time the document is saved and so maintains the last update date.