1.1. Command pasteFromWord

The "Paste from Word" add-on declares a generic command called pasteFromWord. The "Paste from Word" feature consists in invoking this command, typically from a menu item, with a parameter which configures the command for the type of the document being edited.

Excerpts from configuration file addon_install_dir/docbook5/docbook5.incl:

<menu label="-" insert="ifNotDefined(os.name*=Linux) _para">
  <item label="Paste from _Word" icon="../common/paste_from_word.png"
    command="pasteFromWord" 
    parameter="[xmlns:db=http://docbook.org/ns/docbook]
      [after db:para]

      [xmlns:pfw=java:com.xmlmind.xmleditext.paste_from_word.XPathFunctions]

      -p tables.set-column-number yes

      -p sections.max-level {pfw:docbookSectionMaxLevel(.)}

      -t paste-from-word:xslt/docbook5.xslt

      -p transform.hierarchy-name
      {if($pasting-root, local-name(/*), pfw:docbookHierarchyName(.))}

      -p transform.cals-tables yes"/>
  <separator />
</menu>

Command pasteFromWord can be executed when the document opened in XMLmind XML Editor (XXE for short) is editable and when the clipboard contains HTML. The fact that the HTML is non-filtered HTML generated by MS-Word 2003+ is checked later, when the command is actually executed.

1.1.1. Engine options

During its execution, command pasteFromWord runs the "Paste from Word" engine. This engine converts non-filtered HTML generated by MS-Word 2003+ to a valid document having the same type as the document being edited in XXE (e.g. it generates a DocBook 5 chapter). Then pasteFromWord pastes part or all of the document generated by the engine at the “right” location in the document being edited in XXE, given the current state of the selection. More information in Section 1.2, “The "Paste from Word" engine”.

Therefore the parameter of command pasteFromWord merely consists in options directly supported by the "Paste from Word" engine. Example taken from addon_install_dir/docbook5/docbook5.incl:

-p tables.set-column-number yes

However in order to be able to give these options values adapted to the document being edited in XXE, the option values are often XPath 1.0 expressions (enclosed in curly braces "{ }"). These expressions are evaluated in the context of the implicitly or explicitly selected element of the document being edited. Example taken from addon_install_dir/docbook5/docbook5.incl:

[xmlns:pfw=java:com.xmlmind.xmleditext.paste_from_word.XPathFunctions]1
...
-p transform.hierarchy-name2
   {if($pasting-root, local-name(/*), pfw:docbookHierarchyName(.))}3

1

This namespace prefix declaration allows XPath to invoke static methods found in Java™ class com.xmlmind.xmleditext.paste_from_word.XPathFunctions. More information in Section 2, “Java™ methods as extension functions” in XMLmind XML Editor - Support of XPath 1.0.

2

transform.hierarchy-name is a parameter which is passed to XSLT stylesheet paste-from-word:xslt/docbook5.xslt under the name hierarchy-name. This parameter specifies to the XSLT stylesheet what kind of DocBook 5 document should be generated. Examples: "book" (book containing chapters and sections), "chapter-sect1" (chapter possibly containing sect1, sect2, sect3, etc), "section" (section possibly containing sub-sections), "sect3" (sect3 possibly containing sect4, sect5).

3

This XPath expression reads: if command pasteFromWord is used to replace the root element of the document being edited, then generate the same element as the root element, otherwise lookup the ancestors of the context node (".", which is the implicitly or explicitly selected element of the document being edited) to determine the name of the hierarchy to be generated ("book", "chapter-sect1", etc).

1.1.2. Other options

The only option which is interpreted by command pasteFromWord itself and not by the "Paste from Word" engine is [after element_qname]. Excerpts from addon_install_dir/docbook5/docbook5.incl:

<item label="Paste from _Word" icon="../common/paste_from_word.png"
    command="pasteFromWord" 
    parameter="[xmlns:db=http://docbook.org/ns/docbook]
      [after db:para]
  ...

Excerpts from addon_install_dir/dita/topic.incl:

<item label="Paste from _Word" icon="../common/paste_from_word.png"
      command="pasteFromWord" 
      parameter="[after p]
  ...

DocBook element para and DITA topic element p are both plain paragraphs. However these elements may contain blocks such as lists and tables. Inserting a list or table in a plain paragraph makes the structure of the document hard to understand. That's why an option like [after db:para] instructs command pasteFromWord to paste blocks after db:para, and not inside db:para, even if this is allowed by the schema of the document.