Why these helpers exist | Absolute markers: firstRow() and lastRow() | Run boundaries: firstOf() and lastOf() | Beat and number: everyNth() and rowNumber() | Periodic runs: firstOfBlock() | Combinations: where the helpers earn their keep | 1. Footnote markers once per group: firstOf() + c_glue() | 2. Block headers from a hidden column: firstOf() + c_addrow() | 3. Subtotals assembled from the data: lastOf() + c_glue() + c_style() | 4. Gaps between blocks, but never at the edge: lastOf() + !lastRow() | 5. Page breaks on block boundaries: firstOf() + rowNumber() + c_pageBreak() | All of them at once | Honest edges | Reference table

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 — Concentration-time figure with a parameter table | Data | Variation: let them split across pages | Example 7 — Gap between Spanning Header Lines | Example 8 — Risk-difference forest figure | Example 9 — Two related tables on one page | Example 10 — Laboratory safety with threshold highlighting | Final notes

Overview | Category and prerequisites | Core Concept: Lazy Evaluation | Why Lazy Evaluation? | 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 | 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 | One condition block per rule | Use Vectorized Conditions | Tighten Conditions, Do Not Split Tables | Style Consolidation | Debugging and Inspection | Viewing Captured Actions | Testing Conditions Manually | Incremental Building | Common Patterns Library | Pattern 1: Alternating Row Colors | Pattern 2: Group Separator Bands with Cell Merging | Pattern 3: Conditional Highlighting with Thresholds | Pattern 4: Summary Rows with Totals | Limitations and Workarounds | Limitation 1: Conditions must be row-wise | 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 | 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. Can I use aggregate logic such as mean(x) inside a compute_cols() condition? | 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? | 13. Why does firstOf() mark more rows than I expected? | Rendering, replay, and reproducibility | 14. What is the practical difference between write_doc(), | 15. When do I need a persistent metaPath instead of tempdir()? | 16. Can I delete the original figure file after saving a report? | 17. Why did different sections of one report use different templates? | 18. How do I force one template across every section? | TOC and report assembly | 19. Why does a Table of Contents not appear even though I asked for one? | 20. Why is the TOC still just a placeholder when I open the DOCX? | 21. Can create_report() accept a named list of specs built in a loop? | Practical column and action recipes | 22. How do I define several display columns in one place? | 23. How do I use NA to skip one column inside a batch define_cols() call? | 24. How do I hide a helper column but still use it to drive formatting? | 25. How do I turn a hidden grouping column into a stub header? | 26. How do I insert subtotals from a hidden total column? | 27. How do I apply one condition to several visible columns at once? | 28. How do I combine font and background styles for one rule? | 29. How do I give columns a base style and still add row-level | 30. How do I build a total line by combining c_merge(), c_clear(), | 31. How do I apply more than one action to the same condition without | 32. How do I build a two-level stub with one hidden column and two style rules? | 33. Can I combine multiple actions of the same or different types, and how do they work together? | 34. 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() | 35. My figure looks fine in LibreOffice but text is cropped/reskinned in MS Word — why? | 36. How do I switch between continuous sections, repeating/not repeating headers, and row-break behavior across pages? | Metadata workflows: replay, combine, and validation | 37. How do I replay a document from stored metadata without re-running R code? | 38. How do I combine multiple documents into a single DOCX with a Table of Contents? | 39. How do I filter and combine only the latest versions of documents? | 40. How do I match saved metadata with actual DOCX files for QC validation? | 41. How do I store metadata persistently for regulatory validation? | 42. How do I clean up obsolete metadata files while keeping the latest versions?

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: Apply conditional row actions (compute_cols) | Step 7: Combine specs into a report | Passing a named list of specs | 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_set_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 | Column labels — labelStyleRef in define_cols() | Column values — valueStyleRef in define_cols() | Spanning headers — labelStyleRef in add_span_header() | 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) | Length units by parameter family | 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

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 | Width Floors and the Unlocked Reserve | Space Constraint Validation | Using minColWidth | 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: A width shifts by more than a tenth of a percent after recalculation | 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 | Overview | Key Features | Core Concepts | Rule Structure | Data Structure | Result Structure | Usage Examples | Complete Example | Example data: | Validation rules | Mode Comparison | When to Use Which? | Performance Tips | Error Message Design | Advanced Usage | Categorizing Violations | Generating Summary Reports | HTML Check Report | XLSX Export | Tracking Changes Across Runs | Visualizing Validation Results | Common Patterns and Recipes | Range Checks | Presence Checks | Format Validation | Conditional Checks | Reference Data Checks | Group-Specific Validation | Best Practices | Conclusion | Key Benefits | Final Thoughts

Cheat sheet | Row matching strategies | OUT* outputs | SYSINFO bitmask | Things ksCompare does not try to replicate

A first comparison | What's inside cmp? | Triage helpers | Tolerances | Options | Renamed columns | Reading files directly | Duplicate keys | Next steps

HTML | Smart sampling | Group by key | Excel

ULP tolerance | Auto-key inference | Diff triage helpers | First / last unequal observations | Duplicate-key strategies | SAS format normalisation | Encoding-safe string comparison | Pattern detection

ks_assert_clean | Tolerating known diffs | CI integration | With pointblank | With arsenal