'\" t
.\" Automatically generated by Pandoc 3.10
.\"
.TH "ooxml\-docx" "n" "" "" "ooxml user documentation"
.SH NAME
::ooxml::docx \- Create ECMA\-376 Office Open XML writer documents (the
\&.docx format)
.SH SYNOPSIS
.IP
.EX
package require ooxml::docx
::ooxml::docx::docx new *?\-option value ...?* ?docx\-file?
.EE
.SH DESCRIPTION
The command \f[I]::ooxml::docx\f[R] creates a new docx object.
.PP
Without the optional file argument the object represents an almost
minimal empty document.
.PP
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.
.PP
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.
.PP
A simple \(lqHello, World\(rq example is:
.IP
.EX
set docx [ooxml::docx::docx new]
$docx paragraph \(dqHello, World!\(dq
$docx write hello.docx
$docx destroy
.EE
.PP
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.
.PP
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.
.PP
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.
.PP
Content to the document is added top down.
.PP
The created docx object commands currently support the following
methods:
.TP
\f[B]append\f[R] \f[I]text\f[R] \f[I]?\-option value \&...?\f[R]
Appends \f[I]text\f[R] to the last paragraph of the content of the
document.
The option/value pairs control the appearance of the \f[I]text\f[R]
within the paragraph.
See CHARACTER OPTIONS for the valid options and the type of their value.
.TP
\f[B]appendTo\f[R] \f[I]objectId\f[R] \f[I]creatingScript\f[R]
This method appends content to an already created table, table row table
cell, footer, header, footnote, endnote, comment or textbox.
The \f[I]objectId\f[R] has to be the id returned by the method which
created the object.
The \f[I]creatingScript\f[R] is evaluated and creates the appended
object content.
The resulting document is the same as if the \f[I]creatingScript\f[R]
would have been appended to the \f[I]creatingScript\f[R] of the method
which created the object.
.TP
\f[B]br\f[R] \f[I]?n?\f[R]
Inserts a line break into the current paragraph.
The optional argument \f[I]n\f[R] (default 1) specifies the number of
breaks to insert.
.TP
\f[B]comment\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
This method creates a comment to the current point in the document with
comment content created by the \f[I]creatingScript\f[R] 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.
.RS
.PP
The allowed options are
.IP
.EX
  \-author string

  \-date <xsd datetime>

  \-initials string
.EE
.RE
.TP
\f[B]commentrangeend\f[R] \f[I]id\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
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 \f[I]creatingScript\f[R] and returns the object id of the created
comment.
The \f[I]id\f[R] argument must be the id returned by the corresponding
\f[I]commentrangestart\f[R] call.
For the allowed options see the method \f[I]comment\f[R].
.TP
\f[B]commentrangestart\f[R] ?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 \f[I]resultvar\f[R], if the optional argument
is given.
.TP
\f[B]destroy\f[R]
Destroys the docx object and releases all associated DOM documents and
resources.
Inherited from TclOO.
.TP
\f[B]configure\f[R] \f[I]?\-option value \&...?\f[R]
Set certain document properties.
The recognized options are:
.RS
.IP
.EX
  \-category

  \-contentStatus

  \-created

  \-creator

  \-description

  \-identifier

  \-ignorable prefixList: Set the MC Ignorable prefixes (e.g. \(dqw14 wp14\(dq).

  \-keywords

  \-language

  \-lastModifiedBy

  \-lastPrinted

  \-modified

  \-revision

  \-subject

  \-title

  \-version
.EE
.RE
.TP
\f[B]endnote\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates an endnote with content produced by \f[I]creatingScript\f[R] 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:
.RS
.PP
\-refstyle \f[I]styleRef\f[R]: Character style applied to the reference
mark.
The value may be either the internal style ID (\f[I]w:styleId\f[R]) or
the display name (\f[I]w:name\f[R]).
.PP
The other \f[I]\-option value\f[R] pairs allows formatting of the
(whole) endnote value.
See CHARACTER OPTIONS for the valid options and the type of their value.
.RE
.TP
\f[B]field\f[R] \f[I]field\-type\f[R] ?\f[I]switches\f[R]? \f[I]?\-option value \&...?\f[R]
Appends the given field type to the last paragraph.
Recognized field types are
.RS
.IP
.EX
      AUTHOR
      CREATEDATE
      DATE
      FILESIZE
      PAGE
      NUMPAGES
      SAVEDATE
      SECTION
      TIME
      TITLE
      USERNAME
.EE
.PP
If the optional argument \f[I]switches\f[R] is given its value will be
appended as the field switches to the field\-type name.
The following optional \f[I]\-option value\f[R] pairs allows formatting
of the (whole) inserted field value.
See CHARACTER OPTIONS for the valid options and the type of their value.
.RE
.TP
\f[B]footnote\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates a footnote with content produced by \f[I]creatingScript\f[R] 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:
.RS
.IP
.EX
  \-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*).
.EE
.RE
.PP
\f[B]footer\f[R] \f[I]creatingScript\f[R] ?returnvar?
?objectIdvar?
\f[B]header\f[R] \f[I]creatingScript\f[R] ?returnvar?
?objectIdvar?
.PP
: 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 \f[I]returnvar\f[R].
This is the id to refer to the footer or header to be used with the
options \f[I]\-defaultHeader\f[R], \f[I]\-firstHeader\f[R],
\f[I]\-evenHeader\f[R], \f[I]\-defaultFooter\f[R],
\f[I]\-firstFooter\f[R] and \f[I]\-evenFooter\f[R] of the methods
\f[I]pagesetup\f[R] and \f[I]sectionstart\f[R].
The object id of the created footer or header is stored in the
\f[I]objectIdvar\f[R], if given.
This is the id to use with the method \f[I]appendTo\f[R].
.TP
\f[B]image\f[R] \f[I]file\f[R] \f[I]anchor|inline\f[R] \f[I]?\-option value \&...?\f[R]
An \f[I]inline\f[R] image is part of the text, like a character (and
therefore may change the line height).
An \f[I]anchor\f[R] 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.
.RS
.PP
Both types of images share the following options:
.IP
.EX
 \-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 \(dqauto\(dq).
.EE
.PP
Anchor images additionally accept:
.IP
.EX
 \-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 \(dqcolumn\(dq.

 \-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 \(dqparagraph\(dq.

 \-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
 \(dqnone\(dq).

 \-wrapData *keyValueList*: Wrap attributes (only with \-wrapMode
 square). Keys: wrapText, distT, distB, distL, distR.
.EE
.RE
.TP
\f[B]import\f[R] \f[I]part\f[R] \f[I]docx\f[R]
Imports the given \f[I]part\f[R] from the file \f[I]docx\f[R] into the
docx object, replacing what the object had for that part of the docx zip
archive.
.RS
.PP
The shortcut \(lqstyles\(rq may be used for word/styles.xml and
\(lqnumbering\(rq for word/numbering.xml.
.RE
.TP
\f[B]jumpto\f[R] \f[I]text\f[R] \f[I]markid\f[R] \f[I]?\-option value \&...?\f[R]
Appends the text \f[I]text\f[R] 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 \f[I]markid\f[R] inside the document.
.RS
.PP
The option/value pairs control locally the appearance of the
\f[I]text\f[R] within the paragraph.
See CHARACTER OPTIONS for the valid options and the type of their
argument.
.RE
.TP
\f[B]mark\f[R] \f[I]markid\f[R]
Sets the mark \f[I]markid\f[R] at the end of the last paragraph.
.TP
\f[B]markstart\f[R] \f[I]name\f[R]
Starts a named bookmark span at the current position.
The bookmark name must be unique within the document.
Use \f[B]markend\f[R] to close the span.
.TP
\f[B]markend\f[R] \f[I]name\f[R]
Ends the bookmark span previously opened by \f[B]markstart\f[R] with the
same \f[I]name\f[R].
.TP
\f[B]math\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates a math zone.
The \f[I]creatingScript\f[R] creates the math content using the math
methods described below.
By default the math is inline within the current paragraph.
Options:
.RS
.IP
.EX
     \-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.
.EE
.PP
Inside the \f[I]creatingScript\f[R], the following math methods are
available.
All math methods must be called from within the \f[I]creatingScript\f[R]
of a \f[B]math\f[R] call; calling them outside a math zone raises a Tcl
error.
Invalid option values also raise a Tcl error.
.RE
.TP
\f[B]mrun\f[R] \f[I]?\-option value \&...?\f[R] \f[I]text\f[R]
Creates a math run (text within a math zone).
Options:
.RS
.IP
.EX
  \-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.
.EE
.RE
.TP
\f[B]mfrac\f[R] \f[I]?\-option value \&...?\f[R] \f[I]numeratorScript\f[R] \f[I]denominatorScript\f[R]
Creates a fraction.
The two scripts create the numerator and denominator content.
Options:
.RS
.IP
.EX
     \-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.
.EE
.RE
.TP
\f[B]msub\f[R] \f[I]baseScript\f[R] \f[I]subscriptScript\f[R]
Creates a subscript construct.
.TP
\f[B]msup\f[R] \f[I]baseScript\f[R] \f[I]superscriptScript\f[R]
Creates a superscript construct.
.TP
\f[B]msubsup\f[R] \f[I]baseScript\f[R] \f[I]subscriptScript\f[R] \f[I]superscriptScript\f[R]
Creates a simultaneous sub\-superscript construct.
.TP
\f[B]msqrt\f[R] \f[I]radicandScript\f[R]
Creates a square root.
.TP
\f[B]mroot\f[R] \f[I]degreeScript\f[R] \f[I]radicandScript\f[R]
Creates an nth\-root.
The \f[I]degreeScript\f[R] produces the root index (e.g.\ 3 for cube
root) and \f[I]radicandScript\f[R] the expression under the radical.
.TP
\f[B]mnary\f[R] \f[I]?\-option value \&...?\f[R] \f[I]baseScript\f[R]
Creates an n\-ary operator (summation, product, integral, etc.).
Options:
.RS
.IP
.EX
  \-char *string*: The operator character (e.g. \(dq∑\(dq, \(dq∏\(dq, \(dq∫\(dq).

  \-limLoc *(undOvr|subSup)*: Limit placement \(em 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.
.EE
.RE
.TP
\f[B]mfunc\f[R] \f[I]nameScript\f[R] \f[I]argumentScript\f[R]
Creates a function application construct (e.g.\ sin, cos, lim).
.TP
\f[B]mlimlow\f[R] \f[I]baseScript\f[R] \f[I]lowerLimitScript\f[R]
Creates a lower\-limit construct (limit below the base).
.TP
\f[B]mlimupp\f[R] \f[I]baseScript\f[R] \f[I]upperLimitScript\f[R]
Creates an upper\-limit construct (limit above the base).
.TP
\f[B]maccent\f[R] \f[I]?\-option value \&...?\f[R] \f[I]baseScript\f[R]
Creates an accent construct \(em places a diacritical mark (hat, tilde,
dot, vector arrow, etc.)
above the base expression.
.RS
.IP
.EX
  \-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).
.EE
.RE
.TP
\f[B]mbar\f[R] \f[I]?\-option value \&...?\f[R] \f[I]baseScript\f[R]
Creates an overline or underline bar above or below the base.
.RS
.IP
.EX
  \-pos *top|bot*: Position of the bar (default \(dqtop\(dq = overline).
.EE
.RE
.TP
\f[B]mdelim\f[R] \f[I]?\-option value \&...?\f[R] \f[I]script\f[R]
Creates a delimiter construct \(em wraps content in matching delimiters
such as parentheses, brackets, braces, absolute\-value bars, norms,
floor/ceiling symbols, etc.
.RS
.PP
The \f[I]script\f[R] 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
\f[B]mdelimarg\f[R] within the script.
.IP
.EX
  \-begChr *string*: Opening delimiter character (default \(dq(\(dq)
  \-endChr *string*: Closing delimiter character (default \(dq)\(dq)
  \-sepChr *string*: Separator character between arguments (default \(dq|\(dq)
  \-grow *onOffValue*: Delimiters grow to match content height
  \-shp *centered|match*: Delimiter shape
.EE
.RE
.TP
\f[B]mdelimarg\f[R] \f[I]script\f[R]
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.
.TP
\f[B]mgroupchr\f[R] \f[I]?\-option value \&...?\f[R] \f[I]baseScript\f[R]
Creates a grouping character construct \(em an underbrace, overbrace, or
similar character that spans the base expression.
Commonly used to label parts of an equation.
.RS
.IP
.EX
  \-char *string*: The grouping character (default U+23DF = ⏟ bottom
  curly bracket). Use U+23DE for overbrace (⏞).
  \-pos *top|bot*: Position of the character (default \(dqbot\(dq)
  \-vertJc *top|bot*: Vertical justification of the base relative to
  the grouping character
.EE
.RE
.TP
\f[B]mmatrix\f[R] \f[I]?\-option value \&...?\f[R] \f[I]rowScripts\f[R]
Creates a matrix.
The \f[I]rowScripts\f[R] argument is a list; each element is a script
that creates cells via \f[B]mmatcell\f[R] calls.
Wrap in \f[B]mdelim\f[R] for bracket/parenthesis notation.
.RS
.IP
.EX
  \-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\(en255)
.EE
.RE
.TP
\f[B]mmatcell\f[R] \f[I]script\f[R]
Creates a matrix cell (m:e child) inside a matrix row.
Each call wraps its script content in a separate m:e element.
.TP
\f[B]numbering\f[R] \f[I]subcmd\f[R] \f[I]args\f[R]
Manages numbering definitions (lists, outlines).
.RS
.PP
The supported subcommands are:
.PP
\f[B]abstractNum\f[R] \f[I]id\f[R] \f[I]levelDefinitions\f[R]: Creates
an abstract numbering definition with the given integer \f[I]id\f[R].
The \f[I]levelDefinitions\f[R] argument is a list; each element defines
one level using option/value pairs:
.IP
.EX
  \-numberFormat *format*: Numbering format (decimal, upperRoman,
  lowerRoman, upperLetter, lowerLetter, bullet, etc.)
  \-levelText *string*: Level text template (e.g. \(dq%1.\(dq or \(dq%1.%2\(dq)
  \-align *alignment*: Number alignment (start, center, end, etc.)
  \-start *integer*: Starting number (default 1)
.EE
.PP
Paragraph and character options may also be given per level to style the
number and the paragraph.
.PP
A corresponding w:num entry is automatically created with the same numId
as the abstractNumId.
.PP
Example:
.IP
.EX
   $doc numbering abstractNum 0 {
       {\-numberFormat decimal \-levelText \(dq%1.\(dq \-align start}
       {\-numberFormat lowerLetter \-levelText \(dq%2)\(dq \-align start}
   }
.EE
.PP
\f[B]abstractNumIds\f[R]: Returns a sorted list of all abstractNum IDs.
.PP
\f[B]delete\f[R] \f[I]type\f[R] \f[I]id\f[R]: Deletes a numbering
definition.
\f[I]type\f[R] is either \f[B]abstractNum\f[R] or \f[B]num\f[R];
\f[I]id\f[R] is the integer ID.
.RE
.TP
\f[B]pagebreak\f[R]
Appends a page break to the document.
.TP
\f[B]pagesetup\f[R] \f[I]?\-option value \&...?\f[R]
The allowed options are:
.RS
.IP
.EX
  \-margins keyValueList

  \-paperSource keyValueList

  \-sizeAndOrientation keyValueList

  \-defaultHeader id
  \-defaultFooter id
  \-firstHeader id
  \-firstFooter id
  \-evenHeader id
  \-evenFooter id
.EE
.PP
The last block of options set the respectively header or footer.
The id has to be returned from a header or footer method call.
.IP
.EX
   \-border

   \-pageNumbering

  \-sectionType *(continuous|evenPage|nextColumn|nextPage|oddPage)*
.EE
.PP
Specifies the type of the current section break.
The default is \f[I]nextPage\f[R].
Use \f[I]continuous\f[R] to start a new section on the same page
(e.g.\ for switching between single and multi\-column layout).
.IP
.EX
  \-docGrid *keyValueList*
.EE
.PP
Configures the document grid for the section, controlling line pitch and
character spacing for CJK and other layout needs.
The accepted keys are:
.IP
.EX
  type        Grid type: \(dqdefault\(dq, \(dqlines\(dq, \(dqlinesAndChars\(dq,
              or \(dqsnapToChars\(dq.
  linePitch   Distance between lines (integer, in twips).
  charSpace   Additional character pitch (integer, in 4096ths
              of a point).

  \-vAlign *(top|center|bottom|both)*
.EE
.PP
Vertical alignment of text on the page.
The value \f[I]both\f[R] distributes text evenly between the top and
bottom margins (justified).
.RE
.TP
\f[B]paragraph\f[R] \f[I]text\f[R] \f[I]?\-pstyle style? ?\-cstyle style? ?\-option value \&...?\f[R]
Appends \f[I]text\f[R] as paragraph to the content of the document.
If the \f[I]\-pstyle\f[R] option is given, the referenced paragraph
style will be used.
If the \f[I]\-cstyle\f[R] option is given the referenced character style
will be used.
Style values may be given either as the internal style ID
(\f[I]w:styleId\f[R]) or as the display name (\f[I]w:name\f[R]).
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.
.TP
\f[B]readpart\f[R] \f[I]part\f[R] \f[I]filename\f[R]
Replaces the named XML \f[I]part\f[R] in the docx object with the
contents of \f[I]filename\f[R].
The file is parsed as XML and replaces the in\-memory DOM for that part.
Example:
.RS
.IP
.EX
$doc readpart word/settings.xml mysettings.xml
.EE
.RE
.TP
\f[B]replace\f[R] \f[I]from\f[R] \f[I]to\f[R] \f[I]?part_list?\f[R]
Replaces every \f[I]from\f[R] substring in any text with \f[I]to\f[R],
Only uniformly styled text is replaced (if \f[I]from\f[R] spans over
more than one text part it will not be recognized).
Without the optional \f[I]part list\f[R] 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 \f[I]part list\f[R] argument which are currently
not exists in the object will be silently ignored.
.TP
\f[B]sectionend\f[R]
Ends the current section, emitting the stored section properties as a
w:sectPr inside the last paragraph.
Must be preceded by a \f[B]sectionstart\f[R] call; raises an error
otherwise.
.TP
\f[B]sectionstart\f[R] \f[I]?\-option value \&...?\f[R]
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 \f[B]pagesetup\f[R]: \-margins,
\-sizeAndOrientation, \-sectionType, \-docGrid, \-vAlign, \-border,
\-pageNumbering, header/footer references, etc.
.TP
\f[B]settings\f[R] \f[I]?\-option value \&...?\f[R]
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.
.RS
.PP
Special option:
.IP
.EX
      \-reset *onOffValue*: If on, resets all settings to defaults before
      applying the remaining options.
.EE
.PP
Commonly used settings:
.IP
.EX
     \-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.
.EE
.PP
Many more settings are available.
On/off settings use \f[I]onOffValue\f[R].
Refer to the property table in the source for the complete list.
.RE
.TP
\f[B]selectNodes\f[R] \f[I]xpath\f[R] ?\f[I]part\f[R]? \f[I]?selectNodes options?\f[R]
Returns the result of the \f[I]xpath\f[R] 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 \f[I]part\f[R] argument is given the context node of the
expression will be the document element of the docx part identified by
this argument.
If \f[I]part\f[R] 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 \f[I]selectNodes options\f[R] are routed throw.
.RS
.PP
All documents accessible by this have the following prefix namespace
mappings predefined:
.PP
.TS
tab(@);
l l.
T{
Prefix
T}@T{
Namespace
T}
_
T{
a
T}@T{
http://schemas.openxmlformats.org/drawingml/2006/main|
T}
T{
ct
T}@T{
http://schemas.openxmlformats.org/package/2006/content\-types|
T}
T{
m
T}@T{
http://schemas.openxmlformats.org/officeDocument/2006/math|
T}
T{
mc
T}@T{
http://schemas.openxmlformats.org/markup\-compatibility/2006|
T}
T{
o
T}@T{
urn:schemas\-microsoft\-com:office:office|
T}
T{
pic
T}@T{
http://schemas.openxmlformats.org/drawingml/2006/picture|
T}
T{
r
T}@T{
http://schemas.openxmlformats.org/officeDocument/2006/relationships|
T}
T{
rel
T}@T{
http://schemas.openxmlformats.org/package/2006/relationships|
T}
T{
sl
T}@T{
http://schemas.openxmlformats.org/schemaLibrary/2006/main|
T}
T{
v
T}@T{
urn:schemas\-microsoft\-com:vml|
T}
T{
w
T}@T{
http://schemas.openxmlformats.org/wordprocessingml/2006/main|
T}
T{
w10
T}@T{
urn:schemas\-microsoft\-com:office:word|
T}
T{
w14
T}@T{
http://schemas.microsoft.com/office/word/2010/wordml|
T}
T{
wp
T}@T{
http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing|
T}
T{
wp14
T}@T{
http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing|
T}
T{
wpg
T}@T{
http://schemas.microsoft.com/office/word/2010/wordprocessingGroup|
T}
T{
wps
T}@T{
http://schemas.microsoft.com/office/word/2010/wordprocessingShape|
T}
.TE
.RE
.TP
\f[B]simplecomment\f[R] \f[I]comment\f[R] \f[I]?\-option value \&...?\f[R]
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
\f[I]comment\f[R].
For the allowed options see the method \f[I]comment\f[R].
Additionally to this options all PARAGRAPH OPTIONS and CHARACTER OPTIONS
are allowed.
If given they are applied to format the comment text.
.TP
\f[B]simplecommentrangeend\f[R] \f[I]id\f[R] \f[I]comment\f[R] \f[I]?\-option value \&...?\f[R]
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 \f[I]comment\f[R] argument.
The \f[I]id\f[R] argument must be the id returned by the corresponding
\f[I]commentrangestart\f[R] call.
For the allowed options see the method \f[I]comment\f[R].
Additionally to this options all PARAGRAPH OPTIONS and CHARACTER OPTIONS
are allowed.
If given they are applied to format the comment text.
.TP
\f[B]simpletable\f[R] \f[I]tabledata\f[R] \f[I]?\-option value \&...?\f[R]
Creates a table from a nested list.
Each element of \f[I]tabledata\f[R] is a row; each element within a row
is a cell\(cqs text content.
.RS
.PP
Example: \f[CR]$doc simpletable {{A1 B1 C1} {A2 B2 C2}}\f[R]
.PP
Options:
.IP
.EX
  \-columnwidths *list*: Column widths (measurements).
  \-firstStyle *styleName*: Character style for the first row.
  \-lastStyle *styleName*: Character style for the last row.
.EE
.PP
Table\-level options (\-style, \-width, \-align, \-layout, \-look,
\-tableBorders, cell margins) are also accepted \(em see
\f[B]table\f[R].
.RE
.TP
\f[B]style\f[R] \f[I]subcommand\f[R] \f[I]args\f[R]
The supported subcommands are:
.RS
.IP
.EX
  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:
.EE
.PP
(Table styles only.)
Conditional formatting for table regions such as firstRow, lastRow,
firstColumn, lastColumn, band1Vert, band1Horz, etc.
.IP
.EX
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
.EE
.RE
.TP
\f[B]tab\f[R] \f[I]?n?\f[R]
Inserts a tab character into the current paragraph.
The optional argument \f[I]n\f[R] (default 1) specifies the number of
tabs to insert.
.TP
\f[B]table\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates a table by defining every row and cell individually by the
\f[I]creatingScript\f[R] and returns the object id of the created table.
The recognized options are:
.RS
.IP
.EX
  \-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
  \(ga\-<position>Border {type <borderType> color <hex> borderwidth <eighthPts> space <pts>}\(ga.

  \-cellMarginTop, \-cellMarginStart, \-cellMarginLeft,
  \-cellMarginBottom, \-cellMarginEnd, \-cellMarginRight:
  Default cell margins. Each takes a *keyValueList* with keys
  type and value.
.EE
.RE
.TP
\f[B]tablecell\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates a table cell within a \f[B]tablerow\f[R] script and returns the
object id of the created table cell.
The \f[I]creatingScript\f[R] creates the cell content (paragraphs,
nested tables, etc.).
.RS
.PP
Options:
.IP
.EX
  \-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.
.EE
.PP
Cell border options (\-topBorder, \-leftBorder, \-bottomBorder,
\-rightBorder, \-tl2brBorder, \-tr2blBorder) and cell margin options are
also accepted.
.RE
.TP
\f[B]tablerow\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates a table row within a \f[B]table\f[R] script and returns the
object id of the created table row.
The \f[I]creatingScript\f[R] creates cells via \f[B]tablecell\f[R]
calls.
.RS
.PP
Options:
.IP
.EX
  \-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.
.EE
.RE
.TP
\f[B]textbox\f[R] \f[I]?\-option value \&...?\f[R] \f[I]creatingScript\f[R]
Creates an anchored text box at the current position and returns the
object id of the created text box.
The \f[I]creatingScript\f[R] creates the text box content (paragraphs,
tables, etc.)
inside the box.
.RS
.PP
Options:
.IP
.EX
   \-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.
.EE
.PP
Anchor positioning options (\-anchorData, \-positionH, \-alignH,
\-posOffsetH, \-positionV, \-alignV, \-posOffsetV, \-wrapMode,
\-wrapData, \-bwMode) are also accepted \(em see \f[B]image\f[R] anchor
options.
.RE
.TP
\f[B]url\f[R] \f[I]text\f[R] \f[I]url\f[R] \f[I]?\-option value \&...?\f[R]
Append \f[I]text\f[R] to the current paragrah and make that text an
hypherlink to \f[I]uri\f[R].
The option/value pairs control the appearance of the \f[I]text\f[R]
within the paragraph.
See CHARACTER OPTIONS for the valid options and the type of their value.
.TP
\f[B]write\f[R] \f[I]?filename?\f[R]
Writes the object as WordprocessingML docx file to \f[I]filename\f[R].
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.
.TP
\f[B]writepart\f[R] \f[I]part\f[R] \f[I]filename\f[R]
Writes a single XML part from the docx object to \f[I]filename\f[R].
Raises an error if the part does not exist in the object.
.TP
\f[B]xpath\f[R] \f[I]xpath\f[R] \f[I]?part?\f[R] \f[I]?selectNodes options?\f[R]
An alias for the method \f[I]selectNodes\f[R].
See there for the meaning of the arguments.
.TP
\f[B]xmlparts\f[R] \f[I]?pattern?\f[R]
Returns the paths of the xml parts of the docx object.
If the optional argument \f[I]pattern\f[R] is given only the xml parts
of the docx docx object which match the \f[I]pattern\f[R] using glob
style matching are returned.
.SH CHARACTER OPTIONS
\f[B]\-bold\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-color\f[R] \f[I]auto|RRGGBB hex value\f[R]
.PP
\f[B]\-cstyle\f[R] \f[I]styleRef\f[R]
.PP
\f[B]\-dstrike\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-emboss\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-font\f[R] \f[I]font familiy name\f[R]
.PP
\f[B]\-fontsize\f[R] \f[I]measure\f[R]
.PP
If the value has no unit the integer means twentieths of a point.
.PP
\f[B]\-highlight\f[R]
(black|blue|cyan|green|magenta|red|yellow|white|darkBlue|darkCyan|darkGreen|darkMagenta|darkRed|darkYellow|darkGray|lightGray|none)
.PP
\f[B]\-italic\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-noProof\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-rtl\f[R] \f[I]onOffValue\f[R]
.PP
\f[B]\-strike\f[R] \f[I]onOffValue\f[R]
.PP
Toggles strikethrough on the text.
.PP
\f[B]\-underline\f[R] \f[I]kind\f[R]
.PP
The allowed \f[I]kind\f[R] values are:
.IP
.EX
single
words
double
thick
dotted
dottedHeavy
dash
dashedHeavy
dashLong
dashLongHeavy
dotDash
dashDotHeavy
dotDotDash
dashDotDotHeavy
wave
wavyHeavy
wavyDouble
none
.EE
.PP
\f[B]\-verticalAlign\f[R] *(baseline|superscript|subscript)
.SH PARAGRAPH OPTIONS
\f[B]\-align\f[R] \f[I]kind\f[R]
.PP
The allowed \f[I]kind\f[R] values are:
.IP
.EX
start
center
end
both
mediumKashida
distribute
numTab
highKashida
lowKashida
thaiDistribute
left
right
.EE
.PP
\f[B]\-background\f[R] \f[I]RRGGBB hex value\f[R]
.PP
Sets a solid background fill color on the paragraph.
This is a shorthand for \f[CR]\-shading {type clear fill RRGGBB}\f[R].
.PP
\f[B]\-bidi\f[R] \f[I]onOffValue\f[R]
.PP
Right\-to\-left paragraph direction.
.PP
\f[B]\-indentation\f[R] \f[I]keyValueList\f[R]
.PP
Sets the paragraph indentation.
The accepted keys are:
.IP
.EX
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.
.EE
.PP
\f[B]\-keepLines\f[R] \f[I]onOffValue\f[R]
.PP
Keep all lines of the paragraph on the same page.
.PP
\f[B]\-keepNext\f[R] \f[I]onOffValue\f[R]
.PP
Keep the paragraph on the same page as the next paragraph.
.PP
\f[B]\-level\f[R] \f[I]integer\f[R]
.PP
Numbering level (used with \f[B]\-numberingStyle\f[R]).
Zero\-based.
.PP
\f[B]\-numberingStyle\f[R] \f[I]integer\f[R]
.PP
Numbering definition ID to apply to this paragraph.
.PP
\f[B]\-pageBreakBefore\f[R] \f[I]onOffValue\f[R]
.PP
Start the paragraph on a new page.
.PP
\f[B]\-shading\f[R] \f[I]keyValueList\f[R]
.PP
Sets the paragraph shading pattern.
The accepted keys are:
.IP
.EX
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 \(dqauto\(dq).
fill    Background fill color (RRGGBB hex or \(dqauto\(dq).
.EE
.PP
Example: \f[CR]\-shading {type clear fill FFFF00}\f[R] for a yellow
background.
.PP
\f[B]\-spacing\f[R] \f[I]keyValueList\f[R]
.PP
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
.PP
The accepted keys are:
.IP
.EX
after       Space after the paragraph.
before      Space before the paragraph.
line        Line spacing within the paragraph.
lineRule    How \(dqline\(dq is interpreted: \(dqauto\(dq (default, value
            is in 240ths of a line), \(dqexact\(dq (value is in
            twips), or \(dqatLeast\(dq (minimum, value is in twips).
.EE
.PP
\f[B]\-suppressLineNumbers\f[R] \f[I]onOffValue\f[R]
.PP
Suppress line numbers for this paragraph.
.PP
\f[B]\-textframe\f[R] \f[I]keyValueList\f[R]
.PP
Configures the paragraph as a text frame.
Keys: width, height, wrap, vAnchor, hAnchor, xAlign, yAlign, dropCap,
lines, vSpace, hSpace, hrule, anchorLock.
.PP
\f[B]\-widowControl\f[R] \f[I]onOffValue\f[R]
.PP
Enable widow/orphan control for this paragraph.
.SH OPTION VALUE TYPES
Several option values share the same value types.
This types are:
.SS 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:
.IP
.EX
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)
.EE
.SH DEPENDENCIES
.IP
.EX
Tcl >= 8.6.7
tdom >= 0.9.6
.EE
.PP
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\(cqs
zipfile::decode or tclvfs vfs::zip >= 1.0.4.
