Structure and numbering - electricbookworks/constitution GitHub Wiki

The constitution comprises:

• chapters, schedules and annexures
  • those are divided into sections, some separated into themes by headings
    • sections are divided into numbered clauses (decimal numbering 1, 2, 3)
      • which often have sub-clauses (alphabetical ordering a, b, c) and
        • sub-sub-clauses (roman numerals, i, ii, iii).

The document therefore has a fairly regular tree structure – ideally suited to the tree-structure nature of HTML and HTML lists in particular. So for much of the document we can use lists. Naturally, there are quirks and exceptions, since the constitution is an evolving document written by humans.

In our markdown version of the constitution, we recreate the constitution using this structure:

• Each chapter, schedule or annexure is in a separate file.
• Each section is a single HTML list, set off by a heading before the list.
• We include the number of the section in the section heading, not in its first list item. (The layout of the official constitution in English includes the section number at the start of the first list item. We are deviating from this in order to create simpler HTML lists, and section-numbered tables of contents generated from headings.)
• The section lists are HTML-ordered lists.

If structured correctly in markdown, our CSS styling numbers the clauses and sub-clauses correctly as:

• decimal (1, 2, 3)
  • lower-alpha (a, b, c)
    • lower-roman (i, ii, iii)

In markdown (and specifically in kramdown, the flavour of markdown we're using), an ordered list is created when a line (following an empty line) starts with a number, a full stop and a tab:

1. A list item.

(You can also use a space instead of a tab in markdown, but we prefer a tab.) Each new list item must also start number–full-stop–tab:

1. A list item.
2. A second list item.

It does not matter what numbers you use: the resulting HTML will be an ol ordered list:

<ol>
  <li>A list item</li>
  <li>A second list item</li>
</ol>

The browser or PDF-renderer will always number that from 1 by default, even if your markdown looks like this:

1. A list item.
1. A second list item.

or this:

344. A list item.
21. A second list item.

The resulting HTML list will always be the same. (For overriding the starting number of an HTML list, see Quoting list items. Essentially, you tag the list with a start attribute, e.g.: {:start='3'})

This means you might just paste in 1. for every list item. This is fine if you really need to work quickly. For example, section 3, where this markdown will result in an HTML list that numbers correctly:

## 3. Citizenship

1.	There is a common South African citizenship.
1.	All citizens are–
	1.	equally entitled to the rights, privileges and benefits of citizenship; and
	1.	equally subject to the duties and responsibilities of citizenship.
1.	National legislation must provide for the acquisition, loss and restoration of citizenship.

However, if you have the time, it's easier to read your markdown if you use the actual numbering:

## 3. Citizenship

1.	There is a common South African citizenship.
2.	All citizens are–
	1.	equally entitled to the rights, privileges and benefits of citizenship; and
	2.	equally subject to the duties and responsibilities of citizenship.
3.	National legislation must provide for the acquisition, loss and restoration of citizenship.