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-1>'). In Lucid Emacs 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" (Note:Transient Mark Mode.) 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. Note:Secondary
selection. 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 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.