Overview | Data and spec behavior | 1. Why does cols not drop the other columns from my data? | 2. Can I hide a column and still use it in compute_cols()? | 3. Why can I not set colWidth on an invisible column? | 4. Why did the other column widths change after I locked one column? | 5. Why did c_glue() not modify a repeated value? | Row actions and layout rules | 6. Why does compute_cols() not like aggregate logic such as mean(x)? | 7. Can I nest c_*() actions inside each other? | 8. Why does every add_span_header() call create a new row of headers? | 9. Can span headers overlap? | 10. How do I keep a small table under a figure on the same page? | 11. When should I use isGrouping, isPaging, and isColBreak? | 12. Why do my footnotes repeat on every page? | Rendering, replay, and reproducibility | 13. What is the practical difference between write_doc(), | 14. When do I need a persistent metaPath instead of tempdir()? | 15. Can I delete the original figure file after saving a report? | 16. Why did different sections of one report use different templates? | 17. How do I force one template across every section? | TOC and report assembly | 18. Why does a Table of Contents not appear even though I asked for one? | 19. Why is the TOC still just a placeholder when I open the DOCX? | 20. Can create_report() accept a named list of specs built in a loop? | Practical column and action recipes | 21. How do I define several display columns in one place? | 22. How do I use NA to skip one column inside a batch define_cols() call? | 23. How do I hide a helper column but still use it to drive formatting? | 24. How do I turn a hidden grouping column into a stub header? | 25. How do I insert subtotals from a hidden total column? | 26. How do I apply one condition to several visible columns at once? | 27. How do I combine font and background styles for one rule? | 28. How do I give columns a base style and still add row-level | 29. How do I build a total line by combining c_merge(), c_clear(), | 30. How do I apply more than one action to the same condition without | 31. How do I build a two-level stub with one hidden column and two style rules? | 32. Can I combine multiple actions of the same or different types, and how do they work together? | 33. How can I create three- or four-level nested text in one column (for example Parameter/Visit/Statistic indentation)? | Pattern A: detail rows only, hierarchy injected with c_addrow() | Pattern B: placeholder hierarchy rows in data, collapsed with c_merge() | 34. How do I switch between continuous sections, repeating/not repeating headers, and row-break behavior across pages? | Metadata workflows: replay, combine, and validation | 35. How do I replay a document from stored metadata without re-running R code? | 36. How do I combine multiple documents into a single DOCX with a Table of Contents? | 37. How do I filter and combine only the latest versions of documents? | 38. How do I match saved metadata with actual DOCX files for QC validation? | 39. How do I store metadata persistently for regulatory validation? | 40. How do I clean up obsolete metadata files while keeping the latest versions?

Purpose | How examples are organised | Session setup (shared across examples) | Example 1 — Demographics table with conditional formatting | Input data | Building the specification | Render | Rendered output | Switching style templates | Example 2 — Demographics table (UTF-8 encoding support) | Code | Example 3 — Adverse Events table with complex spanning headers | Example 4 — Data listing with automatic two-level TOC | Splitting long tables across pages | Split rendered output | Example 5 — Figures and combined multi-spec reports with TOC | Example 6 - Table under the figure | Data | Variation: adding an explicit table title | Troubleshooting: When figure and table don't fit | Example 7 - Gap between Spanning Header Lines

Overview | Category and prerequisites | Core Concept: Lazy Evaluation | Why Lazy Evaluation? | The Three Action Functions | c_style(): Conditional Styling | c_merge(): Conditional Cell Merging | c_addrow(): Conditional Row Insertion | c_pageBreak(): Conditional Page Break | Evaluation Context | The Data Environment | Available Helper Functions | Advanced c_style() Patterns | Multiple Column Styling | Conditional Styling with Complex Logic | Row-Level Styling | Advanced c_merge() Patterns | Multi-Column Grouping Merges | Conditional Display Column Content | Merging with Styling | Advanced c_addrow() Patterns | Summary Rows | Header Rows | c_glue(): Append or Prepend Text to Cell Values | c_clear(): Blank Cell Content in Matching Rows | Combining Actions Together | Performance Tips | 1. Minimize compute_cols() Calls | 2. Use Vectorized Conditions | 3. Pre-Filter Data When Possible | 4. Style Consolidation | Debugging and Inspection | Viewing Captured Actions | Testing Conditions Manually | Incremental Building | Common Patterns Library | Pattern 1: Alternating Row Colors | Pattern 2: Grouped Section Headers with Merging | Pattern 3: Conditional Highlighting with Thresholds | Pattern 4: Summary Rows with Totals | Limitations and Workarounds | Limitation 1: No Direct Aggregate Functions in Conditions | Limitation 2: No Nested c_*() Functions | Limitation 3: Style References Must Exist | Integration with Other ksTFL Features | Using with define_cols() | Using with Invisible Columns | Using in Multi-Spec Reports | Best Practices | Summary

Overview | Core Concepts | Column States | Initial Width Distribution | The autoColWidth Option | Width Locking Workflow | Basic Locking | Multiple Locked Columns | Mixing Relative and Absolute Units | Width Recalculation Algorithm | Example Walkthrough | Drift Correction | Invisible Columns | Making Columns Invisible | Important Constraints | Using Invisible Columns for Logic | Manual Width Management | Disabling Auto-Recalculation | Why Use Manual Mode? | Validation and Constraints | Minimum Width Thresholds | Space Constraint Validation | Adjusting Minimum Width | Common Patterns | Pattern 1: ID Column + Auto Widths | Pattern 2: Fixed-Width Text + Flex Numeric | Pattern 3: All Manual Widths | Pattern 4: Progressive Locking | Troubleshooting | Issue: "Insufficient space for remaining columns" | Issue: Widths don't sum to exactly 100% | Issue: Can't set width for invisible column | Issue: Widths change unexpectedly after define_cols() | Advanced: Width Metadata | Best Practices | Summary

Overview | How Font Discovery Works | Platform-Specific Directories | Target Fonts and Fallbacks | Checking Font Status | Adding Custom Font Directories | Option A: Set before loading | Option B: Set and rescan after loading | Rescanning Fonts | Startup Messages | Interaction with write_doc() | FAQ | Q: I see [fallback] for a font I know is installed. What's wrong? | Q: Can I use custom fonts not in the target list? | Q: Will documents look different on systems without the proprietary fonts? | Q: How do I suppress the startup font warning?

Introduction | How to use this guide | General workflow | High-level pipeline | Anatomy of a TFL spec | Quick 5-minute example | Step 1: Create a TFL_spec | Table spec (from data frame) | Figure spec (from image file) | Text spec (narrative content) | Step 2: Customize columns (define_cols) | Single column | Batch update (multiple columns with single values) | Per-column customization | Step 3: Define styles (add_style) | Step 4: Add spanning headers (span headers) | Step 5: Add titles, footnotes, headers, footers | Step 5b: Page layout and templates | Page size, orientation, and margins | Document templates | Step 6: Combine specs into a report | Passing a named list of specs | Step 7: Apply conditional row actions (compute_cols) | Step 8: Save and Render | Option A: One step with write_doc() (recommended) | Option B: Two steps with save_report() + replay_report() | Step 9: JSON metadata — what it is and why you might need it | What is the metadata folder? | Why use a persistent metaPath? | Managing metadata files | Recommended production setup | Understanding auto-generated values | Column widths (auto-calculation) | Data references (dataRef) | Session-wide defaults with tfl_options | Complete example: From data to document | Key gotchas and tips | RStudio Addins | Styles Editor | Replay Reports | TFL Spec Preview (Selection) | TFL Spec Preview (by name) | Style Atoms Catalog | Next steps | Resources | Quick reference table

1. End-to-End Architecture | 2. C++ Module Map | 2.1 Entry and orchestration | 2.2 Parsing and schema model | 2.3 Layout and table engine | 2.4 Font discovery, measurement, and pagination | 2.5 DOCX emission and packaging | 3. Detailed Rendering Pipeline | 4. Core Data Structures | 5. Text and Font Subsystem | 6. Pagination Internals | 7. Style Resolution Cascade | 8. R/C++ Integration | 9. Build and Dependencies | 10. Practical Trace (One Table Spec)

Category and scope | Workflow overview | 1 — Simple minimal table | 2 — Simple minimal figure | 3 — Simple minimal text (narrative) | 4 — Define columns: single, batch, and parameter recycling | Why define_cols()? | Example 1: Single column definition | Example 2: Batch update with single value (recycling to all columns) | Example 3: Batch update with per-column values (1-to-N mapping) | Example 4: Multiple define_cols() calls (chaining with |>) | 5 — Set document properties (hasData, content width, placement) | 6 — Combine table/figure/text into a single report | Passing a named list of specs | 7 — Column widths: automatic calculation and locking | How automatic column width works | Example 1: Accept auto-calculated widths | Example 2: Lock one column, auto-adjust others | Example 3: Lock multiple columns with relative widths | Example 4: Mixed units (percentages and absolute) | Example 5: Width validation and constraints | 8 — Table with titles, subtitles and footnotes | 9 — span columns (spanning headers) | Why spanning headers? | Example 1: Single spanning header | Example 1b: Using tidyselect helpers with spanning headers | Example 2: Styled spanning headers | Example 3: Paragraph borders on spanning headers | 10 — Styles and f_combine() for combined style references | Why named styles? | Example 1: Define base styles | Example 2: Combine styles with f_combine() | 11 — Conditional row actions with compute_cols() | Example 1: Conditional styling | Example 2: Combining styles in conditional rows | Example 3: Column merging in conditional rows | Example 4: Inserting separator rows | Example 4b: Page break insertion | Example 5: Multiple actions on same rows | 12 — Render to DOCX with write_doc() | What write_doc() does | Example: Assemble and render a multi-spec report | 13 — Session-wide tfl_options: common headers/footers and default body text | Why session options? | Example 1: Set basic session options | Example 2: Override session options in a specific spec | Example 3: Check and reset session options | Final notes

Overview | Category and scope | Styling philosophy and workflow | Why declarative styles? | Best practices workflow | Style primitives (s_* helpers) | s_font() — Font properties | s_paragraph() — Paragraph properties | s_spacing() — Line and paragraph spacing | s_indents() — Indentation | s_table_style() — Table cell properties | s_borders() — Border specifications | s_border() — Individual border line | Paragraph-level borders | Declaring named styles with add_style() | Basic syntax | Example: Define a complete style | Multiple calls merge with last-win strategy | Referencing and applying styles | 1. Column labels — labelStyleRef in define_cols() | 2. Column values — valueStyleRef in define_cols() | 3. Spanning headers — labelStyleRef in add_span_header() | 4. Content — styleRef in add_title(), add_footnote() | Combining styles with f_combine() | Basic usage | When to use f_combine() vs named styles | Combining with per-column mapping | Allowed values (enumerations) | Color names | Font names (common) | Alignment | Border line styles | Vertical alignment | Text orientation | Common styling patterns | Pattern 1: Clinical table headers | Pattern 2: Right-aligned numeric columns | Pattern 3: ID/key columns (bold, wide) | Pattern 4: Multi-level headers with styled stubs | Troubleshooting | Error: "Context error" or "can only be used inside add_style()" | Error: "Invalid parameter" or "Allowed values are..." | Styles not applied after create_report() | Styles looking different in renderer than expected | Advanced notes | Style consolidation in create_report() | Style reference resolution | Built-in style atoms | Complete atom reference | Table-width shrink atoms (tw_*) | See also

Example 1: Basic Discrete Formatting | Example 2: Numeric Range Formatting | Example 3: Decimal Ranges (BMI Categories) | Example 4: Exclusive/Inclusive Bounds | Example 5: Reverse Formatting with Invalue | Example 6: Bidirectional Formatting | Example 7: Parse Multiple Formats from Text | Example 8: Export Formats Back to Text | Example 9: SAS-like PUT/INPUT Functions | Example 10: Data Frame Formatting | Example 11: Missing Value Handling | Example 12: Date/Time Formats (SAS-style) | SAS Date Formats | R Numeric Dates (Days Since 1970-01-01) | Time Formats | Datetime Formats | Custom Date Formats with fnew_date() | Date Formats in Data Frames | Parse Date Formats from Text | Example 13: Multilabel Formats | Overlapping Age Categories | Multilabel with Missing Values | Parse Multilabel from Text | Multilabel Export | Practical Example: Adverse Event Severity Grading | Example 14: Case-Insensitive Matching | Example 15: Expression Labels in Formats | Simple sprintf Expression | Two Extra Arguments (.x1, .x2) | ifelse Expression | Mixed Static and Expression Labels | Expression in .other Fallback | Scalar Recycling | Statistical Table Format with Computed Labels | Example 16: Vectorized Format Names (SAS PUTC-style) | Example 17: Working with Dates and Formats — PUTN | Example 18: Import SAS Formats from CNTLOUT CSV | Use Imported Formats | Apply to Data Frame | Export Imported Format | Selective Import (No Auto-register) | Example 19: Bilingual Format | Example 20: Composite Key Lookup with fputk() | Character lookup (returns character strings) | Native Date lookup (returns Date objects) | Example 21: Consistent Data-Driven Formats with fmap() | Clinical-data example | Same fmap(keys, values) pattern for both types | When to use the default (reversal on) | Summary | Example 22: Date Lookup via fparse() and fputk() | Character date lookup | Native Date lookup | Round-trip: export and re-import | Example 23: Inspecting Range Rules with franges() | Completing a Summary Against Format Labels | Getting Unique Labels from a Format | Example 24: Reverse Range Lookup with fmap_to_ranges() | Example 25: Date Range Bucketing | Fiscal-year bucketing | Define from text with fparse() | LOW / HIGH open-ended bounds | Export and roundtrip | Overlapping buckets with multilabel and fput_all() | Auto-detection of type | Datetime range bucketing | Example 26: Stratified Range Lookup with fputk() | Programmatic construction with fmap_strata() | Text definition with fparse() | Date subtype: per-subject windows | Roundtrip via fexport() / fparse() | Example 27: Plain Range Lookup with fmap_ranges() | Example 28: Composite Key Lookup with NA Components (na_as_string) | Clinical example — LB parameter derivation | The rule of thumb | Example 29: Composite Label Invalue Lookup with finputk() | Basic usage | With NA components (na_as_string = TRUE)