# Document Generation Guide ## Overview OpenBrIM's document generation system enables creation of professional engineering calculation reports, design check documents, and technical documentation. The system uses XML-based document objects that integrate seamlessly with the parametric engine (ParamML), allowing dynamic content generation based on analysis results and design parameters. This guide explains the document generation objects, patterns, and best practices for AI agents who will create comprehensive engineering documentation. **Key Capabilities:** * **Dynamic Content**: Variables and expressions evaluated from parametric model * **Conditional Rendering**: Guards control content visibility based on design conditions * **Rich Formatting**: Tables, sections, text, equations, and visualizations * **CAD Integration**: Embed section drawings and 3D visualizations * **Design Code Integration**: Reference code check calculations and results * **Unit-Aware Output**: Automatic unit conversion and formatting ## Core Concepts ### 1. Document Object Hierarchy Documents are structured as trees of objects: * Root document defines title and metadata * Sections organize content hierarchically * Content objects (tables, text, CAD, etc.) populate sections * All objects follow OpenBrIM object model (`` elements with `N`, `T` attributes) ### 2. Variable Embedding Embed parametric expressions in document content using pipe delimiters: **Syntax:** `|expression|` **Example:** ``` |withunits(fc_Input,'DR_StressU','Stress',3)| ``` The expression is evaluated and the result is inserted into the document. ### 3. Conditional Content Use `Guard` attributes to conditionally include/exclude document objects: **Syntax:** `Guard="expression"` **Example:** ```xml ``` ### 4. Unit Formatting The `withunits()` function formats values with proper units: **Syntax:** `withunits(value, unitSystemParam, unitType, precision)` **Parameters:** * `value`: Numeric value to format * `unitSystemParam`: Unit system reference (e.g., 'DR\_PropU1', 'DR\_StressU') * `unitType`: Type of unit ('Length', 'Force', 'Stress', 'Area', etc.) * `precision`: Decimal places **Example:** ``` |withunits(SectionPropsX.HSection,'DR_PropU1','Length',2)| ``` Result: `24.00 in` (depending on unit system) *** ## Core Document Objects ### 1. Document (Root Object) The root document object defines the overall report structure. **Object Type:** `Document` **Prefix:** `DOC` #### Key Properties | Property | Type | Description | Default | | -------- | ---- | ------------------------ | -------- | | Title | Text | Document title | Required | | N | Text | Document name/identifier | Required | | T | Text | Always "Document" | Required | #### XML Example ```xml ``` *** ### 2. DocSection (Document Section) Hierarchical sections organize content into logical groups. **Object Type:** `DocSection` **Prefix:** `SEC` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | --------------------- | -------- | | Title | Text | Section heading | Required | | Guard | Expression | Conditional rendering | - | #### Nesting Sections can contain subsections to create hierarchy: ```xml ``` #### XML Examples **Simple Section:** ```xml ``` **Conditional Section:** ```xml ``` **Nested Sections:** ```xml ``` *** ### 3. DocTable (Document Table) Tables display tabular data with rows and cells. **Object Type:** `DocTable` **Prefix:** `TABLE` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | --------------------- | -------- | | N | Text | Table identifier | Optional | | Guard | Expression | Conditional rendering | - | #### Structure Tables contain: * `DocRow` objects (rows) * Each row contains `DocCell` objects (cells) #### XML Examples **Two-Column Table with Header:** ```xml Description Value Thickness |withunits(SectionPropsX.HSection,'DR_PropU1','Length',2)| Width |withunits(SectionPropsX.WSection,'DR_PropU1','Length',2)| ``` **Three-Column Table (Description, Parameter, Value):** ```xml Description Parameter Value Design compressive strength of concrete f'c |withunits(fc_Input,'DR_StressU','Stress',3)| Specified minimum yield strength of steel fy |withunits(fy_Input,'DR_StressU','Stress',3)| ``` *** ### 4. DocRow (Table Row) Represents a single row in a document table. **Object Type:** `DocRow` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | --------------------- | ------- | | Guard | Expression | Conditional rendering | - | #### XML Example ```xml Area |withunits(round(SectionPropsX.AreaSection),'DR_PropU1','Area',2)| ``` **Conditional Row:** ```xml Advanced Analysis Results |DetailedResult| ``` *** ### 5. DocCell (Table Cell) Represents a single cell within a table row. **Object Type:** `DocCell` #### Key Properties | Property | Type | Description | Default | | -------- | ------ | ------------------ | ------- | | Style | CSS | Inline CSS styling | - | | colspan | Number | Column span | 1 | | rowspan | Number | Row span | 1 | #### Common Style Properties ```css text-align: center | left | right vertical-align: top | middle | bottom font-weight: normal | bold font-size: 12px | 14px | 16px height: 20px padding: 5px background-color: #f0f0f0 border: 1px solid #ccc ``` #### Content Cell content can include: * Plain text * Embedded variables: `|expression|` * HTML formatting: ``, ``, ``, `` * Line breaks: Standard text wrapping #### XML Examples **Header Cell:** ```xml Description ``` **Data Cell with Variable:** ```xml |withunits(SectionPropsX.HSection,'DR_PropU1','Length',2)| ``` **Cell with Subscript/Superscript:** ```xml f'c ``` **Multi-line Cell:** ```xml Effective Depth (measured from top to centroid of tension reinforcement) ``` *** ### 6. DocCADD (CAD Drawing/Visualization) Embeds CAD drawings, section visualizations, or 3D geometry in the document. **Object Type:** `DocCADD` **Prefix:** `CADD` #### Key Properties | Property | Type | Description | Default | | -------- | ------ | ----------------------- | ------- | | Width | Number | Drawing width (pixels) | 800 | | Height | Number | Drawing height (pixels) | 600 | #### Child Elements Contains a `

` element with: * `N="CADD"`: Parameter name * `V`: Reference to section/geometry object * `T`: Type of visualization ("Section", "3D", etc.) #### XML Examples **Section Drawing:** ```xml

``` **3D Visualization:** ```xml

``` **With Section Context:** ```xml

``` *** ### 7. DocDesignCode (Design Code Check Reference) References design code check calculations and results. **Object Type:** `DocDesignCode` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | -------------------------------- | -------- | | Obj | String | Reference to design check object | Required | | Guard | Expression | Conditional rendering | - | #### XML Examples **Simple Code Check:** ```xml ``` **Conditional Code Check:** ```xml ``` **Multiple Code Checks:** ```xml ``` **Code Check with Context:** ```xml ``` *** ### 8. DocRef (Document Reference) References another document object or table from elsewhere in the model. **Object Type:** `DocRef` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | ---------------------------- | -------- | | Obj | String | Reference to document object | Required | | Guard | Expression | Conditional rendering | - | #### Use Cases * Reuse tables defined elsewhere * Reference results from other sections * Include shared content across multiple documents #### XML Examples **Reference Table:** ```xml ``` **Reference Multiple Tables:** ```xml ``` **Conditional Reference:** ```xml ``` *** ### 9. DocText (Free-Form Text) Inserts formatted text content, including markdown. **Object Type:** `DocText` #### Key Properties | Property | Type | Description | Default | | -------- | ---------- | --------------------- | ------- | | Guard | Expression | Conditional rendering | - | #### Content Format Text is defined within a `` section to preserve formatting and special characters. **Markdown Support:** * Start with `--md` to enable markdown processing * Supports standard markdown syntax #### XML Examples **Simple Text:** ```xml ``` **Markdown Text:** ```xml ``` **Text with Context Label:** ```xml ``` **Complete Example in Context:** ```xml ``` *** ### 10. DocSectionAnalysis (Section Analysis Diagram) Generates interaction diagrams and section analysis visualizations. **Object Type:** `DocSectionAnalysis` #### Key Properties | Property | Type | Description | Default | | ------------ | ---------- | ----------------------------------- | -------- | | N | Text | Object identifier | Optional | | AnalysisType | Number | Type of analysis (0=PM, 1=MM, etc.) | 0 | | Section | String | Section reference | Required | | Width | Number | Diagram width (pixels) | 800 | | Height | Number | Diagram height (pixels) | 600 | | AxialForce | Expression | Applied axial force | - | | Moment | Expression | Applied moment | - | | Orientation | Number | Section orientation (degrees) | 0 | | PhiComp | Number | Compression reduction factor φ | 0.75 | | PhiTens | Number | Tension reduction factor φ | 0.9 | | Ecu | Number | Concrete ultimate strain | 0.003 | | Etu | Number | Steel ultimate strain | 0.005 | | Refinement | Number | Analysis point density | 500 | #### Analysis Types * **0**: P-M interaction diagram (axial-moment) * **1**: M-M interaction diagram (biaxial moment) * Additional types depend on section analysis module #### XML Examples **P-M Interaction Diagram:** ```xml ``` **With Section Context:** ```xml ``` *** ## Variable Embedding and Expressions ### 1. Basic Variable Reference **Syntax:** `|variableName|` **Example:** ```xml |footinglength| ``` ### 2. Function Calls **Syntax:** `|functionName(arg1, arg2, ...)|` **Examples:** **Round Values:** ```xml |round(SectionPropsX.AreaSection)| ``` **Unit Conversion:** ```xml |withunits(fc_Input,'DR_StressU','Stress',3)| ``` **Nested Functions:** ```xml |withunits(round(SectionPropsX.topReinfsAreaPos,2),'DR_PropU1','Area',2)| ``` ### 3. Object Property Access **Syntax:** `|objectName.propertyName|` **Example:** ```xml |SectionPropsX.HSection| |SectionPropsX.effectivedepth| ``` ### 4. Mathematical Expressions Expressions are evaluated before display: ```xml |SectionPropsX.HSection / 2| |footinglength + footingwidth| ``` ### 5. Common Functions #### `withunits(value, unitSystem, unitType, precision)` Formats value with units based on the project unit system. **Parameters:** * `value`: Number to format * `unitSystem`: Unit system reference ('DR\_PropU1', 'DR\_StressU', etc.) * `unitType`: 'Length', 'Force', 'Stress', 'Area', 'Moment', etc. * `precision`: Decimal places **Examples:** ```xml |withunits(SectionPropsX.HSection,'DR_PropU1','Length',2)| |withunits(fc_Input,'DR_StressU','Stress',3)| |withunits(round(SectionPropsX.AreaSection),'DR_PropU1','Area',2)| ``` #### `round(value, decimals?)` Rounds a number to specified decimal places. **Examples:** ```xml |round(SectionPropsX.botReinfsAreaPos,2)| |round(strip_widthx)| ``` *** ## Guard Expressions Guards control conditional rendering of document content based on design parameters. ### Syntax ```xml ``` ### Comparison Operators * `.EQ.` : Equals * `.NE.` : Not equals * `.GT.` : Greater than * `.LT.` : Less than * `.GE.` : Greater than or equal * `.LE.` : Less than or equal * `.AND.` : Logical AND * `.OR.` : Logical OR **Note:** Use `.EQ.` instead of `==` for guards in document context. ### Examples **Simple Condition:** ```xml ``` **Multiple Conditions (OR):** ```xml ``` **Multiple Conditions (AND):** ```xml ``` **Null Check:** ```xml ``` **Numeric Comparison:** ```xml Shear Resistance |ShearCapacity| ``` *** ## Document Structure Patterns ### 1. Two-Direction Design Report Common pattern for pier footings, columns, and biaxial elements: ```xml

``` ### 2. Load Case Results Pattern Standard pattern for showing unfactored, service, and strength results: ```xml ``` ### 3. Conditional Design Sections Sections that appear only when specific design options are enabled: ```xml ``` ### 4. Properties Table Pattern Standard two-column table for properties: ```xml Description Value Thickness |withunits(thickness,'DR_PropU1','Length',2)| ``` ### 5. Material Properties Table Pattern Three-column table with description, symbol, and value: ```xml Description Parameter Value Design compressive strength of concrete f'c |withunits(fc_Input,'DR_StressU','Stress',3)| ``` *** ## Complete Document Examples ### Example 1: Simple Beam Design Report ```xml

Property Value Depth |withunits(d,'DR_PropU1','Length',2)| Width |withunits(bf,'DR_PropU1','Length',2)| Section Modulus |withunits(Sx,'DR_PropU1','SectionModulus',2)| Description Parameter Value Yield strength Fy |withunits(Fy,'DR_StressU','Stress',1)| Modulus of elasticity E |withunits(E,'DR_StressU','Stress',0)| ``` ### Example 2: Pier Footing Report (from user example) ```xml

Description Value Thickness |withunits(SectionPropsX.HSection,'DR_PropU1','Length',2)| Width |withunits(SectionPropsX.WSection,'DR_PropU1','Length',2)| Area |withunits(round(SectionPropsX.AreaSection),'DR_PropU1','Area',2)| Top reinforcement Area |withunits(round(SectionPropsX.topReinfsAreaPos,2),'DR_PropU1','Area',2)| Bottom reinforcement Area |withunits(round(SectionPropsX.botReinfsAreaPos,2),'DR_PropU1','Area',2)| Effective Depth |withunits(round(SectionPropsX.effectivedepth,2),'DR_PropU1','Length',2)| Description Parameter Value Design compressive strength of concrete f'c |withunits(fc_Input,'DR_StressU','Stress',3)| Specified minimum yield strength of steel fy |withunits(fy_Input,'DR_StressU','Stress',3)| ``` *** ## Best Practices ### 1. Consistent Table Styling Use consistent cell styles throughout documents: **Header Cells:** ```css text-align: center; height: 20px; font-weight: bold; vertical-align: middle; font-size: 14px ``` **Data Cells:** ```css text-align: center; height: 20px; vertical-align: middle; font-size: 14px ``` **Left-aligned Text Cells:** ```css text-align: left; padding: 5px; vertical-align: top; font-size: 14px ``` ### 2. Unit Formatting Always use `withunits()` for dimensional quantities: ```xml |withunits(thickness,'DR_PropU1','Length',2)| |thickness| in ``` ### 3. Precision Control Use appropriate precision for different quantities: * **Lengths**: 2 decimal places * **Areas**: 2 decimal places * **Stresses**: 3 decimal places * **Forces**: 1-2 decimal places * **Dimensionless ratios**: 3 decimal places ```xml |withunits(length,'DR_PropU1','Length',2)| |withunits(stress,'DR_StressU','Stress',3)| |withunits(force,'DR_ForceU','Force',1)| ``` ### 4. Section Organization Use hierarchical sections for logical organization: 1. Input Data (geometry, materials, loads) 2. Analysis Results (forces, stresses, displacements) 3. Design Checks (code compliance verification) 4. Summary (design ratios, pass/fail status) ### 5. Guard Usage Place guards at appropriate levels: * **Section level**: Hide entire design sections (e.g., optional torsion design) * **Row level**: Hide individual table rows (e.g., optional parameters) * **Cell level**: Rarely needed, usually guard at row or section level ```xml Detail Parameter |DetailValue| ``` ### 6. CAD Drawing Placement Place CAD drawings before related tables: ```xml

``` ### 7. DocText for Context Use DocText to provide context between design checks: ```xml ``` ### 8. Subscripts and Superscripts Use HTML tags for mathematical notation: ```xml f'c fy Ec 106 x2 σmaxcompression ``` ### 9. Error Handling in Expressions Use conditional expressions to handle null values: ```xml |iif(value == NULL, 'N/A', withunits(value,'DR_PropU1','Length',2))| |iif(isDefined(optionalParam), optionalParam, defaultValue)| ``` ### 10. Reusable Content with DocRef Define tables once and reference multiple times: ```xml ``` *** ## Advanced Patterns ### 1. Dynamic Table Generation Generate table rows based on lists: ```xml Station Moment |StationList[i]| |MomentList[i]| ``` ### 2. Multi-Level Conditional Content Nested guards for complex logic: ```xml ``` ### 3. Combined Results Tables Single table showing multiple limit states: ```xml Limit State Demand Capacity Ratio Strength I |withunits(M_u_StrI,'DR_MomentU','Moment',1)| |withunits(M_n,'DR_MomentU','Moment',1)| |round(M_u_StrI/M_n,3)| Service I |withunits(M_s_SrvI,'DR_MomentU','Moment',1)| |withunits(M_allow,'DR_MomentU','Moment',1)| |round(M_s_SrvI/M_allow,3)| ``` ### 4. Summary Pass/Fail Table Design check summary with status indicators: ```xml Check Ratio Status Flexure |round(FlexureRatio,3)| |iif(FlexureRatio <= 1.0, 'PASS', 'FAIL')| Shear |round(ShearRatio,3)| |iif(ShearRatio <= 1.0, 'PASS', 'FAIL')| Deflection |round(DeflectionRatio,3)| |iif(DeflectionRatio <= 1.0, 'PASS', 'FAIL')| ``` *** ## Common Pitfalls and Solutions ### 1. Missing Variable Delimiters **Wrong:** ```xml SectionPropsX.HSection ``` **Correct:** ```xml |SectionPropsX.HSection| ``` ### 2. Incorrect Guard Syntax **Wrong:** ```xml ``` **Correct:** ```xml ``` ### 3. Forgetting CDATA for DocText **Wrong:** ```xml This text contains characters ``` **Correct:** ```xml characters ]]> ``` ### 4. Inconsistent Cell Heights **Problem:** Rows with different cell heights look unprofessional. **Solution:** Use consistent height in all cells: ```css height: 20px; ``` ### 5. Null Value Handling **Wrong:** ```xml |withunits(OptionalValue,'DR_PropU1','Length',2)| ``` **Correct:** ```xml |iif(OptionalValue == NULL, 'N/A', withunits(OptionalValue,'DR_PropU1','Length',2))| ``` ### 6. Object Reference Syntax **Wrong:** ```xml ``` **Correct:** ```xml ``` *** ## Summary The OpenBrIM document generation system provides comprehensive tools for creating professional engineering reports: **Core Objects:** * **Document**: Root object defining report structure * **DocSection**: Hierarchical organization of content * **DocTable**: Tabular data with rows and cells * **DocCADD**: Embedded CAD drawings and visualizations * **DocDesignCode**: Design code check references * **DocRef**: Content reuse via references * **DocText**: Free-form text and markdown * **DocSectionAnalysis**: Interaction diagrams and section analysis **Key Features:** * **Variable Embedding**: `|expression|` syntax for dynamic content * **Unit Formatting**: `withunits()` for unit-aware display * **Conditional Rendering**: `Guard` attributes for adaptive documents * **Rich Formatting**: HTML/CSS styling in cells, subscripts, superscripts * **Parametric Integration**: Full access to ParamML expressions **Best Practices:** * Use consistent table styling throughout documents * Always format dimensional quantities with `withunits()` * Place guards at appropriate hierarchical levels * Organize content logically (Input → Analysis → Design → Summary) * Use DocText to provide context between technical sections * Handle null values gracefully in expressions * Reuse common content with DocRef By following this guide, AI agents can create comprehensive, professional engineering documentation that integrates seamlessly with OpenBrIM's parametric modeling and analysis capabilities.