Export Options¶
Multipart Parent Summaries¶
Use this export layout to reduce task content while retaining standalone tasks:
export:
layout:
multipart: parents
multipart accepts expanded (the default) or parents. It applies to
Word/PDF task narratives and task tables, SVG cards and PowerPoint task slides.
The normal elements selections still choose fields and sections. Per-standard
export.standards.VERSION.layout.multipart overrides the shared setting.
Gantt exports and terminal list presentation are independent.
Each parent entry uses its authored label, description, note, risks and work
items; missing parent prose remains empty rather than copying a child’s prose.
Common child status, priority, site, B&R, types and tags are retained;
differing values show Mixed as presentation text, without adding input enum
values. Categories instead aggregate all distinct child category IDs in authored
part order. Narratives show each configured label; category table cells show
each configured table_entry (or canonical ID) on its own line. Every line
uses the category column’s alignment from layout.task_table.columns.
Repeated categories appear once. Partial parent views aggregate selected parts.
Source task categories remain scalar and unchanged. Milestone and deliverable references are combined without duplicates.
Complete parent summaries record a completion period only when every part has
an actual completion period, using the latest one.
Timing shows the earliest start and latest end only when every child has timing. Incomplete timing is marked partial/unspecified. Durations describe the calendar span, including gaps, rather than summed effort. Ongoing spans come from their funding years. The original task schedules and dependency graph remain intact; collapsed groups do not create new scheduling constraints or cycles.
The funding displayed on a parent entry uses its authoritative budget, or sums the effective part budgets when there is no parent budget. Funding/budget totals, funded and unfunded subtotals, activity/B&R breakdowns and deliverable readiness continue to use the source parts. A mixed funded/unfunded parent entry can display both budgets while the Funded Total excludes the unfunded allocation, following normal shared-parent budget counting.
A parent spanning activities appears once in its first declared part’s activity and emits a review warning. Activity and B&R subtotals retain the original assignments. Task references and dependency arrows target the displayed parent; references within the same collapsed parent are suppressed. Separately selected relationship and risk sections retain their source detail.
Parent-only documents are summary artifacts. Reimporting one is lossy, and
Mixed values and omitted child fields may need manual review before the
result can be used as a task plan. If a parent ID conflicts with a standalone task ID, the summary receives an
export-only _PARENT suffix and a warning; the standalone task is retained.
The source plan is never rewritten.
The general configuration has one mechanism for choosing plan export content:
export.elements. It applies to Word, PDF, SVG, and PowerPoint. Print a complete
configuration example with planner fields config. The Gantt commands and
terminal list commands do not use this selection.
Output Standards And Page Layout¶
Select export.standard: asc-v4 or asc-v6 for the corresponding ASC output. The standard is
independent of the package version and config_version. Omitting it selects
legacy, preserving existing output defaults. Named standards retain their
document rules; future requirements use a new identifier rather than changing
the meaning of an existing profile. Unknown identifiers are errors.
ASC v4 uses a Project Title: heading, underlined section/metadata headings,
normal paragraph spacing, and portrait pages throughout. Its default order is
project metadata, summary, optional Background, Execution (activities, tasks,
milestones, deliverables), then Resourcing/Schedule (funding table, request
project dependencies, stakeholders, users, and consolidated risks).
The v4 Word/PDF table has an unlabeled task-number column, Site, BNR, Status,
Type, Tags, and the plan’s fiscal years. Status is the derived Funded/Unfunded
indicator, independent of annual allocations. Annual amounts retain units
(for example, 100K); priority/category columns and totals are not selected
by default. Table widths fit within the page margins. Explicit selections and
layout settings override these defaults; populated fields omitted from a
profile remain available for selection and are still validated.
export:
standard: asc-v4
# Omit elements/layout to use the profile's defaults.
# Optional overrides:
layout:
spacing: tight
headings:
underline: false
legacy remains distinct from v4: it preserves the current default behavior,
which has evolved beyond the earlier template. Existing user configuration is
not rewritten. The v4 template’s instructional text and visible version title
are not printed in exports. Existing marking configuration still applies.
export:
standard: asc-v6
header: 'CUI // EXAMPLE'
layout:
spacing: normal
headings:
underline: false
task_table:
orientation: landscape
fiscal_years: [FY28, FY29, FY30, FY31, FY32, FY33]
ASC v6 defaults to underlined section/metadata headings and a landscape Word/PDF
funding table. The example disables heading underlining for another deliverable.
The document title, task field prefixes, and hyperlink underlining have separate
roles; the heading switch does not change hyperlink or category formatting.
Narrative pages stay portrait. The table starts a new landscape section, repeats
its column headings across pages, and returns to portrait for following content.
Numbering continues across sections. orientation: portrait overrides this.
Word performs pagination; PDF conversion preserves Word’s section layout.
export.layout.spacing accepts normal or tight. ASC v4 defaults to
normal; legacy and ASC v6 default to tight, preserving their existing
compact layout. normal
matches the reference Word document’s spacing: ordinary paragraphs have an
8-point gap and approximately 1.16 line spacing; the title uses 18 points before
and 4 points after. Summary/execution prose uses the reference’s 1.15 spacing.
Tables retain single spacing and zero paragraph gaps, as in the reference’s
table style. Contact entries remain compact within their group.
When text follows a portrait table, its first paragraph receives the missing
paragraph gap before it: 8 points in normal mode and 4 points in tight.
Existing spacer paragraphs, larger gaps, and explicit page/section breaks are
preserved; landscape tables retain their page transitions to portrait content.
Existing indentation, emphasis, underlining and header/footer markings are independent.
SVG adapts the paragraph gap to pixels and grows its cards/canvas. PowerPoint
uses 8-point paragraph gaps and repaginates at the existing font sizes. Terminal
lists and Gantt chart geometry are unaffected. These settings are also shown by
planner fields config; existing user configuration files are not rewritten.
header is literal single-line text used in both the header and footer.
Its default is an empty string; set header to add markings or use
header: '' to clear them.
There is no separate footer option. Markings also apply to plan SVG/PowerPoint
and Gantt SVG/PowerPoint. They are independent of content selection.
ASC v6 restores Execution, Tasks, Milestones, Deliverables and
Resourcing/Schedule headings for included content and titles the plan
Project Title:, as in the v6 template. Following that template, structured
dependencies (request dependencies), optional stakeholders and users
prose, and consolidated risks appear under Resourcing/Schedule, before the
funding table. In the default output order dependencies follow deliverables.
Milestones may supply reporting_level: L1 or L2. No absent facts are
invented and no specific fiscal years are forced by the standard.
When elements is omitted/null under asc-v6, the profile supplies a
standard narrative and table. Default table columns are task number, site,
B&R, Funded/Unfunded status, type, tags, ASC task priorities, budget category
ID, and fiscal funding. priority is the ordinary task field; each table row contains that task’s
ordered IDs and may differ from other rows.
Multipart tasks use hierarchical numbers such as Task A.1.1 beneath Task A.1.
Ordinary table cells have 2.7-point left/right margins. Merged activity and
parent-task table rows have 3-point left/right cell padding
so their labels do not touch the borders. This applies to both spacing modes.
Word/PDF column headers are always bold, including fiscal-year headers.
Merged activity row labels such as Activity A are also bold.
Activity headings stay with their first task row when the table crosses a page
boundary. Parent-task headings likewise stay with their first part, allowing
Word/PDF to break before the heading to preserve context. Larger activities may
continue across pages after their first task; column headings still repeat.
Word’s required empty paragraph after a final table uses compact paragraph-mark
formatting so it does not spill onto an otherwise empty last page. This applies
to both table orientations and is independent of body font size and spacing.
The same parent/first-child policy applies throughout paginated exports:
document titles, section and item headings, custom multi-line headings, and
nested risk/work-item fields. Word/PDF uses the rendered paragraph hierarchy;
explicit page/section breaks remain authoritative. PowerPoint moves continuation
breaks before nested heading chains when the heading and first detail fit
together. Larger child content may continue across pages/slides. SVG is a
continuous canvas and has no page boundaries.
Amounts and totals are numeric thousands of dollars, with thousands separators.
Unfunded tasks retain their specified amounts; funding status depends only on
task status. The optional fiscal_years column list can include a baseline
year without changing plan coverage, task schedules, or funding calculations.
Export selections use the same containers as plan YAML. Execution contains
description, activities, tasks, milestones, and deliverables;
resourcing contains dependencies, stakeholders, users, risks,
and the generated task_table. For example:
export:
standard: asc-v6
elements:
project:
summary:
execution:
description:
heading: false
activities:
tasks:
milestones:
deliverables:
resourcing:
dependencies:
stakeholders:
users:
risks:
task_table:
columns:
number:
label:
fiscal_funding:
Without an explicit structure, nested selections supply their grouping and
child declaration order, including when the standard is legacy. Omitted children
stay disabled. Ordered task/definition instructions and description heading
switches work at their nested paths. execution.spacing supplies the default
for its selected children; resourcing.spacing supplies the default for its
selected prose/definition children. Child spacing overrides take precedence.
The task table keeps its independent table layout/spacing behavior.
Flat selections such as elements.tasks and elements.task_table remain
accepted, including mixed flat/nested mappings when each field appears in only
one location. Defining both a nested and flat occurrence is an error even if one
is false or empty. Existing flat-only mappings keep their implicit order and
behavior. For compatibility, a bare/boolean execution selection retains its
original description/activities meaning; select its collections explicitly.
A bare/boolean resourcing selection applies to all its children.
An explicit elements mapping controls selected content and fields.
To override the natural grouping/order independently of field selection, use
export.structure:
export:
standard: asc-v6
structure:
- project
- portfolios
- managers
- pocs
- summary
- fiscal_current
- planned_value
- actual_value
- potential_value
- execution:
- activities
- tasks
- milestones
- deliverables
- resourcing:
- dependencies
- stakeholders
- users
- risks
- task_table
The execution group automatically places its selected introductory description
first. activities places execution.activities separately; a bare
execution entry places the description. The resourcing group supplies the
Resourcing/Schedule heading. Children may be moved between groups, including the
Word/PDF task table. Every element and group may occur only once; unknown names
and nested groups are errors. null restores implicit placement; [] omits
placed sections. As with existing output, the document title/slide cover remains
an anchor. An empty group has no heading.
Placement never enables content. An enabled element omitted from an explicit
structure is not rendered. Canonical field paths include
execution.tasks, execution.milestones, execution.deliverables,
resourcing.dependencies, and resourcing.task_table. Existing flat field
paths remain compatible, including the short paths in later examples. Structure entries use the short section names shown
above; they can move a selected section outside its natural container without
moving its field selection. Existing table column selections still apply.
structure can also be specified in per-standard overrides; lists replace as
a whole, and inactive overrides are validated.
Word/PDF group headings use outline level 1, with child sections at level 2. SVG and PowerPoint follow the same narrative order and group boundaries. The task table remains a Word/PDF feature; placement does not create a table in SVG or PowerPoint. Field-level execution instructions retain their own ordering when implicit placement is used. Explicit placement controls the relative position of the execution description and activities.
For complete ASC defaults, omit existing elements and table column layout,
or explicitly enable the ASC columns. planner fields config includes
commented examples. Plan files now put tasks, milestones and deliverables under
execution and project commitments/risks/prose under resourcing. The flat
Python plan API, terminal views, schedules, funding and Gantt calculations retain
their existing behavior. Word imports emit the nested YAML organization.
Word custom properties, SVG metadata and PowerPoint document properties record
the output standard, planner version and effective heading/table settings.
These properties contain presentation provenance, not hidden plan content.
The output-standard identifier is metadata only; exports do not print it in
document text, SVG graphics, PowerPoint slides, or PDF content.
See Command Line Interface for version-aware Word import and --update asc-v6.
Separate Rules By Standard¶
Use export.standard to select the active profile and export.standards
to keep separate rules for legacy, asc-v4, and asc-v6 in one file:
export:
standard: asc-v6
header: 'CUI // EXAMPLE'
layout:
headings:
underline: false
standards:
asc-v4:
elements: null
layout:
spacing: normal
task_table:
orientation: portrait
asc-v6:
elements:
project:
summary:
execution:
tasks:
milestones:
deliverables:
task_table:
stakeholders:
users:
layout:
spacing: tight
task_table:
orientation: landscape
Settings resolve in this order: built-in defaults for the selected standard,
shared settings directly under export, then its selected standard block.
Changing standard selects the corresponding rules without rewriting other
blocks. A missing or empty block adds no overrides. Existing configurations
without standards retain their behavior.
For one export, planner export plan.yaml plan.docx --standard asc-v4 selects
v4 without editing the file. --standard accepts legacy, asc-v4, or
asc-v6 and takes precedence over export.standard. It selects the matching
block before resolving shared settings and overrides; it does not merely change
the version label after rendering. When omitted, configuration chooses the
standard. This applies to every plan export format, including PDF conversion.
Each block accepts header, elements, layout, and structure. Layout
mappings merge by setting, so a block can override table orientation while
inheriting shared heading formatting. Ordered lists, including column layouts,
replace rather than append. A block’s elements replaces the entire shared
selection: its declaration order and omitted-child rules apply independently,
including ordered formatting instructions. Omitting elements inherits the
shared selection; elements: null restores the chosen profile’s default
selection, and elements: {} disables selected content. Layout null/false
values are not reset operators; use the setting’s existing supported values.
All blocks are validated, including inactive ones, as are shared settings even
when overridden. Unknown standards, unknown fields, nested standard or
standards keys, and invalid values are configuration errors with source
locations. This feature does not apply to list presentation settings.
planner fields config includes a copyable commented example.
Export metadata records the active standard and resolved presentation, including explicit section order and formatting instructions. Inactive blocks are not embedded, and standard identifiers are not printed in visible output.
Selecting Content¶
Use booleans and nested mappings. true enables a whole branch, false
disables it, and a mapping selects children. A bare entry (YAML null), such as
milestones:, means the same as milestones: true. This shorthand also
applies to nested fields, table columns, and totals. Omitted children in a mapping are
disabled. An empty mapping disables that branch. Under legacy, omitting elements or setting
it to null enables all supported content, including notes. The packaged
configuration lists every supported field explicitly and disables notes by
default. Top-level sections follow their declaration order in elements. Document
titles and PowerPoint covers remain first. Omitted/null elements uses the
packaged section order.
export:
elements:
project: true
summary: true
execution:
tasks:
number: true
label: true
status: true
category: true
description: true
note: false
site: true
bnr: true
funding: true
risk:
type: true
level: true
description: true
mitigation: false
workitems:
id: true
label: true
status: true
resourcing:
task_table:
columns:
number: true
site: true
bnr: true
funding: true
fiscal_funding: true
totals: true
Top-level elements are project, portfolios, managers,
pocs, summary, background, fiscal_years, fiscal_range_begin, fiscal_range_end,
fiscal_current, planned_value, the calculated actual_value and
potential_value,
execution and resourcing. Execution contains description, activities,
tasks, milestones, and deliverables. Resourcing contains
dependencies, stakeholders, users, risks, and the export-only
task_table. Selecting
fiscal_years displays normalized coverage and takes precedence over individual
range endpoints. Otherwise, selected configured endpoints appear individually.
Task narratives display configured labels for both category and priority.
Custom narrative lines use the same labels. The independent Word/PDF task table
uses each entry’s optional table_entry, falling back to its canonical ID.
Select tasks.priority for task narratives or task_table.columns.priority
for the independent Word/PDF table. The old project-priority section is removed.
Define table conversions explicitly in the active configuration, for example
id: INVEST with table_entry: Cat 3 or id: ASC_1 with
table_entry: ASC 1. There are no automatic ID conversions.
This does not affect input IDs; Word import resolves canonical IDs or explicit
table labels back to canonical IDs. See General Configuration for validation rules.
Project-year funding metadata is selected independently:
export:
elements:
fiscal_current:
planned_value:
actual_value:
potential_value:
tasks:
Current Fiscal Year: FY27 identifies the reporting year, and
Planned Value: $100K displays its project budget without repeating the year.
Actual Value: $85K displays the complete project’s funding for that year, with only
the amount colored green below budget, black at budget, or red above budget.
Task status does not exclude specified funding; authoritative multipart parent
budgets count once. The fields precede Execution in profile defaults when
present; explicit selection/order and per-standard overrides remain effective.
Missing metadata is omitted. Actual Value requires a declared current year and uses
neutral black when the planned budget is unspecified.
Word import recovers the declared year and planned budget and recomputes Actual Value from recovered funding. Omitted funding and original multipart budget structure can change the imported total and require review. If the year was hidden, an imported planned budget is retained in summary prose for review instead of inventing a year or writing an invalid yearless budget.
For example, bare entries enable milestones, selected task fields, and deliverables in that order:
export:
elements:
milestones:
tasks:
line: [id, label, status]
description:
deliverables:
A missing key still excludes that element within a mapping; {} still disables
a branch. Bare-value shorthand applies only to content selection, not line/style
settings or table layout.
Nested Fields¶
tasks accepts every task input field, except authoring directives such as
parts and defaults. The optional generated fields number, duration, state, and
funding_status control task numbering, duration text, dependency-aware
schedule state, and funding status. The task field end displays the effective
end regardless of whether it was supplied or calculated.
Task expected selects the duration in months, supplied or derived from endpoints; duration selects its formatted display. Unknown names and invalid
nesting are configuration errors with source locations. Use note, not
notes.
end is available independently of the input timing representation. A task
authored with start and expected can display its calculated end without
displaying its duration:
export:
elements:
tasks:
- line: [number, label, status]
- line: [start, end]
- description:
The same configuration works when the input supplies start and end.
Each line uses effective task timing, including funding-driven ends for ongoing
tasks. This syntax also works in configured terminal task lines. Word import
recovers a selected start/end pair and derives duration; an end displayed without
a recoverable start is reported for review and omitted from the draft. Ongoing
ends remain derived from imported funding.
Task.funding_status is a read-only boolean: false only when task status is
unfunded, and true for every other status. It is independent of fiscal-year
funding amounts, which may remain specified on unfunded tasks. Exports display
Funded for true or Unfunded for false. It is not a plan input field. To add its table column,
enable export.elements.task_table.columns.funding_status. The separate
export.elements.tasks.funding_status controls narrative output; both are
disabled in the packaged defaults. Its layout attribute is funding_status.
Task risk accepts type, level, description, and mitigation.
Risk content appears within the owning task narrative. Each entry repeats an
unnumbered Risk heading, retaining its selected severity color. There is no separate
Risk Mitigation section or configuration switch. Narrative risk selection is independent of risk table column selection.
Task workitems accepts id, label, description, status,
assignees, and the derived type. Each selection applies to every reference.
Task relationship lists and fiscal funding are selected as complete fields.
execution accepts description and activities. Activities support
id, label, description, generated number, and optional tasks,
task_count, and funding summaries. They accept the same ordered
instructions as tasks, milestones and deliverables.
Task Lines And Field Styles¶
Use an ordered list under tasks. Each line: instruction groups scalar
fields on one logical output line. Repeat line: in separate list items and
interleave standalone fields wherever they should appear:
export:
elements:
milestones:
tasks:
- line:
- field: id
color: magenta
- field: label
bold: false
italic: true
- field: status
color: auto
bold: true
color: cyan
- description:
- line: [category, funding_status]
- risk:
type:
level:
mitigation:
deliverables:
task_table:
columns:
number:
funding_status:
fiscal_funding:
totals:
This exports milestones, task narratives, deliverables, and then the Word/PDF summary table. The table may appear anywhere among selected sections, including without task narratives. SVG and PowerPoint do not render the summary table.
Instructions render in their listed order, with only listed content enabled. Within a line, fields are ordered and separated by spaces. Bare standalone entries retain their existing field rendering, including structured/nested content. Empty task lists disable task narratives. Repeating a field, including across grouped lines and standalone instructions, is an error.
A field name such as id prints its value and is shorthand for
{field: id}. Line-wide bold, italic, and color settings are
siblings of line; per-field mappings override them. Lines wrap to fit the
output width. A logical line is not a promise to fit on one physical page line.
Status and schedule state retain bracketed markers. Category defaults to Category: label with a bold prefix, normal label text,
and no category ID. Line/field bold and italic settings do not change that fixed
category emphasis. The instruction-list syntax also applies to milestones and deliverables, as
described below.
Bare tasks: and tasks: true retain the default task layout.
Field heading control¶
Use heading: true or heading: false to show or hide a field’s generated
label. Standalone instructions accept it beside the field selection; grouped
lines accept a line-wide default and per-field overrides:
export:
elements:
tasks:
- line: [number, label, status]
- description:
heading: true
- line:
- field: start
- field: end
heading: false
heading: true
- category:
heading: false
- risk:
type:
mitigation:
heading: false
This adds Description: before the task prose on its first paragraph, prints
Start: before the start value, and omits the End and Category prefixes.
For a structured standalone field such as risk or workitems, the switch
controls its parent heading and all selected child labels; values remain visible.
Exported field labels are bold, with ordinary value formatting preserved.
Omitting heading enables labels for standalone fields, including task
descriptions (Description: on the first paragraph). Grouped
line fields have no prefixes except Category. The same syntax works for
milestone/deliverable instructions and configured list output, whose existing
terminal defaults are preserved when the setting is omitted. heading must be
a boolean; bare/null values are invalid. It does not enable disabled content or
control section/item titles or table column headers. Heading underlining remains
controlled separately by layout.headings.underline. Word import retains
field identities even when their visible labels are hidden.
Task number fields in a line accept format: short or format: full:
export:
standard: asc-v4
elements:
tasks:
- line:
- field: number
format: short
- label
- status
- description:
This produces a heading such as A.1.1 Evaluate the prototype [ACTIVE].
full is the default and retains the Task `` prefix. The number itself is
unchanged: ASC v4/v6 use activity/task/part numbering, while legacy keeps its
existing activity/task numbering. It is generated from output ordering and is
distinct from ``id, the stable identifier stored in the plan. Number formatting
does not alter stable IDs, dependency references, default headings, or tables.
Bold, italic, and color overrides remain available on the same field. Word
import recognizes both forms through the existing semantic field markers.
format is supported only on a task number field mapping, not as a
line-wide default, standalone field selector, definition-field style, or table
column option. Null and unknown formats are errors. The same per-field syntax
works in configured terminal task lines, preserving terminal numbering.
planner fields config includes an example.
The previous task mapping with line: [id, label, status] or lines entries
containing fields remains accepted for compatibility. Its grouped lines still
precede other selected fields. New examples use repeated line: instructions.
Do not mix lines with the instruction-list form or place multiple directives
in a single instruction. Duplicate YAML keys are rejected.
Per-field styles override line defaults, then exporter defaults. Explicit false
turns off inherited bold/italic, including inline emphasis for that field.
Colors accept black, white, red, green, blue, cyan, magenta, yellow, gray/grey,
orange, purple, teal, navy, maroon, olive, or quoted "#RRGGBB" values.
auto uses semantic status colors for status and normal black for other
fields; default explicitly selects normal black. Status defaults to its
semantic color. Other fields retain inline emphasis unless overridden.
Only single-value task fields and generated scalar fields can appear in lines.
Structured/list fields (risk, workitems, funding, dependencies, tags, milestones,
and deliverables) keep their existing separate rendering. Empty lines, unknown
fields/styles/colors, duplicate grouped fields, both line and lines,
and grouped fields explicitly set to false are configuration errors. Lines and
styles affect exports only; plan validation and terminal listing are unchanged.
Milestone And Deliverable Instructions¶
Milestones and deliverables accept the same ordered instruction-list interface,
with repeated line entries, line defaults, and per-field bold/italic/color
overrides. Only listed content is rendered, in declaration order:
export:
elements:
milestones:
- line: [id, label]
bold: true
- description:
- line: [deadline]
- deliverables:
deliverables:
- line:
- id
- field: label
italic: true
- field: status
bold: false
color: auto
bold: true
- description:
- line: [type, ready, required_by]
- producers:
Milestone scalar fields are id, label, description, and deadline. Deliverable
scalar fields are id, label, description, type, status, completed, ready, and
required_by. Calculated dates still use the full validated plan. Milestone
deliverables and deliverable producers are relationship lists and must
use standalone instructions, rather than fields inside a line. Standalone
fields retain their labeled rendering. Deliverable status uses its stored value;
auto colors use the applicable status color or normal black.
Repeated lines and their styles work in Word/PDF, SVG, and PowerPoint, including wrapping and continuation slides. The first grouped line is the item heading when it is first in the instruction list; otherwise the renderer retains a generic Milestone/Deliverable heading to identify the item. Fields in a line are not repeated separately. Duplicate fields, unsupported line fields, mixed directives, and invalid styles are configuration errors. Empty instruction lists disable the section. Existing bare/true entries and child mappings keep their previous output. No new mapping-style line/lines aliases are added for these sections.
planner fields config includes commented replacement examples for both
sections. Word import recovers selected visible definition fields and references;
calculated fields are never imported as plan inputs, and omitted required values
still require review. Plan schemas, validation, dependencies, and timing are
unchanged.
Table Content¶
task_table controls the Word/PDF task summary table. SVG cards and PowerPoint
bodies use task field selections; they do not gain a separate summary table.
Set task_table: false to remove the entire table and its heading. columns
selects individual columns, including formerly fixed task numbering. These
selections are independent of task narrative fields: omitting or disabling
tasks.site does not suppress an enabled task_table.columns.site. Layout
only styles selected columns; it does not enable them.
Risk and work-item columns accept either a boolean for the complete value or a
mapping of selected children, such as risk: {type: true, mitigation: true}.
Their table children are independent of narrative risk/work-item selections.
Relationship columns retain reference labels and IDs even when the corresponding
narrative definitions are hidden.
Column names are task input fields plus number, end, duration,
state, funding_status, priority, and fiscal_funding. funding displays a task’s
fiscal funding.
fiscal_funding expands into one column per plan fiscal year, independently of
tasks.funding. Fiscal columns appear as the final group. totals controls
the funding totals row when a funding or fiscal-funding column is selected.
Like terminal list totals, task_table.totals accepts a mapping with optional
activity, bnr, and unfunded children. Enabled children include the
overall total and add the selected breakdowns. A bare totals: or
totals: true shows only the overall total; false, {}, or a mapping
whose children are all false disables totals.
Overall, activity, and B&R total labels are bold and end with a colon;
amounts retain normal weight.
activityOne
Activity A Totalrow per activity.topplaces it after the activity heading row;bottom,true, or a bare entry places it after the activity’s last task.bnrOne row per B&R code, labeled
B&R CODE Total:, plusNo B&R Total:for tasks without one. Withactivity, each activity also lists its own B&R rows (Activity A B&R CODE Total:) beside its activity total. The plan-wide B&R rows always precede the planFunded Totalrow.
export:
elements:
task_table:
columns:
number:
bnr:
fiscal_funding:
totals:
activity: bottom
bnr:
Activity and B&R subtotals use the same counting as the plan total, so each
set adds up to Funded Total. These totals always exclude unfunded budgets.
The unfunded child adds a separate Unfunded Total: row immediately before
Funded Total:, with the same bold label, trailing colon, alignment and
amount formatting as other subtotals. This replaces its previous behavior of
including unfunded amounts in regular totals:
export:
elements:
task_table:
totals:
unfunded:
The previous sibling settings totals_activity, totals_bnr, and
totals_unfunded remain supported with boolean/bare totals. They cannot
be combined with a totals mapping. The previous form can still select
subtotals independently while disabling the overall total.
The task rows themselves still show each unfunded task’s funding. A multipart
parent’s single budget counts as funded when any part is funded, with a warning
when its parts are mixed. A multipart parent’s single
budget counts once, under its first part’s activity and B&R code; a warning
reports parents whose parts differ. Word import skips these derived rows. SVG
and PowerPoint exports have no task table and do not show subtotals.
Completed fiscal cells merge and turn green when task status is enabled. They
show Completed, with the completion year appended only when completed is
also enabled. Disabling status suppresses this completion styling.
Tables with no effective columns are omitted. Zero ordinary columns with fiscal
columns remains a valid table. Readiness, funding, schedules, numbering, and
multipart parent totals always use the full validated plan.
Table Presentation¶
export.layout affects presentation only. Column definitions under
layout.task_table.columns set label, alignment, and ordering. Listed columns
come first, followed by other enabled columns in canonical order; fiscal-year
columns remain last. An entry never enables a column.
export:
elements:
tasks:
number: true
site: true
bnr: true
task_table:
columns:
number: true
site: true
bnr: true
layout:
task_table:
columns:
- attribute: number
alignment: left
- attribute: site
label: Institution
alignment: left
- attribute: bnr
label: Budget Code
alignment: center
Alignment choices are left, center, and right. Labels are optional.
Set independent body and table font sizes in points:
export:
layout:
font_size: 12
task_table:
font_size: 10
layout.font_size sets narrative text and section/field headings in Word/PDF,
SVG, and PowerPoint. Display titles and header/footer markings retain their
existing sizes. layout.task_table.font_size sets all Word/PDF table text,
including bold column headers and merged activity/parent rows; it does not
inherit the body setting. Word/PDF defaults are 12-point body text and 10-point
table text. If the body setting is omitted, SVG and PowerPoint retain their
existing format-specific sizes. SVG converts explicit points to pixels at 96dpi;
its line wrapping/card heights and PowerPoint pagination follow the chosen size.
SVG/PowerPoint do not render the Word summary table.
Both settings accept numbers from 1 to 1638 in half-point increments, such as
10.5; strings, null, booleans, and other fractional steps are errors. Omit a
setting to use its default. Per-standard layout overrides inherit/replace
the settings independently. Table width estimates use the selected table font;
smaller text can fit more columns, while larger text may trigger the existing
page-width warning. Word/PDF keep the configured font size when space is tight.
Word/PDF table columns reserve estimated room for their longest single word, including identifiers and B&R codes with punctuation. Sizing uses displayed values, bold headers, fiscal totals, and merged completion/total labels, with cell margins and a font safety allowance. Remaining width favors columns with multiword text; short scalar columns stay compact. Column order, page margins, orientation, and font size are retained. Word table paragraphs disable character-level Latin word breaking and automatic hyphenation; multiword values may wrap between words.
If the estimated minimum widths exceed the printable page width, export warns and fits the table to the page; some values may still wrap. Choose landscape orientation, fewer columns, or a smaller table font to provide more space. Widths are estimates rather than measurements from Word, so installed fonts can still affect rendering.
A fiscal_funding layout entry applies its alignment to every year column,
including headers, totals, and merged completion cells. Its optional label
prefixes each year heading (for example, Budget FY27); without a label,
headings remain FY27, FY28, and so on.
Duplicate layout attributes, unsupported fields, and content switches inside
layout are errors.
Narrative Formatting And Import¶
Legacy generated headings and labels are bold without underlining; the standard
and layout.headings.underline can change heading underlining. Word/PDF uses
compact spacing: no added space before paragraphs or between a heading and its
details, zero internal group gaps, and four-point gaps between entries.
Enabled task headings are followed by selected fields in the renderer’s order.
Each separately rendered child is indented one level beneath its parent across
Word/PDF, SVG, and PowerPoint. In Word/PDF, individual task headings align with the
document margin; there is no additional Tasks section heading. Task fields
sit beneath the task heading; risk and work-item fields sit another level
beneath their individual headings.
Execution, milestone, and deliverable details follow the same policy, as do
contact lists and auxiliary priority entries. Each level is a quarter inch
(18 points in Word/PowerPoint, 24 pixels in SVG). Wrapped lines retain their
field’s indentation, including across PowerPoint continuation slides.
When category is enabled, its default format is a bold Category: prefix
followed by the configured label in normal text, without an appended ID.
An explicit heading: false hides the prefix in formatting instructions.
Notes appear after descriptions
when enabled. Word/PDF and SVG share inline bold/italic/link rendering; PowerPoint
retains editable text, fixed fonts, pagination, and continuation slides.
Plain text sections support unordered Markdown lists using *, -, or
+ followed by a space. Preserve item boundaries with a YAML literal block:
description: |
Evaluate the prototype:
* Check **accuracy**.
- Measure throughput.
+ Record the test environment.
+ Publish the [report](https://example.com/report).
The three markers have the same meaning and render as bullets in terminal,
Word/PDF, SVG, and PowerPoint output. Indented items retain nesting; emphasis
and links work inside items. Word import recovers native bullet lists as
Markdown. This applies to prose such as summaries, descriptions, notes,
mitigations, and resourcing text; configured line instructions still
explicitly request a single line of output.
Deliverable description lists use separate Word/PDF paragraphs for each item, with hanging indents for wrapped lines and deeper indentation for nested items. Source-wrapped prose and item continuations are joined before rendering. Word import retains all items, emphasis, and links in the recovered description. Section spacing overrides also retain bullet formatting.
Hidden task status, risk level, and priority also disable their corresponding SVG styling. SVG tooltips contain selected content only. Full model validation still runs even when most output is hidden. Generic document shells and export markings remain when content is empty.
Word import reads the selected Word narrative’s visible fields. Omitted required information may need review or placeholders; a table-only or identity-free partial document may not be independently importable. Legacy Word narratives remain supported. New category labels resolve against the active configuration; missing or ambiguous labels produce a review placeholder. Older appended category IDs remain recoverable. Task priorities resolve configured labels, explicit table labels, or canonical IDs per task. Table IDs disambiguate duplicate labels; missing disambiguation or a conflict requires review before import writes a plan. Older project-wide assignments are copied to tasks without an explicit assignment, with a review notice.
Migration¶
Replace an old element-name list with a mapping, for example
elements: {project: true, execution: {tasks: true}}. Replace include_note and
--include-note with elements.execution.tasks.note. Replace
task_table_attributes and task_table_columns with
elements.resourcing.task_table.columns; task narrative selection is independent.
Move custom labels, alignment, and ordering to layout.task_table.columns.
Move the former elements.tasks.table branch to elements.resourcing.task_table.
The former location and flat elements.task_table remain accepted for compatibility;
specifying both locations is an error. Existing user configuration is not rewritten.
The retired configuration keys and command flag are rejected. There are no
content overrides outside the selection tree.
Existing low-level Python ExportOptions constructors and legacy options-file
helpers remain compatibility interfaces for callers. General configuration
accepts only the new elements and layout keys. New Python callers should
use ExportOptions.from_mapping with that same nested configuration.
PDF And PowerPoint¶
PDF uses the selected Word document and requires Microsoft Word on macOS or Windows. Conversion failures preserve existing output. Linux users can export Word and convert it on a supported system.
PowerPoint uses editable slides and supports --template PATH for a specific
.pptx or .potx file. Otherwise it searches
TUXFAN_PLANNER_TEMPLATE_DIRECTORY, then the current directory, for
template.pptx or template.potx. Explicit missing/invalid templates fail;
there is no fallback. Existing designs, masters, and layouts are retained while
sample slides are replaced. Table layout settings apply to Word/PDF only.
Execution description headings¶
execution accepts an ordered instruction list as well as its existing
selection mapping. The description uses the same heading switch as other
standalone descriptions:
export:
elements:
execution:
- description:
heading: false
- activities:
The same syntax works under list.elements. Omitted heading or explicit
true shows the description heading. False hides the heading and retains the
prose; it does not hide the standard’s top-level Execution heading. Keep the
activities entry to include activity definitions, or omit it to export only
the description. Instructions appear in their declared order, and activities
may contain their own ordered instruction list. An execution line may group
its scalar description using the standard per-line/per-field styles.
Hidden headings retain Word semantic markers so the execution description can
still be recovered during import. Existing mapping selections and defaults are
unchanged. planner fields config includes a copyable replacement example.
A concise mapping form is equivalent when only the description heading needs customization:
execution:
description:
heading: false
activities:
The description mapping accepts the boolean heading setting; other keys are
rejected. Existing bare selections remain unchanged. An empty description style
mapping uses the default visible heading.
Per-element spacing¶
Export elements may override export.layout.spacing with normal or
tight. The override applies to the whole selected collection or prose block,
including its nested details and gaps between items. It does not change content,
indentation, fonts, colors, explicit paragraph breaks or pagination relationships.
The existing normal/tight rules remain the reference for each format.
export:
layout:
spacing: normal
elements:
tasks:
- spacing: tight
- line: [number, label, status]
- description:
heading: false
milestones:
spacing: tight
id:
label:
description:
deadline:
deliverables:
spacing: normal
id:
label:
description:
type:
Spacing directives are presentation settings, not selected fields. They may appear anywhere in an ordered instruction list and apply to the entire element; only one directive is allowed per scope. A directive must contain only spacing. A spacing-only declaration includes the same default content as a bare element. When fields are also specified, normal child-selection omission rules apply; spacing never enables explicitly disabled fields. Omit spacing to inherit; null, booleans and other values are invalid.
Supported scopes are tasks, milestones, deliverables, execution,
execution.description, execution.activities, summary, background,
dependencies, stakeholders, users, risks,
portfolios, managers, pocs. Single-line fiscal and
budget metadata continue to inherit document spacing. For example:
execution:
spacing: normal
description:
heading: false
spacing: tight
activities:
- spacing: tight
- line: [number, label]
- description:
An element inherits the nearest enclosing explicit spacing setting, then the document setting, then the selected standard’s default. Per-standard element selections may carry independent spacing overrides using existing replacement and inheritance rules. At boundaries between narrative sections, the following section controls the gap; existing larger gaps and page/section breaks remain. Headings stay attached to their first content. PowerPoint calculates wrapping and pagination with each slide’s resolved mode; SVG recalculates vertical layout.
Task narrative spacing does not affect task-table cell margins, single-spaced cell paragraphs, row density, columns or funding. The paragraph after a portrait table uses its following section’s mode. Spacing directives are export-only; terminal list presentation is unchanged and rejects these directives. Existing configurations retain their output rules when no overrides are supplied.
Generated-number heading punctuation¶
Task and activity headings separate generated numbers from their labels with a
colon: Task A.1.1: Child label and Activity A: Activity label. This also
applies to configurable line: [number, label, status] output and short number
formats (A.1.1: Child label). If other prefix fields intervene, the colon
immediately precedes the label, preserving configured field order. Explicit
label field headings keep their own Label: prefix without an added separator.
Number-only fields and table cells retain their number without a trailing colon. Stable IDs do not receive automatic punctuation. The separator is a presentation span separate from the number/label values, preserving styles and Word import. Word imports continue accepting the previous period-separated default headings. The same shared line rule applies to configured terminal output. Legacy Word/SVG headings and Gantt task labels use the colon convention as well.
Project Dependencies and Consolidated Risks¶
elements.dependencies selects structured project commitments. Its selectable
fields are id, label, type, description, promised, risks,
and the derived tasks list. A task’s own dependencies field displays
references to tasks and project commitments; project commitments remain delivery
unconfirmed until a future fulfillment mechanism is introduced.
elements.risks selects a consolidated Risks section containing project
risks first, then inline risks in normal task order. Shared project risks appear
once regardless of how many dependencies reference them. Separately authored
inline risks retain their owning task and are never assigned public risk IDs.
Selectable fields are id, label, type, level, description,
mitigation, owner, dependencies, and scope. Fields that do not apply
to an entry are omitted. Unnumbered Risk: headings retain severity colors,
controlled by layout.context_colors. Project references do not affect task
risk severity or scheduling automatically.
Both sections accept the same ordered line: instructions, field styles,
heading toggles, and spacing: normal|tight overrides as other definitions.
The following configuration places all risks in the consolidated section and
suppresses their duplicate display inside task narratives:
export:
elements:
dependencies:
- line: [id, label]
bold: true
- line: [type, promised]
- description:
- risks:
tasks:
- line: [number, label, status]
- description:
risks:
- spacing: tight
- line: [id, label]
bold: true
- owner:
- line: [type, level]
- description:
heading: false
- mitigation:
- dependencies:
A bare risks: uses the complete default presentation. tasks.risk and
risks are independent switches: disabling one does not disable the other.
Enabling both intentionally displays inline risks in both places. Section order
follows declaration order. The same content/line controls are available under
list.elements; export-only spacing directives are not terminal settings.
The former request_dependencies and external_risks selections are rejected.
Word import recovers structured records, reconnects their references, and keeps
consolidated inline risks private to their tasks. If both presentations contain
a task risk, import combines the recovered fields rather than duplicating it.
If its owning task was omitted, the risk prose is retained in the summary with a
review notice. Older unstructured dependency/risk prose is also retained in the
summary rather than assigning unsupported dates, risk levels, or mitigations.
Summary Emphasis¶
Word/PDF preserves all summary line breaks, including blank lines. Inline Markdown is parsed before splitting the lines, so quoted italics and bold can span multiple lines without losing their style. Bullets and nested lists retain their line boundaries. For example:
summary: |-
Our purpose is *"Explore robust methods,
connect models, and improve future experiments."*
The plan provides:
- A clear baseline.
Word/PDF retains the two authored lines of the quote and its italic style.
Word imports recover emphasis from each formatted line. Quotes require no
escaping inside a literal YAML block. Use > or >- instead of | or
|- when YAML should fold ordinary source wrapping into a paragraph. SVG,
PowerPoint and terminal prose continue to reflow source wrapping while keeping
inline emphasis.
All monetary values in export narratives, funding tables, totals and budget metadata use whole thousands with halves rounded up. Exact amounts are summed before any display rounding; see Funding and Staff Costs.