Three limitations of docx_tools found while writing docs/development/tools/word.md for #111. They are independent; splitting into separate PRs is fine.
1. <!-- widths: … --> assumes a 6.5-inch text width.
block_elements.add_table_to_doc() distributes proportional widths over a hard-coded page_width = 6.5 (US Letter with 1-inch margins), while add_image_to_doc() in the same module reads the real width from doc.sections[-1]. On an A4 template with other margins the absolute column widths are wrong. Fix: compute the usable width from the last section the same way the image code does, falling back to 6.5 only if that fails.
2. add_toc() writes a literal English "Table of Contents" and ignores the style map.
document_features.add_toc() calls doc.add_heading('Table of Contents', level=1), so a template that remaps heading_1 through style_mapping does not apply to it, and non-English documents get an English heading. Fix: accept an optional heading text (new tool parameter toc_title, defaulting to the current string) and render it through style_map.add_mapped_heading().
3. Conditionals and block-level placeholder content are body-only.
conditionals.resolve_conditionals() walks doc.element.body only; {{#if}} markers inside table cells, headers and footers are left as literal text. _replace_placeholders_in_table() passes doc=None, so a placeholder value containing a list or heading is rendered inline in a cell. Both are documented in config/docx_templates.yaml as "not handled yet". If cells are the common case (letterheads built as layout tables), extend _resolve_block_container() to recurse into w:tc elements and allow block insertion inside a cell.
Three limitations of
docx_toolsfound while writingdocs/development/tools/word.mdfor #111. They are independent; splitting into separate PRs is fine.1.
<!-- widths: … -->assumes a 6.5-inch text width.block_elements.add_table_to_doc()distributes proportional widths over a hard-codedpage_width = 6.5(US Letter with 1-inch margins), whileadd_image_to_doc()in the same module reads the real width fromdoc.sections[-1]. On an A4 template with other margins the absolute column widths are wrong. Fix: compute the usable width from the last section the same way the image code does, falling back to 6.5 only if that fails.2.
add_toc()writes a literal English "Table of Contents" and ignores the style map.document_features.add_toc()callsdoc.add_heading('Table of Contents', level=1), so a template that remapsheading_1throughstyle_mappingdoes not apply to it, and non-English documents get an English heading. Fix: accept an optional heading text (new tool parametertoc_title, defaulting to the current string) and render it throughstyle_map.add_mapped_heading().3. Conditionals and block-level placeholder content are body-only.
conditionals.resolve_conditionals()walksdoc.element.bodyonly;{{#if}}markers inside table cells, headers and footers are left as literal text._replace_placeholders_in_table()passesdoc=None, so a placeholder value containing a list or heading is rendered inline in a cell. Both are documented inconfig/docx_templates.yamlas "not handled yet". If cells are the common case (letterheads built as layout tables), extend_resolve_block_container()to recurse intow:tcelements and allow block insertion inside a cell.