8. Commands for editing

8.1 Inserting Markup

The commands that insert start-tags works only if the document has an associated DTD.

Keyboard commands for inserting:

C-c <

Will ask, for the tag to insert, in the mini-buffer with completion on the tags that are valid at point (sgml-insert-tag).

If the option sgml-balanced-tag-edit is non-nil, inserting a start-tag will also insert the corresponding end-tag. If, in addition, sgml-auto-insert-required-elements is non-nil, tags for elements required between the inserted tags will also be inserted.

The list of valid tags, computed for a position in the buffer, will contain:

1. The end-tag for the current element, if it can be ended at the position and sgml-balanced-tag-edit is nil. Furthermore it will contain end-tags for enclosing elements if the necessary omissible end-tag declarations have been made in the DTD.

2. The start-tags of all elements that could occur after point. If sgml-omittag-transparent is nil, the above will be limited to the elements that can occur within the current element.

C-c C-e

Insert start and end-tags for an element (sgml-insert-element). The name of the element is read from the mini-buffer with completion on valid elements. If sgml-insert-end-tag-on-new-line is non-nil or the element has element content, the end-tag will be inserted on a new line after the start-tag.

If sgml-omittag-transparent is nil, the list of valid elements will only contain the elements that can be in the content of the current element.

Required elements in the content will be automatically inserted if the option sgml-auto-insert-required-elements is non-nil. When the content model demands an element but there is more than one to choose from, a comment can be inserted with the available choices if the option sgml-insert-missing-element-comment is non-nil.

C-c C-i

Inserts a new element in the current element where it is legal. Prompts for element name with completion. The completion list contains all elements that could be added to the current element somewhere, without making the content invalid. This assumes that the content is valid to begin with. Currently this list only has regular elements, not inclusions. The new element will be inserted as late as possible in the current element (unless prefix argument is given, then as early as possible.)

C-c C-r

Makes the region into a new element (sgml-tag-region). Reads element name from mini-buffer with completion as for C-c C-e.

C-c /

Inserts an end-tag for the current element (sgml-insert-end-tag).

C-c RET

Split the current element at point. If repeated, the containing element will be split before the beginning of then current element.

Typical use is to start a new paragraph element when inside a paragraph.

C-c +

Read attribute name and value from mini-buffer and insert attribute specification (sgml-insert-attribute). If point is immediately after a start-tag, this command operates on that start-tag. Otherwise the command will operate on the element after point.

The attribute name will be read with completion. If the attribute has a token list as declared value the attribute value will also be read with completion. The prompt for attribute value will typically look like:

Value for attribute (type Default: current value):

C-c C-u C-m

Give keyboard access to the customized part of the Markup menu. Emacs will prompt for the markup to insert using the menu line as selector. (See sgml-custom-markup below.)

Menu bar:

`Markup'

Selecting from this menu will insert markup. The menu contains sub menus with tags and with entities, some other markup and a user defined section.

Sub menus:

`Insert element'

Pops up a menu of valid elements and insert start and end-tags for the selected element. Selections from the menu works like the C-c C-e command.

`Insert start-tag'

Pops up a menu of valid start-tags and insert the selected tag. The menu has the same start-tags as the completion list for C-c <.

`Insert end-tag'

Pops up a menu of valid end-tags and insert the selected tag.

`Tag region'

Pops up a menu of valid elements and tag the region with the selection. Selections from the menu works like the C-c C-r command.

`Insert entity'

Menu of all general entities defined in the DTD.

`Add Element to Element'

Pops up a menu of all elements valid somewhere in the current element. The menu contains all elements that could be added to the current element somewhere, without making the content invalid. The new element will be inserted as late as possible in the current element.

`Insert attribute'

Pops up a menu with all the attributes of an element. The element is either the one which start-tag is immediately before point or the element after point. Selecting from this menu edits the attribute specification list for the element.

The menu has a sub menu for every attribute which declared value is a token list. The rest of the attributes are collected in one sub menu. For the token list attributes, selecting a value will insert that attribute-value pair. Selecting some other attribute reads the attribute-value from the mini-buffer and inserts the attribute value pair.

A menu is also available directly with a mouse button click in the buffer. In GNU Emacs it is the first mouse button combined with shift (S-mouse-3). In XEmacs it is bound to the third mouse button. The mouse button click will pop-up a menu of valid tags or a menu of attributes if the point is in a start-tag. The attributes menu works as the "Insert attribute" menu from the menu-bar. The tags list is the list of valid tags described above for command C-c <. Selection from the tags menu works like the C-c < command, with the following exception:

You can tag a region, with start and end-tag. There are two ways to indicate the region to mark:

1. Use the normal mouse commands to mark region.

   For this to work you must either use transient mark mode (see section `Transient Mark Mode' in The Emacs Editor) or set the option sgml-tag-region-if-active to non-nil (don't set this unless you are sure that you want it).

2. Alternatively make a secondary selection, this is done by holding down the meta key and using the mouse buttons. See section `Secondary selection' in The Emacs Editor. Some window managers intercept these events, which makes it hard use the secondary selection in Emacs.

User Option: sgml-balanced-tag-edit

If non-nil, inserting a start-tag using the context menu will also insert the corresponding end-tag.

User Option: sgml-auto-insert-required-elements

If non-nil, automatically inserts required elements in the content of an inserted element.

User Option: sgml-omittag-transparent

If non-nil, will show legal tags inside elements with omissible start-tags and legal tags beyond omissible end-tags.

User Option: sgml-tag-region-if-active

If non-nil, the `Insert tags' menu will tag a region if the region is considered active by emacs. If nil, region must be active and transient-mark-mode must be on for the region to be tagged.

User Option: sgml-custom-markup

Menu entries to be added to the Markup menu. The value should be a list of lists of two strings. The first string is the menu line and the second string is the text inserted when the menu item is selected. The second string can contain a `\r' where the cursor should be left. Also, if a selection is made according to the same rules as for the S-mouse-1 menu, the selection is replaced with the second string and `\r' is replaced with the selection.

Example:

(("Version1" "<![%Version1[\r]]>") ("New page" "<?NewPage>"))

User Option: sgml-insert-missing-element-comment

If non-nil, and sgml-auto-insert-required-elements also true, sgml-insert-element will insert a comment if there is an element required but there is more than one to choose from.

User Option: sgml-insert-end-tag-on-new-line

If non-nil, sgml-insert-element will put the end-tag on a new line after the start-tag. Useful on slow terminals if you find the end-tag after the cursor irritating.

8.2 Markup completion

If you are typing in markup directly, M-TAB will help you by completing a tag name, an entity name or a markup declaration name. If you type M-TAB after a plain word, ispell-complete-word will be invoked instead.

If you have typed (-!- marks the position of point)

&At-!-

and type M-TAB (assuming you use the `ISOLat1' entity set) you get:

&Atilde-!-

8.3 Showing information

Commands for showing information obtained by parsing the buffer.

C-c C-c

Shows in the message area: context at point, if in a tag or in mixed content and the open elements (sgml-show-context). The form of the string is controled by the user option sgml-show-context-function.

C-c C-w

Shows what element the character after point (under the cursor) belongs to; also shows context of element (sgml-what-element).

C-c C-t

Show information about the current element type and the valid element following the point.

C-c C-s

Show the major element structure in a separate buffer (`*Document structure*'). That buffer can be used to navigate the document, like an Occur buffer (see section `Other Search-and-Loop Commands' in The Emacs Editor). The structure shows container elements and the text of the first child element (if it is not a container). This works best for document types which uses containers and title structure (e.g. `<div> <title>Heder</title> ..</div>'). PSGML uses a heuristic rule to identify container elements: it should have element content and be non empty. You can configure exceptions from this rule using a process instruction in the DTD (see section 7.5 Customizing DTD).

To include an element type el1 that would otherwise be excluded:

<?PSGML element el1 structure=t?>

To exclude an element type el2 that would otherwise be included:

<?PSGML element el2 structure=ignore?>

List contextually valid tags (sgml-list-valid-tags). Displays information about current element, all valid end-tags, valid start-tags in current element, and start-tags valid at this point but in other elements together with the tags omitted.

User Option: sgml-show-context-function

The value shold be a function that generates a string from an element and the current markup type (if any). There are two ready made functions for this. The function sgml-show-context-standard, the default, generates a string like `#PCDATA in para in chapter in book'. The function sgml-show-context-backslash generates a string like `book\chapter\para'.

8.4 Indentation according to structure

You can indent a line according to the depth of element nesting at the beginning of the line. To indent the current line use TAB. You can also use LFD (newline-and-indent) to start a new line with correct indentation.

User Option: sgml-indent-step

How much to increment indent for every element level. If nil, no indentation.

If this is nil, TAB will insert a tab instead of indenting.

User Option: sgml-indent-data

If non-nil, indent in data/mixed context also.

8.5 Move in the element structure

These commands move in the element structure. The commands uses knowledge of SGML syntax, and if available the specific DTD.

C-M-a

Move to the (content) beginning of the current element (sgml-beginning-of-element).

C-M-e

Move to the (content) end of the current element (sgml-end-of-element).

C-M-f

Move forward by element (sgml-forward-element).

C-M-b

Move backward by element (sgml-backward-element).

C-M-u

Move up to before current element (sgml-backward-up-element).

C-c C-n

Move up to after current element (sgml-up-element).

C-M-d

Move down to the (content) beginning of the next element (sgml-down-element).

C-c C-d

Move to the next place where data is allowed (sgml-next-data-field).

You can also move to the next place where there is some structural error with C-c C-o (see section 5. Running an external SGML parser).

8.6 Editing attributes

If you want to change the attributes of a start-tag you can simply edit them directly in the buffer. Or you can place the cursor at or after the start-tag and use the sgml-edit-attributes command, available from the `SGML'-menu or on C-c C-a. This will create a new Emacs window with all possible attributes listed in the form

attribute name = current value.

The current value may be shown as `#DEFAULT' if the attribute has not been given a value in the start-tag. The list also contains the attributes declaration as a comment. Note also that the current value is show without eventual quotes.

It is now possible to edit the attribute values. You can move to the next attribute with TAB. If you want to let an attribute have its default value use C-c C-d, this will insert a `#DEFAULT' in the value field.

If Emacs is running in an X window, the `#DEFAULT' will be underlined to distinguish it from normal values.

Finish the editing with C-c C-c; this will replace the attribute values in the main buffer with those edited. Note that values will be quoted as needed.

If you want to abort the editing, you can remove the window with C-x 0 or if you want it neat, kill the buffer and remove the window.

Some other keys are:

C-a

Go to the beginning of the value field (sgml-edit-attrib-field-start).

C-e

Go to the end of the value field (sgml-edit-attrib-field-end).

C-c C-k

Clear the value field (sgml-edit-attrib-clear).

C-c C-d

Set the value field to `#DEFAULT' (sgml-edit-attrib-default). This is a special value that will make the attribute be implied.

8.7 Changing and deleting markup

C-c =

Change the name of the current element (sgml-change-element-name). Tries to translate attribute specifications. An attribute will be translated to an attribute with the same name. If the new element has no attribute with the same name, the attribute will be ignored. If there is an attribute with the same name but different declared content, a warning is given.

ID attributes are handled specially, an attribute with declared value ID will always be translated to the attribute with declared value ID.

C-c C-k

Kill next tag, markup declaration or process instruction (sgml-kill-markup).

C-M-k

Kill the element following the cursor (sgml-kill-element).

C-c -

Remove tags from current element (sgml-untag-element).

C-c #

Convert character after point to a character reference (sgml-make-character-reference). If called with a numeric argument, convert a character reference back to a normal character.

C-c C-q

Fills an element as a paragraph (sgml-fill-element). This is a substitute for the normal fill-paragraph. The command uses heuristics to decide what should be a paragraph.

1. If point is in an element content, recursively fill the sub-elements.
2. Find the biggest element with mixed content containing point.
3. If the above element is mixed but contains elements with pure element content then fill what is between the pure elements as paragraphs and fill the pure elements recursively.

M-x sgml-expand-all-shortrefs

Short references to text entities are expanded to the replacement text of the entity other short references are expanded into general entity references. If argument, to-entity, is non-nil, or if called interactive with numeric prefix argument, all short references are replaced by generally entity references.

M-x sgml-normalize

Normalize the document in the buffer. This will

1. expand short references,
2. insert missing tags,
3. replace minimized tags with full tags,
4. fix attribute specification lists according to options set.

There is one argument, to-entity, with the same meaning as for sgml-expand-all-shortrefs.

There is one option for the normalize command. With its default value, normalize may actually change the data content of some elements. But only by removing some white-space from the end of elements with omitted end-tags.

User Option: sgml-normalize-trims

If non-nil, sgml-normalize will trim off white space from end of element when adding end-tag.

Default: t.

8.8 Translating between characters and entity references

Set the variable sgml-display-char-list-filename to a file that contains mappings between all characters present in the presentation character set, and their "standard replacement text" names, e.g. "å" -> "[aring ]", e.t.c.

The default value for this variable is `iso88591.map'.

Then use the functions (also in the Modify menu)

sgml-charent-to-display-char

sgml-display-char-to-charent

to translate between entities and characters.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.