Why Navigation Needs Its Own Workflow
A long diagnostic report may contain many sections, tables, and figures. Readers need a reliable way to move from a contents entry to the relevant diagnostic, and back to an overview when the report format supports it. A table of contents that looks complete but links to the wrong figure, or to no figure at all, is not merely inconvenient: it can send a reviewer to evidence that does not support the nearby interpretation.
Navigation is therefore a generated report component that needs its own inputs and checks. A useful workflow connects three things: the intended report structure, the items that were successfully rendered, and the identifiers used by links and destinations. The aim is not simply to list planned sections and figures. It is to make the navigation describe the completed report accurately.
The distinction between a planned item and a rendered item matters. A report-generation process may omit a section or figure after an earlier failure, or conditionally exclude it from a particular analysis report. If the contents are generated from the plan alone, they can advertise material that is absent. Conversely, if an item was rendered but omitted from the manifest, readers may have no direct route to it. The manifest and the final report must be reconciled rather than treated as interchangeable records.
Representing Items and Building Navigation
Give each navigable section or figure an identifier that is stable, unique, and suitable for the report format. Keep identifiers separate from labels: an identifier is for matching links to destinations, while a label is for readers. For example, an identifier might be “fig-vpc-drug-a” while its label is “Visual predictive check for Drug A.” A descriptive label can be revised for clarity without changing the matching key, provided the identifier remains valid.
Choose an explicit ordering rule, such as the order in which items appear in the rendered report. Do not rely on accidental ordering from a file system, an unordered collection, or a display label. For a table of contents, section entries are usually ordered by document position and may be nested by heading level. A figure list can follow figure order and include the figure number or a concise descriptive label. If the report combines these lists, the manifest needs enough information to distinguish item types and to apply the intended grouping.
A robust build uses one record as the source for both sides of a navigation relationship: the link and its rendered destination. Before emitting the contents, it checks which manifest records correspond to items that will actually be rendered. It then emits a link for each eligible record and ensures that the rendered item carries the corresponding identifier. This avoids maintaining the label and identifier independently in two separate places.
Worked Example: Creating a Figure List From a Manifest
Suppose a hypothetical report has three planned figures, listed in document order: identifier “fig-01”, label “Observed versus predicted concentrations”; identifier “fig-02”, label “Residuals by time”; and identifier “fig-03”, label “Visual predictive check.” The rendering record indicates that the first and third figures appear in the completed report, while the second did not render.
The eligible figure records are therefore “fig-01” and “fig-03.” The generated figure list contains two entries, in that order, and each entry links to the destination carrying the same identifier. It must not contain “fig-02,” because that destination is absent. If the report instead rendered all three figures, the list would contain three entries in the order 01, 02, 03.
This is a completeness check as well as a generation rule. If \(R\) is the set of rendered manifest items and \(T\) is the set of generated navigation entries, the intended relationship here is \(T=R\) for figure items. In this example, both sets contain “fig-01” and “fig-03,” so each rendered figure in scope has a list entry and no absent planned figure is advertised.
When Is a Link Unambiguous?
A link is useful only if a reader can resolve it to the intended destination. Matching the identifier in a manifest record to the identifier in the link is not sufficient by itself: the completed document must also contain the destination, and it must not contain a second destination with the same identifier. This last condition applies to every element in the completed document, including elements that are not represented in the manifest.
The justification is direct. By condition 2, at least one destination matches the link identifier. By condition 3, no other element in the completed document has that identifier. Therefore exactly one destination matches. If uniqueness is checked only within the manifest, the argument fails: an element omitted from the manifest could still have a duplicate identifier in the output. A generator should therefore validate the completed document, not infer global uniqueness solely from its input records.
The same reasoning applies when a figure is represented by more than one rendered element. Assign the navigation identifier to one designated destination, such as a figure container, rather than unintentionally repeating it on both a container and a nested image. If the chosen output format handles anchors differently, the build should check the actual rendered form and confirm that each link resolves according to that format’s rules.
Worked Example: Finding a Duplicate Destination
A hypothetical manifest contains one record with identifier “sec-results,” and the report generator uses it both for the contents link and for the rendered Results section. The manifest has no duplicate records. During a document-wide check, however, a separate decorative element is found with the same identifier.
The link refers to “sec-results,” and the Results section is one matching destination. The decorative element is a second matching destination. Thus the link does not resolve unambiguously, even though the manifest identifiers are unique and the listed section was rendered. The correct conclusion is that global uniqueness has failed.
The correction is to give the decorative element a different identifier, or remove its identifier if it does not need to be a navigation destination. Then check the completed document again. If exactly one element carries “sec-results,” the link has one matching destination, assuming the link and destination use the same identifier and the report format recognizes the link.
Generation and Validation as a Sequence
Separating generation from validation makes failures easier to diagnose. A practical sequence is to prepare the candidate records, reconcile them with rendered items, generate links and destinations, and then test the completed output. For a report that contains many analysis-specific sections, carry the analysis context into the labels or grouping where needed, while keeping each identifier unambiguous within the final document.
Collect each intended section or figure’s identifier, label, type, and order from structured report metadata.
Include records only when their corresponding sections or figures are present in the report being built. Record omissions so the contents do not point to items that failed to render.
Use the same identifier for a navigation entry and its designated destination. Apply the specified ordering and labeling rules consistently.
Check that each navigation target exists, each identifier is globally unique, and the contents cover the rendered items intended for navigation.
Several distinct checks are useful because they detect different defects. A missing-target check finds links whose destinations are absent. A duplicate-target check finds identifiers attached to multiple elements, including elements outside the manifest. A coverage check compares the rendered items in scope with the generated entries. An ordering check compares navigation order with the intended document order. A label check can flag blank or uninformative entries, although wording quality still requires review.
Worked Example: Auditing a Short Contents List
A hypothetical report contains two sections and two figures in this order: “Methods” with identifier “sec-methods”; Figure 1, “Concentration-time profile,” with identifier “fig-profile”; “Results” with identifier “sec-results”; and Figure 2, “Residual diagnostic,” with identifier “fig-residual.” All four items rendered. The generated contents contain “sec-methods,” “fig-profile,” and “sec-results,” but not “fig-residual.”
The rendered in-scope set contains 4 items, while the generated set contains 3. The coverage fraction is \(3/4=0.75\), or 75%. More importantly, comparison by identifier identifies the specific omission: “fig-residual.” If all four destinations exist and are globally unique, the three existing links may work, but the navigation is incomplete because Figure 2 has no entry.
Add the missing figure entry in its correct position after “sec-results,” using the label “Residual diagnostic” and identifier “fig-residual.” Re-run the checks: there should be 4 rendered in-scope items and 4 navigation entries; each entry should have a matching destination; and a document-wide identifier scan should find exactly one element for each of the four identifiers. Equal counts alone would not prove correctness, because one item could be duplicated while another is omitted. The identifier-by-identifier comparison is essential.
Approaches, Diagnostics, and Limitations
There are three common approaches to producing navigation. A manually maintained contents list offers direct editorial control, but labels, order, and destinations can become inconsistent as a report changes. A document-scanning approach reads headings or figure captions from the rendered output; it can reflect what is present, but may not know which items should be included, how they should be grouped, or which labels are intended for navigation. A manifest-driven approach makes those choices explicit and supports consistent generation across reports, but only if its records remain synchronized with actual rendering. These approaches can be combined: the manifest can control labels and scope, while a scan of the completed document verifies destinations.
Watch for evidence that the process is going wrong: a contents entry that does nothing, a link that jumps to an unrelated location, repeated identifiers, a figure present in the report but absent from the list, a listed item missing from the report, unexpected ordering, or labels that no longer match the displayed content. Check the final rendered report rather than only the source metadata. Transformations during rendering can alter identifiers, omit conditional content, or create additional elements that were not represented in the manifest.
Navigation also has format-specific limits. A link that works in an HTML report may not behave identically in a PDF or in a print copy. Printed reports may need page references rather than clickable links, and those references can change when pagination changes. The navigation method should therefore match the output format and be tested in that format. This tutorial’s central validation principle remains the same: entries should refer to the intended rendered items, and every generated destination identifier should be unambiguous in the completed output.
Common Mistakes
- Generating from planned items only. A planned figure may not have rendered. Reconcile manifest records with the actual report before emitting its entry.
- Checking uniqueness only in the manifest. An element outside the manifest can still duplicate a destination identifier. Check all identifiers in the completed document.
- Using labels as matching keys. Labels can change or be repeated. Use a stable identifier for matching and a separate label for readers.
- Treating matching counts as proof of coverage. One item can be duplicated while another is missing. Compare identifiers item by item.
- Assuming a link that works in one format works in every format. Test navigation in each intended output format.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A manifest has two figure records, but only one figure appears in the completed report. Should both appear in the figure list? State the rule.
- A link identifier matches one destination, but the completed document has a second element with that identifier outside the manifest. Is the link unambiguous? Why?
- A report has 8 rendered in-scope figures and 7 corresponding navigation entries. What coverage fraction is observed, and what additional check is needed?
- Name two different defects detected by checking the completed document rather than the manifest alone.
Solutions. (1) Only the rendered figure should appear; navigation entries should be reconciled with items actually present. (2) No. The duplicate means two elements match the identifier, so global uniqueness has failed. (3) The coverage fraction is \(7/8=0.875\), or 87.5%. Compare identifiers to find the missing figure; the fraction alone does not identify it or rule out a duplicate entry. (4) For example, a destination can be missing after rendering, or an element outside the manifest can duplicate a destination identifier. A completed-document check can also reveal altered identifiers or unexpected ordering.