What this is
In short
An author writes a long document: chapters, sections, sub-sections, and a place for a table of contents. When the page opens, the titles are numbered, the table is filled from them, and each entry leads to the title it names.
This page is the design of that work. It is written for whoever changes the code, and it is read before reporting a behaviour as a bug: several of them are choices.
Two domains, two letters
The requirements are numbered in two families, as the bibliography numbers its own. D for the document — chapters, sections, abstract, what is numbered and how. T for the table of contents — what it holds, where it stands, and where it leads.
A document without a table is a document all the same, and a table is built from titles it did not write. That is why they are told apart.
What it does not do
- It writes no title and moves none: it numbers what the author wrote, where it was written.
- It numbers nothing itself: the numbers are counted by the stylesheet, so a title carries no number in the source.
- It asks nothing of the internet, and keeps nothing from one opening to the next.
- It does not lay the document on pages: that is the printing, and the slides pagination for a presentation.
The requirements
The document
| No. | Requirement |
|---|---|
| D1 | A long document is read as chapters. |
| D2 | The chapters are numbered, in the order they are read. |
| D3 | A chapter can be left out of the numbering, and the chapters after it keep their count. |
| D4 | Inside a chapter, the sections and the sub-sections are numbered too, and their numbers say which chapter they belong to. |
| D5 | A document can open on a summary, seen as one at a glance. |
| D6 | On paper, a chapter keeps its title with it. |
The table of contents
| No. | Requirement |
|---|---|
| T1 | The table of contents gives what the document holds, in the order it is read. |
| T2 | The author chooses how deep the table goes. |
| T3 | Following an entry leads to the passage it names. |
| T4 | The table is read as a hierarchy: what belongs to what is seen without being read. |
| T5 | An entry bears the number of what it names, and names a chapter left out of the numbering without one. |
| T6 | The table can stand beside the document, and step aside when it is not used. |
| T7 | What brings it back is met before it is needed. |
| T8 | A document without a table is read all the same. |
| T9 | Where the reader stands in the document is seen even when the table is not: a panel that is closed shows no entry, and a long document read without it leaves the reader with no idea of the way already gone. |
How this was designed
MCC: who exchanges what
| Actor | What it does |
|---|---|
| The author | Writes the chapters, the sections and the place of the table. Runs nothing |
| The reader | Reads, and follows an entry of the table |
| The program | Fills the table and ties each entry to its title |
| The browser | Counts the numbers, and lays the document on the pages when it prints |
| No. | From | To | What |
|---|---|---|---|
| F1 | The author | The document | The chapters, the sections, the place of the table |
| F2 | The document | The program | The titles, in the order they are written |
| F3 | The program | The document | The entries of the table, and an anchor before each title |
| F4 | The reader | The program | An entry followed, the panel opened or closed |
| F5 | The browser | The reader | The document, its numbers counted |
MCD: what the data are made of
Three entities.
- DOCUMENT, what the author wrote in one piece. It holds the chapters, and the place of the table when there is one.
- TITLE, known by its place in the order of the document. It has a level, a text, and says whether what holds it is numbered.
- ENTRY, what the table holds. It exists only for a title, and leads to it.
| Association | Leg 1 | Leg 2 |
|---|---|---|
| is made of | DOCUMENT (1,n) | TITLE (1,1) |
| leads to | ENTRY (1,1) | TITLE (0,1) |
Two things are computed, never stored: the number of a title, which the stylesheet counts, and the depth of an entry, which its level gives.
Two rules the keys do not hold: the entries follow the order of the titles; a title has at most one entry.
MCT: the three operations
Op1, number the document.
Triggered when: the document is rendered.
Produces: every chapter, section and sub-section bearing its number, counted in the order they are written. A chapter left out of the numbering produces none, and does not spend a number.
Op1 is run by the browser, from the stylesheet. It is written as an operation because it produces something a reader sees, and because what the table shows of a number depends on it.
Op2, fill the table of contents.
Triggered when: the page opens, and a place for the table is there.
Produces: one entry per title of the levels asked for, in the order of the document, each saying its level and leading to its title. Without a place for the table, nothing is produced and nothing is said.
Op3, reach a title.
Triggered when: the reader follows an entry.
Produces: the title is shown and read. What it takes to show it depends on the support: on a page it is brought under the eyes, and in a presentation the support carrying it becomes the one shown — which is the slides pagination, where that treatment is modelled for every renvoi of a document.
Two requirements are not operations: a document without a table is displayed all the same, and the numbers are never written in the source.
MOT: where, when, and by whom
In the browser of whoever opens the page. Two moments: the request for the page, once, and a request inside the page, once per request.
| PF | What it does | When | Where it comes out |
|---|---|---|---|
| PF1 | Numbers the document | Request for the page | Page and paper |
| PF2 | Fills the table of contents | Request for the page | Page |
| PF3 | Reaches a title | Request in the page | Page |
PF2 happens after the contents the program builds, a bibliography being one of them: a table filled before them would miss their titles.
MLD: the tables
- DOCUMENT (document_id, place_of_the_table)
- TITLE (document_id, place, level, text, numbered)
- ENTRY (place_of_the_title, level, numbered)
A title exists only in the document where it is written, so it carries its identifier, and its place tells it from the others. An entry is known by the title it leads to: there is no entry without a title.
Not in the tables: the number of a title, and the depth of an entry. Both are computed.
MPD: where each table exists
| Table | In the source | While running | On screen |
|---|---|---|---|
| DOCUMENT | the element holding the chapters | that same element | the document |
| TITLE | a heading written in a chapter | that same element, in document order | the title, and its number counted by the stylesheet |
| ENTRY | nothing | a list item holding a link | a line of the table of contents |
An entry carries the level of its title as a class, and the mention that its chapter is left out of the numbering. That is the one thing a stylesheet cannot read from the table itself, the entry standing far from the chapter it belongs to.
An anchor is written before each title, and the entry leads to it rather than to the title: an anchor takes no room and changes nothing to what the author wrote.
MOpT: where the code goes
| Module | What it does | Procedure |
|---|---|---|
| numbering | Counts the chapters, the sections and the sub-sections, and writes their numbers | PF1 |
| table | Reads the titles and fills the table | PF2 |
| panel | Opens and closes the table standing beside the document, and puts what opens it in the navigation | PF2 |
Written where each is: the table and the panel in
wexa_statics/js/extras/book.js, the numbering in
wexa_statics/css/extras/book.css. The numbering holds no
treatment of its own: it counts what is written, and a stylesheet counts.
UML, and where it is written
One class, Book, which carries the table and the panel. The
document and its titles are read where they are written, and are not
carried by classes of their own: nothing is computed on them that would
have to be kept.
The contracts
How to read them
pre is what has to be true on the way in, and what the operation does not check; post is what the caller can count on. The types are the ones written in the JSDoc.
Book
| Operation | Signature | Contract |
|---|---|---|
| constructor | (id_headings, id_toc) | pre: none. post: a document whose place for the table is missing is left alone; a table standing in a panel gets what opens it, in the navigation of the page. Never raises |
| set_html_tags | (tags: String): void | pre: the tags are those of headings. post: the levels taken by the table are those tags, h1 to h4 having been taken until then |
| del_html_tags | (tags: String): void | post: those levels are no longer taken |
| fillTable | (only_numerate_headings: Boolean): void | pre: none. post: one entry per title of the levels taken, in the order of the document, each saying its level and whether its chapter is numbered, and leading to an anchor written before its title. Nothing is produced when there is no place for the table |
What is tested, and where
With a document
Book reads a document and writes in it, so it is checked on
written markup: the entries follow the order of the titles, an entry says
the level of the title it names, a chapter left out of the numbering gives
an entry that says so, and a document without a place for the table is left
untouched.
The tests are in wexa_statics/js/tests/, one file per class, and
are run by tests.html.
What no test covers
The numbering, which a stylesheet counts, and what a printed page does with a chapter. Both are read on a page, and neither is asserted.