insert_string [ -pendingdelete | -nopendingdelete] [ -markup] [ -bufferbuffername | -paste] [ -append] /newtext

This command inserts newtext at the current cursor location.

If there is selected text in the document, the command replaces the text according to the current setting of the set pendingdelete command. You can override or force the insert_string command to replace or preserve the current selection with the -pendingdelete and -nopendingdelete options. If -pendingdelete is set, the string replaces any selected text. If -nopendingdelete is set, any selected text is preserved and the inserted text is added to the right of the selected text.

If -markup is specified, the new text is interpreted as an XML (or SGML) string. This allows you to insert markup, diacritics, or special structures such as tables.

The insert_string -markup command will interpret the processing instruction <?Pub Caret> to set the cursor to a specific position within the inserted fragment. For example, after the command: insert_string -markup "<par>abc</par>" is executed, the cursor is placed after the end </par> tag.

However, with the insert_string -markup "<par>ab<?Pub Caret>c</par>" command, the cursor is positioned after the letter b. The <?Pub Caret> processing instruction must come after a character or tag in the markup string. It is ignored if it occurs at the start of the string. To position the cursor before an opening tag, the form <?Pub Caret1> can be used, for example, insert_string -markup "<par><?Pub Caret1>abc</par>" would position the cursor before the starting <par> tag.

If the <?Pub Caret> processing instruction is not included in the string, the cursor is placed per the following rules:

The -buffer option places newtext in a named paste buffer; -paste puts it in the default paste buffer. The -append option causes the string to be appended to the current contents of the buffer; otherwise, the string replaces whatever is in the buffer.

is is a synonym for insert_string.

Examples: