# ooxml-docx(n) | ooxml user documentation

# NAME

::ooxml::docx - Create ECMA-376 Office Open XML writer documents (the .docx format)

# SYNOPSIS

    package require ooxml::docx
    ::ooxml::docx::docx new *?-option value ...?* ?docx-file?

# DESCRIPTION

The command ::ooxml::docx creates a new docx object.

Without the optional file argument the object represents an almost minimal empty document.

If the last argument is an ECMA-376 Office Open XML WordprocessingML document (vulgo a .docx file) the inital document is a copy of this .docx.

The object has methods to append and style content as text, tables, pictures or textboxes. The .docx file created by the object can be read by word processing programs as libreOffice or Word.

A simple “Hello, World” example is:

    set docx [ooxml::docx::docx new]
    $docx paragraph "Hello, World!"
    $docx write hello.docx
    $docx destroy

The style and appearance of the content is determined in order by local setting, by referencing to a defined style or finally by the default settings.

The methods of a docx object typically expect, if ever, a few arguments required in order and after that option value pairs. The options may appear in any order. An unknown option is reported as error. If an option is given more than one time then the last one wins.

The value of an option is - depending on the option - either a single value or a key value list. In the second case the key value pairs may be in any order. If a key is given more than one time then the last one wins. An unknown key is reported as error. In almost all cases the value given to the option or key will be type checked.

Content to the document is added top down.

The created docx object commands currently support the following methods:

append text ?-option value …?

  Appends text to the last paragraph of the content of the document. The option/value pairs control the appearance of the text within the paragraph. See CHARACTER OPTIONS for the valid options and the type of their value.

appendTo objectId creatingScript

  This method appends content to an already created table, table row table cell, footer, header, footnote, endnote, comment or textbox. The objectId has to be the id returned by the method which created the object. The creatingScript is evaluated and creates the appended object content. The resulting document is the same as if the creatingScript would have been appended to the creatingScript of the method which created the object.

br ?n?

  Inserts a line break into the current paragraph. The optional argument n (default 1) specifies the number of breaks to insert.

comment ?-option value …? creatingScript

  This method creates a comment to the current point in the document with comment content created by the creatingScript and returns the object id of the created comment. Although the standard allows much more rich content most word processor support only basic text formatting for comments.

  The allowed options are

        -author string

        -date <xsd datetime>

        -initials string

commentrangeend id ?-option value …? creatingScript

  This method marks the end of a range of content in the document and creates a comment to this content range with comment content created by the creatingScript and returns the object id of the created comment. The id argument must be the id returned by the corresponding commentrangestart call. For the allowed options see the method comment.

commentrangestart ?returnvar?

  This method marks the start of a range of content in the document for which a comment should be added. The method returns the id of the range and stores the id additionally in the variable with the name resultvar, if the optional argument is given.

destroy

  Destroys the docx object and releases all associated DOM documents and resources. Inherited from TclOO.

configure ?-option value …?

  Set certain document properties. The recognized options are:

        -category

        -contentStatus

        -created

        -creator

        -description

        -identifier

        -ignorable prefixList: Set the MC Ignorable prefixes (e.g. "w14 wp14").

        -keywords

        -language

        -lastModifiedBy

        -lastPrinted

        -modified

        -revision

        -subject

        -title

        -version

endnote ?-option value …? creatingScript

  Creates an endnote with content produced by creatingScript and returns the object id of the created endnote. A reference mark is inserted at the current position in the document. The allowed options are:

  -refstyle styleRef: Character style applied to the reference mark. The value may be either the internal style ID (w:styleId) or the display name (w:name).

  The other -option value pairs allows formatting of the (whole) endnote value. See CHARACTER OPTIONS for the valid options and the type of their value.

field field-type ?switches? ?-option value …?

  Appends the given field type to the last paragraph. Recognized field types are

            AUTHOR
            CREATEDATE
            DATE
            FILESIZE
            PAGE
            NUMPAGES
            SAVEDATE
            SECTION
            TIME
            TITLE
            USERNAME

  If the optional argument switches is given its value will be appended as the field switches to the field-type name. The following optional -option value pairs allows formatting of the (whole) inserted field value. See CHARACTER OPTIONS for the valid options and the type of their value.

footnote ?-option value …? creatingScript

  Creates a footnote with content produced by creatingScript and returns the object id of the created footnote. A reference mark is inserted at the current position in the document. The allowed options are:

        -refstyle styleRef: Character style applied to the reference
        mark. The value may be either the internal style ID (*w:styleId*)
        or the display name (*w:name*).

footer creatingScript ?returnvar? ?objectIdvar? header creatingScript ?returnvar? ?objectIdvar?

: Creates a new footer or header by evaluating the creating script. The id of the created footer or header is returned and, if given, stored in the returnvar. This is the id to refer to the footer or header to be used with the options -defaultHeader, -firstHeader, -evenHeader, -defaultFooter, -firstFooter and -evenFooter of the methods pagesetup and sectionstart. The object id of the created footer or header is stored in the objectIdvar, if given. This is the id to use with the method appendTo.

image file anchor|inline ?-option value …?

  An inline image is part of the text, like a character (and therefore may change the line height). An anchor image is also anchored at an exact place within the text (which determines the page at which the image is shown) but can be freely placed at the page.

  Both types of images share the following options:

       -dimension *keyValueList*: Required. Sets the image size. Keys:
           width (EMU), height (EMU).

       -bwMode *(auto|black|blackGray|blackWhite|clr|gray|grayWhite|
           hidden|invGray|ltGray|white)*: Black-and-white mode
           (default "auto").

  Anchor images additionally accept:

       -anchorData *keyValueList*: Anchor attributes. Keys: behindDoc,
       distT, distB, distL, distR, hidden, locked, layoutInCell,
       allowOverlap, relativeHeight.

       -positionH *relativeFrom*: Horizontal position reference
       (column, character, insideMargin, leftMargin, margin, outsideMargin,
       page, rightMargin). Default "column".

       -alignH *(left|right|center|inside|outside)*: Horizontal alignment
       (mutually exclusive with -posOffsetH).

       -posOffsetH *EMU*: Horizontal offset (mutually exclusive with
       -alignH).

       -positionV *relativeFrom*: Vertical position reference (insideMargin,
       line, margin, outsideMargin, page, paragraph, topMargin,
       bottomMargin). Default "paragraph".

       -alignV *(inline|top|center|bottom|inside|outside)*: Vertical
       alignment (mutually exclusive with -posOffsetV).

       -posOffsetV *EMU*: Vertical offset (mutually exclusive with -alignV).

       -wrapMode *(none|square|topBottom)*: Text wrapping mode (default
       "none").

       -wrapData *keyValueList*: Wrap attributes (only with -wrapMode
       square). Keys: wrapText, distT, distB, distL, distR.

import part docx

  Imports the given part from the file docx into the docx object, replacing what the object had for that part of the docx zip archive.

  The shortcut “styles” may be used for word/styles.xml and “numbering” for word/numbering.xml.

jumpto text markid ?-option value …?

  Appends the text text to the last paragraph and if the text is clicked as link (typically Ctrl-Button-1) the text processor jumps to the mark with the id markid inside the document.

  The option/value pairs control locally the appearance of the text within the paragraph. See CHARACTER OPTIONS for the valid options and the type of their argument.

mark markid

  Sets the mark markid at the end of the last paragraph.

markstart name

  Starts a named bookmark span at the current position. The bookmark name must be unique within the document. Use markend to close the span.

markend name

  Ends the bookmark span previously opened by markstart with the same name.

math ?-option value …? creatingScript

  Creates a math zone. The creatingScript creates the math content using the math methods described below. By default the math is inline within the current paragraph. Options:

           -display *onOffValue*: If on, the math is rendered as a display
           equation on its own paragraph.

           -jc *(left|center|right|centerGroup)*: Justification of a display
           equation. Ignored when -display is off.

  Inside the creatingScript, the following math methods are available. All math methods must be called from within the creatingScript of a math call; calling them outside a math zone raises a Tcl error. Invalid option values also raise a Tcl error.

mrun ?-option value …? text

  Creates a math run (text within a math zone). Options:

        -lit *onOffValue*: Literal (non-italic) text.

        -sty *(p|b|i|bi)*: Math style (plain, bold, italic, bold-italic).

        -scr *(roman|script|fraktur|double-struck|sans-serif|monospace)*:
        Math font script.

        -nor *onOffValue*: Normal text (non-math font). Mutually exclusive
        with -sty/-scr.

        -aln *onOffValue*: Alignment point.

        -brk *onOffValue*: Line break. -brkAt *integer*: alignment position
        after break.

mfrac ?-option value …? numeratorScript denominatorScript

  Creates a fraction. The two scripts create the numerator and denominator content. Options:

           -type *(bar|lin|noBar|skw)*: Fraction type. Defaults to bar (stacked
           with horizontal rule). *lin* gives a linear (inline slash) form,
           *noBar* stacked without bar, *skw* skewed.

msub baseScript subscriptScript

  Creates a subscript construct.

msup baseScript superscriptScript

  Creates a superscript construct.

msubsup baseScript subscriptScript superscriptScript

  Creates a simultaneous sub-superscript construct.

msqrt radicandScript

  Creates a square root.

mroot degreeScript radicandScript

  Creates an nth-root. The degreeScript produces the root index (e.g. 3 for cube root) and radicandScript the expression under the radical.

mnary ?-option value …? baseScript

  Creates an n-ary operator (summation, product, integral, etc.). Options:

        -char *string*: The operator character (e.g. "∑", "∏", "∫").

        -limLoc *(undOvr|subSup)*: Limit placement — under/over or
        sub/superscript position.

        -grow *onOffValue*: Whether the operator grows with its content.

        -sub *script*: Subscript (lower limit) content script.

        -sup *script*: Superscript (upper limit) content script.

        -subHide *onOffValue*: Hide the subscript.

        -supHide *onOffValue*: Hide the superscript.

mfunc nameScript argumentScript

  Creates a function application construct (e.g. sin, cos, lim).

mlimlow baseScript lowerLimitScript

  Creates a lower-limit construct (limit below the base).

mlimupp baseScript upperLimitScript

  Creates an upper-limit construct (limit above the base).

maccent ?-option value …? baseScript

  Creates an accent construct — places a diacritical mark (hat, tilde, dot, vector arrow, etc.) above the base expression.

        -char *string*: The accent character. Default is the combining
        circumflex accent (U+0302). Common values:
        U+0303 (tilde), U+0307 (dot), U+0308 (double dot),
        U+20D7 (combining right arrow / vector).

mbar ?-option value …? baseScript

  Creates an overline or underline bar above or below the base.

        -pos *top|bot*: Position of the bar (default "top" = overline).

mdelim ?-option value …? script

  Creates a delimiter construct — wraps content in matching delimiters such as parentheses, brackets, braces, absolute-value bars, norms, floor/ceiling symbols, etc.

  The script body creates the content. For a single argument, math methods in the script create content directly within an m:e element. For multiple arguments separated by the separator character, use mdelimarg within the script.

        -begChr *string*: Opening delimiter character (default "(")
        -endChr *string*: Closing delimiter character (default ")")
        -sepChr *string*: Separator character between arguments (default "|")
        -grow *onOffValue*: Delimiters grow to match content height
        -shp *centered|match*: Delimiter shape

mdelimarg script

  Creates a delimiter argument (m:e child) inside an enclosing mdelim. Each call to mdelimarg wraps its script content in a separate m:e element, enabling multi-argument delimiters.

mgroupchr ?-option value …? baseScript

  Creates a grouping character construct — an underbrace, overbrace, or similar character that spans the base expression. Commonly used to label parts of an equation.

        -char *string*: The grouping character (default U+23DF = ⏟ bottom
        curly bracket). Use U+23DE for overbrace (⏞).
        -pos *top|bot*: Position of the character (default "bot")
        -vertJc *top|bot*: Vertical justification of the base relative to
        the grouping character

mmatrix ?-option value …? rowScripts

  Creates a matrix. The rowScripts argument is a list; each element is a script that creates cells via mmatcell calls. Wrap in mdelim for bracket/parenthesis notation.

        -baseJc *top|center|bottom*: Vertical alignment of the matrix
        relative to the math baseline
        -mcJc *left|center|right*: Column justification
        -count *integer*: Number of adjacent columns sharing the
        justification (1–255)

mmatcell script

  Creates a matrix cell (m:e child) inside a matrix row. Each call wraps its script content in a separate m:e element.

numbering subcmd args

  Manages numbering definitions (lists, outlines).

  The supported subcommands are:

  abstractNum id levelDefinitions: Creates an abstract numbering definition with the given integer id. The levelDefinitions argument is a list; each element defines one level using option/value pairs:

        -numberFormat *format*: Numbering format (decimal, upperRoman,
        lowerRoman, upperLetter, lowerLetter, bullet, etc.)
        -levelText *string*: Level text template (e.g. "%1." or "%1.%2")
        -align *alignment*: Number alignment (start, center, end, etc.)
        -start *integer*: Starting number (default 1)

  Paragraph and character options may also be given per level to style the number and the paragraph.

  A corresponding w:num entry is automatically created with the same numId as the abstractNumId.

  Example:

         $doc numbering abstractNum 0 {
             {-numberFormat decimal -levelText "%1." -align start}
             {-numberFormat lowerLetter -levelText "%2)" -align start}
         }

  abstractNumIds: Returns a sorted list of all abstractNum IDs.

  delete type id: Deletes a numbering definition. type is either abstractNum or num; id is the integer ID.

pagebreak

  Appends a page break to the document.

pagesetup ?-option value …?

  The allowed options are:

        -margins keyValueList

        -paperSource keyValueList

        -sizeAndOrientation keyValueList

        -defaultHeader id
        -defaultFooter id
        -firstHeader id
        -firstFooter id
        -evenHeader id
        -evenFooter id

  The last block of options set the respectively header or footer. The id has to be returned from a header or footer method call.

         -border

         -pageNumbering

        -sectionType *(continuous|evenPage|nextColumn|nextPage|oddPage)*

  Specifies the type of the current section break. The default is nextPage. Use continuous to start a new section on the same page (e.g. for switching between single and multi-column layout).

        -docGrid *keyValueList*

  Configures the document grid for the section, controlling line pitch and character spacing for CJK and other layout needs. The accepted keys are:

        type        Grid type: "default", "lines", "linesAndChars",
                    or "snapToChars".
        linePitch   Distance between lines (integer, in twips).
        charSpace   Additional character pitch (integer, in 4096ths
                    of a point).

        -vAlign *(top|center|bottom|both)*

  Vertical alignment of text on the page. The value both distributes text evenly between the top and bottom margins (justified).

paragraph text ?-pstyle style? ?-cstyle style? ?-option value …?

  Appends text as paragraph to the content of the document. If the -pstyle option is given, the referenced paragraph style will be used. If the -cstyle option is given the referenced character style will be used. Style values may be given either as the internal style ID (w:styleId) or as the display name (w:name). Resolution prefers an exact style-ID match and falls back to the display name. The other options may locally overwrite a style setting or add more properties. See PARAGRAPH OPTIONS and CHARACTER OPTIONS for the valid options and the type of their argument.

readpart part filename

  Replaces the named XML part in the docx object with the contents of filename. The file is parsed as XML and replaces the in-memory DOM for that part. Example:

      $doc readpart word/settings.xml mysettings.xml

replace from to ?part_list?

  Replaces every from substring in any text with to, Only uniformly styled text is replaced (if from spans over more than one text part it will not be recognized). Without the optional part list argument all parts of the document (the main documentbody, footnotes, comments pp.) will be processed. If the argument is given then only the named parts will be processed. The elements of the part list may be a Tcl glob expression. Part names given by the part list argument which are currently not exists in the object will be silently ignored.

sectionend

  Ends the current section, emitting the stored section properties as a w:sectPr inside the last paragraph. Must be preceded by a sectionstart call; raises an error otherwise.

sectionstart ?-option value …?

  Starts a new section in the document. If a previous section was already started (and not ended), it is implicitly ended first. The allowed options are the same as for pagesetup: -margins, -sizeAndOrientation, -sectionType, -docGrid, -vAlign, -border, -pageNumbering, header/footer references, etc.

settings ?-option value …?

  Modifies the document settings (word/settings.xml). Settings may be called multiple times; each call updates or adds the specified settings without affecting those set by earlier calls.

  Special option:

            -reset *onOffValue*: If on, resets all settings to defaults before
            applying the remaining options.

  Commonly used settings:

           -defaultTabStop *integer*: Default tab stop distance in twips.
           -autoHyphenation *onOffValue*: Enable automatic hyphenation.
           -evenAndOddHeaders *onOffValue*: Use different headers/footers for
           even and odd pages.
           -hideSpellingErrors *onOffValue*: Hide red squiggly underlines.
           -hideGrammaticalErrors *onOffValue*: Hide grammar error marks.
           -trackRevisions *onOffValue*: Enable revision tracking.
           -mirrorMargins *onOffValue*: Mirror left/right margins for
           facing pages.
           -embedTrueTypeFonts *onOffValue*: Embed TrueType fonts.
           -documentProtection *keyValueList*: Protect the document.
           Keys: edit (readOnly|comments|trackedChanges|forms|none),
           enforcement (on|off), formatting (on|off), plus optional
           cryptographic parameters.

  Many more settings are available. On/off settings use onOffValue. Refer to the property table in the source for the complete list.

selectNodes xpath ?part? ?selectNodes options?

  Returns the result of the xpath expression. If no other argument is given the context node will be the document element node of the word/document.xml part of the docx. If the part argument is given the context node of the expression will be the document element of the docx part identified by this argument. If part is a relative path inside the docx zip (example: _rels/.rels) then this is used. All parts of the docx inside the word directory may specified without the directory part and the .xml suffix. The optional selectNodes options are routed throw.

  All documents accessible by this have the following prefix namespace mappings predefined:

  Prefix | Namespace
  --- | ---
  a | http://schemas.openxmlformats.org/drawingml/2006/main|
  ct | http://schemas.openxmlformats.org/package/2006/content-types|
  m | http://schemas.openxmlformats.org/officeDocument/2006/math|
  mc | http://schemas.openxmlformats.org/markup-compatibility/2006|
  o | urn:schemas-microsoft-com:office:office|
  pic | http://schemas.openxmlformats.org/drawingml/2006/picture|
  r | http://schemas.openxmlformats.org/officeDocument/2006/relationships|
  rel | http://schemas.openxmlformats.org/package/2006/relationships|
  sl | http://schemas.openxmlformats.org/schemaLibrary/2006/main|
  v | urn:schemas-microsoft-com:vml|
  w | http://schemas.openxmlformats.org/wordprocessingml/2006/main|
  w10 | urn:schemas-microsoft-com:office:word|
  w14 | http://schemas.microsoft.com/office/word/2010/wordml|
  wp | http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing|
  wp14 | http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing|
  wpg | http://schemas.microsoft.com/office/word/2010/wordprocessingGroup|
  wps | http://schemas.microsoft.com/office/word/2010/wordprocessingShape|

simplecomment comment ?-option value …?

  This method creates a comment to the current point in the document. The text content of the comment will be what is given by the argument comment. For the allowed options see the method comment. Additionally to this options all PARAGRAPH OPTIONS and CHARACTER OPTIONS are allowed. If given they are applied to format the comment text.

simplecommentrangeend id comment ?-option value …?

  This method marks the end of a range of content in the document and creates a comment to this content range with comment content given by the comment argument. The id argument must be the id returned by the corresponding commentrangestart call. For the allowed options see the method comment. Additionally to this options all PARAGRAPH OPTIONS and CHARACTER OPTIONS are allowed. If given they are applied to format the comment text.

simpletable tabledata ?-option value …?

  Creates a table from a nested list. Each element of tabledata is a row; each element within a row is a cell’s text content.

  Example: `$doc simpletable {{A1 B1 C1} {A2 B2 C2}}`

  Options:

        -columnwidths *list*: Column widths (measurements).
        -firstStyle *styleName*: Character style for the first row.
        -lastStyle *styleName*: Character style for the last row.

  Table-level options (-style, -width, -align, -layout, -look, -tableBorders, cell margins) are also accepted — see table.

style subcommand args

  The supported subcommands are:

        paragraphdefault ?-option value ...?

        characterdefault ?-option value ...?

        paragraph name ?-option value ...?

        character name ?-option value ...?

        table name ?-option value ...?

      The *name* argument is the display name of the style. The
      internal style ID (w:styleId) is derived from the name by
      stripping non-alphanumeric characters. Use the **-styleid**
      option to set the internal ID explicitly if the derived ID
      would be empty or ambiguous. Both display name and derived ID
      must be unique within the style type.

      Additional style creation options:

         -basedon styleRef:

      Parent style to inherit from. Accepts
      either an internal style ID or a display name (resolved to a
      style ID internally). The parent must be the same type as the
      style being created.

        -conditional keyValueList:

  (Table styles only.) Conditional formatting for table regions such as firstRow, lastRow, firstColumn, lastColumn, band1Vert, band1Horz, etc.

      All methods and options that reference a style (such as
      **-pstyle**, **-cstyle**, **-style**, **-basedon**,
      **-refstyle**) accept either the internal style ID (preferred,
      tried first) or the display name (fallback).

        ids styletype

        names styletype

        delete styletype name

tab ?n?

  Inserts a tab character into the current paragraph. The optional argument n (default 1) specifies the number of tabs to insert.

table ?-option value …? creatingScript

  Creates a table by defining every row and cell individually by the creatingScript and returns the object id of the created table. The recognized options are:

        -columnwidths *list*: List of column widths (measurements).

        -style *styleRef*: Table style reference (style ID or display name).

        -width *keyValueList*: Table width. Keys: type (auto|dxa|pct|nil),
        value (measurement or percentage).

        -align *(center|end|left|right|start)*: Table alignment.

        -layout *keyValueList*: Table layout. Keys: type (autofit|fixed).

        -look *keyValueList*: Table conditional formatting flags. Keys:
        firstRow, lastRow, firstColumn, lastColumn, noHBand, noVBand
        (all on/off).

        -caption *string*: Table caption for accessibility.

        -tableBorders: Table border options. For each border position
        (top, left, bottom, right, insideH, insideV), use
        `-<position>Border {type <borderType> color <hex> borderwidth <eighthPts> space <pts>}`.

        -cellMarginTop, -cellMarginStart, -cellMarginLeft,
        -cellMarginBottom, -cellMarginEnd, -cellMarginRight:
        Default cell margins. Each takes a *keyValueList* with keys
        type and value.

tablecell ?-option value …? creatingScript

  Creates a table cell within a tablerow script and returns the object id of the created table cell. The creatingScript creates the cell content (paragraphs, nested tables, etc.).

  Options:

        -cellWidth *keyValueList*: Cell width. Keys: type (auto|dxa|pct|nil),
        value (measurement or percentage).

        -span *integer*: Number of grid columns this cell spans.

        -hspan *(restart|continue)*: Horizontal merge state.

        -vspan *(restart|continue)*: Vertical merge state.

        -vAlign *(top|center|bottom|both)*: Vertical alignment of cell
        content.

        -textDirection *direction*: Text direction within the cell.

        -shading *keyValueList*: Cell shading pattern. Keys: type, color,
        fill (same as paragraph shading). The options -shading and
        -background are mutually exclusive.

        -background *RRGGBB*: Shorthand for a solid background fill color.
        The options -shading and -background are mutually exclusive.

        -tcFitText *onOffValue*: Shrink text to fit cell width.

  Cell border options (-topBorder, -leftBorder, -bottomBorder, -rightBorder, -tl2brBorder, -tr2blBorder) and cell margin options are also accepted.

tablerow ?-option value …? creatingScript

  Creates a table row within a table script and returns the object id of the created table row. The creatingScript creates cells via tablecell calls.

  Options:

        -rowHeight *keyValueList*: Row height. Keys: value (measurement),
        hRule (auto|exact|atLeast).

        -headerrow *onOffValue*: Mark this row as a header row that repeats
        on each page.

        -cantSplit *onOffValue*: Prevent the row from splitting across
        pages.

        -align *(center|end|left|right|start)*: Row alignment (overrides
        table alignment).

        -cellSpacing *keyValueList*: Cell spacing within the row. Keys:
        type, value.

        -wBefore, -wAfter *keyValueList*: Width before/after the row
        (for indented rows). Keys: type, value.

textbox ?-option value …? creatingScript

  Creates an anchored text box at the current position and returns the object id of the created text box. The creatingScript creates the text box content (paragraphs, tables, etc.) inside the box.

  Options:

         -name *string*: Display name for the text box shape. Auto-generated
         if omitted.

         -dimension *keyValueList*: Required. Sets the text box size. Keys:
         width (EMU), height (EMU).

         -bodyAtts *keyValueList*: Text body attributes. Keys: wrap
         (none|square), numCol (integer), and other wps:bodyPr attributes.

  Anchor positioning options (-anchorData, -positionH, -alignH, -posOffsetH, -positionV, -alignV, -posOffsetV, -wrapMode, -wrapData, -bwMode) are also accepted — see image anchor options.

url text url ?-option value …?

  Append text to the current paragrah and make that text an hypherlink to uri. The option/value pairs control the appearance of the text within the paragraph. See CHARACTER OPTIONS for the valid options and the type of their value.

write ?filename?

  Writes the object as WordprocessingML docx file to filename. If the argument is omitted then document.docx will be used. If the filename does not have a suffix, then the suffix .docx will be appended.

writepart part filename

  Writes a single XML part from the docx object to filename. Raises an error if the part does not exist in the object.

xpath xpath ?part? ?selectNodes options?

  An alias for the method selectNodes. See there for the meaning of the arguments.

xmlparts ?pattern?

  Returns the paths of the xml parts of the docx object. If the optional argument pattern is given only the xml parts of the docx docx object which match the pattern using glob style matching are returned.

# CHARACTER OPTIONS

-bold onOffValue

-color auto|RRGGBB hex value

-cstyle styleRef

-dstrike onOffValue

-emboss onOffValue

-font font familiy name

-fontsize measure

If the value has no unit the integer means twentieths of a point.

-highlight (black|blue|cyan|green|magenta|red|yellow|white|darkBlue|darkCyan|darkGreen|darkMagenta|darkRed|darkYellow|darkGray|lightGray|none)

-italic onOffValue

-noProof onOffValue

-rtl onOffValue

-strike onOffValue

Toggles strikethrough on the text.

-underline kind

The allowed kind values are:

    single
    words
    double
    thick
    dotted
    dottedHeavy
    dash
    dashedHeavy
    dashLong
    dashLongHeavy
    dotDash
    dashDotHeavy
    dotDotDash
    dashDotDotHeavy
    wave
    wavyHeavy
    wavyDouble
    none

-verticalAlign *(baseline|superscript|subscript)

# PARAGRAPH OPTIONS

-align kind

The allowed kind values are:

    start
    center
    end
    both
    mediumKashida
    distribute
    numTab
    highKashida
    lowKashida
    thaiDistribute
    left
    right

-background RRGGBB hex value

Sets a solid background fill color on the paragraph. This is a shorthand for `-shading {type clear fill RRGGBB}`.

-bidi onOffValue

Right-to-left paragraph direction.

-indentation keyValueList

Sets the paragraph indentation. The accepted keys are:

    start           Left/start indentation (measurement).
    startChars      Left/start indentation in character units.
    end             Right/end indentation (measurement).
    endChars        Right/end indentation in character units.
    firstLine       First line additional indent (measurement).
    firstLineChars  First line indent in character units.
    hanging         Hanging indent (measurement).
    hangingChars    Hanging indent in character units.

-keepLines onOffValue

Keep all lines of the paragraph on the same page.

-keepNext onOffValue

Keep the paragraph on the same page as the next paragraph.

-level integer

Numbering level (used with -numberingStyle). Zero-based.

-numberingStyle integer

Numbering definition ID to apply to this paragraph.

-pageBreakBefore onOffValue

Start the paragraph on a new page.

-shading keyValueList

Sets the paragraph shading pattern. The accepted keys are:

    type    Shading pattern (required). Common values: clear, solid,
            horzStripe, vertStripe, diagStripe, diagCross, pct10,
            pct20, pct25, pct50, pct75, etc.
    color   Foreground pattern color (RRGGBB hex or "auto").
    fill    Background fill color (RRGGBB hex or "auto").

Example: `-shading {type clear fill FFFF00}` for a yellow background.

-spacing keyValueList

The value to the option must be a Tcl list of keyword measurement pairs and defines the space before, after and between the lines of the paragraph. The space values are given as measurement

The accepted keys are:

    after       Space after the paragraph.
    before      Space before the paragraph.
    line        Line spacing within the paragraph.
    lineRule    How "line" is interpreted: "auto" (default, value
                is in 240ths of a line), "exact" (value is in
                twips), or "atLeast" (minimum, value is in twips).

-suppressLineNumbers onOffValue

Suppress line numbers for this paragraph.

-textframe keyValueList

Configures the paragraph as a text frame. Keys: width, height, wrap, vAnchor, hAnchor, xAlign, yAlign, dropCap, lines, vSpace, hSpace, hrule, anchorLock.

-widowControl onOffValue

Enable widow/orphan control for this paragraph.

# OPTION VALUE TYPES

Several option values share the same value types. This types are:

## MEASUREMENT

A measurement is given either as integer value without unit or as integer immediately followed by a unit. If the value is just a number then what distance is specified by the number depends on the option and is documented with the option. The allowed units are:

    mm
         Millimeter
    cm
         Centimeter
    in
         Inch (1in = 2.54cm)
    pt
         Point (1pt = 1/72in)
    pc
         Pica (1pc = 12pt)
    pi
         The same as pc: Pica (1pi = 12pt)

# DEPENDENCIES

    Tcl >= 8.6.7
    tdom >= 0.9.6

Reading an existing .docx file (as template or for imports) uses the zlib command built into Tcl and needs no additional package. Only if an archive cannot be handled by the built-in reader, one of the optional fallback backends is used: the Tcl 9 zipfs, tcllib’s zipfile::decode or tclvfs vfs::zip >= 1.0.4.