summaryrefslogtreecommitdiffhomepage
path: root/format-specification.md
diff options
context:
space:
mode:
Diffstat (limited to 'format-specification.md')
-rw-r--r--format-specification.md15
1 files changed, 13 insertions, 2 deletions
diff --git a/format-specification.md b/format-specification.md
index 587b333..8aec323 100644
--- a/format-specification.md
+++ b/format-specification.md
@@ -224,7 +224,7 @@ and before text content. Only non-default values are written.
.part: body % frontmatter, body, backmatter
.section: body % toc, body, glossary, bibliography,
% bookindex, blurb
-.parent: 5 % parent OCN
+.parent: 5 % parent OCN, see below
.last_descendant: 70 % last descendant OCN
.ancestors: 0 0 0 0 5 20 0 0 % markedup_ancestors[8]
.ancestors_collapsed: 0 0 0 0 5 20 0 0
@@ -245,6 +245,17 @@ and before text content. Only non-default values are written.
A heading's identifier is not a property: it follows the level on the
object declaration line (`[5] heading :1 ch1_intro`).
+`.parent` is written for every object, including when the value is 0,
+with two exceptions: the `:A~` document root, which has no parent, and
+the entries of the generated `@toc` section, which are furniture rather
+than authored objects and whose place is already given by their
+`.indent` level (the `@toc` heading itself does carry `.parent: 1`). A
+parent of 0 is not "no parent recorded": it is a parent heading the
+author has made non-substantive, its ocn suppressed with `~#`, or a
+dummy heading introduced with `-#` to segment an output. Stating it
+keeps "non-substantive parent" and "no parent" distinguishable, so a
+reader must not treat a missing `.parent` as 0.
+
**Text attribute properties** (from `attrib`):
```
@@ -404,7 +415,7 @@ Properties with default values are omitted to reduce verbosity:
|---|---|---|
| .part | "" | empty |
| .section | "" | empty, or same as the enclosing section |
-| .parent | 0 | zero |
+| .parent | (none) | the `:A~` document root, and `toc` entries; otherwise always written, 0 included |
| .last_descendant | 0 | zero |
| .children | (none) | no child headings |
| .ancestors | 0 0 0 0 0 0 0 0 | all zeros |