You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.
pollen-tfl/hierarchical-headings.html.pm

35 lines
2.1 KiB
Perl

This file contains invisible Unicode characters!

This file contains invisible Unicode characters that may be processed differently from what appears below. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to reveal hidden characters.

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

#lang pollen
(define-meta title "hierarchical headings")
hanging-topic[(topic-from-metas metas)]{Consider tiered numbers}
Traditionally, em{hierarchical headings} in legal documents start with roman numerals at the top level (I, II, III); then switch to capital letters (A, B, C); then numerals (1, 2, 3); then lowercase letters (a, b, c); then romanettes (i, ii, iii); and then variations of the above using two parentheses instead of one, or other barely visible changes.
This is a terrible way to label hierarchical headings.
numbered-list{
Roman numerals and romanettes stink. Theyre difficult to read. (Quick, what number is XLIX?) Theyre easy to confuse at a glance. (II vs. III, IV vs. VI, XXI vs. XII.) If what we mean by I, II, III is 1, 2, 3, then lets just say so.
Letters aren't much better. Though we immediately recognize A, B, C as equivalent to 1, 2, 3, the letter-to-number correlation gets weaker as we go past F, G, H. (Quick, what number is T?) If what we mean by J, K, L is 10, 11, 12, then lets just say so.
Mixing roman numerals and letters results in ambiguous references. When you see a lowercase em{i}, does it denote the first item or the ninth item? Does a lowercase em{v} denote the fifth item or the 22nd item?
By using only one index on each header, its easy to lose track of where you are in the hierarchy. If Im at subheading em{(d)}, is that em{(d)} under superheading em{(2)} or em{(3)}?
}
Lawyers should take a cue from technical writers, who solved this problem long agoby using tiered numbers as indexes for hierarchical headings.
So instead of:
indented{image[#:border #f #:width "80%" "hierarchical-headings-example.svg"]}
Youd have:
indented{image[#:border #f #:width "80%" "hierarchical-headings-example-2.svg"]}
To my eyes, this system is more understandable because it only uses numbers, it avoids ambiguity or miscues. Its also more navigable because every tiered number is unique, its always clear where you are in the hierarchy. And every word processor can automatically produce tiered numbering. Consider it.