Fields at layout time

Fields that depend on pages, and the table of contents, index and table of authorities, are resolved while a document is laid out (LayoutEngine.Layout, so also DocumentRenderer, Office.Convert and document.SaveAs("x.pdf")). The document is only read: results go to the pages, never back into the file. References are to ECMA-376 Part 1; items marked to check against Word are rules the specification leaves open and are listed in the table at the end.

Policy

• A result that equals the stored one is left alone, so the field keeps the formatting of its stored runs. A computed result goes into the first result run (its character formatting) and the other result runs of that field show nothing.
• A field with w:fldLock is never rebuilt; a table of contents, index or authorities whose field is not closed, or whose code and result are not in paragraphs of one container, keeps its stored result and adds layout.field-skipped.
• w:updateFields in the settings part (§17.15.1.90, Word updates every field when it opens the file) turns UpdateFields on, because that is what Word does with the file.
• Nothing is fetched: INCLUDEPICTURE, INCLUDETEXT and HYPERLINK targets are never followed.
• The system clock is never read. File dates come from the document properties, shown in the clock's time zone (UTC without a clock).

Passes

A field that depends on pages cannot know its value until pages exist, and its value can change the pages (a longer number, a longer contents list). Layout therefore runs again with the facts of the pass before — the printed number and number format of each page, the page each paragraph starts on (and, for a paragraph that splits, where each piece starts), the page counts of the document and its sections — until a pass produces the facts it was given:

1. Pass 1 has no facts: fields that need them keep their stored result (NUMPAGES shows 1).
2. Pass k reads the facts of pass k − 1 and produces its own.
3. When both are equal the pass stands. When LayoutOptions.MaxFieldPasses (default 6) is reached first, the last pass stands and LayoutDocument.Notes gets layout.fields-unsettled. LayoutDocument.FieldPasses tells how many passes ran.
4. A document in which no field read the facts is laid out once.

A table of contents is built before pass 1 (its length does not depend on pages); only its page numbers wait for the facts. That is how a contents list that makes the headings move down a page ends with the numbers of the pages the headings are on.

The working copy

A table of contents, index or table of authorities that has to be built is built in a copy of the document (the document is saved to memory and opened again; LayoutDocument.WorkingCopy returns it, and LayoutParagraph.Source of that layout belongs to the copy). Entries are real paragraphs, as Word writes them:

The page-list field exists only in the copy (ODXEPAGES, with the bookmark names as arguments and \l and \g separators), so the lists follow the pages like PAGEREF does.

Fields

All of them take \* (Upper, Lower, FirstCap, Caps, Roman, roman, ALPHABETIC, alphabetic, Arabic, ArabicDash, CardText, OrdText, Ordinal, Hex), \# and \@ as in mail-merge.md (§17.16.4). MERGEFORMAT and CHARFORMAT are accepted and ignored. A reference to a bookmark that does not exist keeps the stored result and adds layout.field-source-missing; with UpdateFields it shows Error! Reference source not found..

Notes

layout.fields-unsettled, layout.field-source-missing, layout.field-skipped.

Open points (to check against Word)

Tests and differential inputs

tests/OneDocument.Rendering.Tests/FieldTests.cs lays out generated documents (FieldDocs): a three-level contents list whose entries move after relayout, numbered headings, TOC switches and TC fields, PAGEREF/REF/NOTEREF/STYLEREF/SEQ with their switches, the picture switches, index and authorities (multi-level, ranges, run-in, columns), the stored-versus-updated policy, IF/=/dates, a bounded non-converging relayout and a 800-heading contents list.

The same documents are cases 100–112 of LayoutCases.All(), so tools/layout-differential.sh sends them to Word with the rest of the layout set. They are unanswered until the differential runs; the cases that need a built table of contents carry w:updateFields, so Word has to update fields before its export (or the oracle has to call its field update).

For a later document operation

FieldUpdater (builds the entries in a copy), FieldModel (bookmarks, fields, SEQ and note numbers) and FieldEvaluator (one value per field type) are internal to RecursiveAI.OneDocument.Rendering; a hub-level UpdateFields() writes the computed results with Field.SetResult after one layout, using the facts of its last pass. LayoutDocument.WorkingCopy already holds a document with the tables built, which that operation can save.