In short

A document writes its BibTeX entries and its text. When its page opens, the browser reads the entries, numbers the citations of the text in the order they appear, and builds the bibliography. Nobody runs anything, and nothing is fetched from the internet.

This page is the design of that work: what it does, what it deliberately does not do, the decisions that explain the code where it surprises, and the classes that carry it. Read the section below before reporting a behaviour as a bug: several of them are choices.

Two independent domains

The bibliography lists what the BibTeX data holds. It does not depend on the citations: a page without a single citation gets its table all the same, which is what publications.html shows. The citations, on their side, are numbered even when the page says nowhere to put the bibliography.

What the text owes to a reference, its number and the places it is cited at, is handed to the table from the outside. The table never asks the citations anything.

Left out on purpose

These were written as requirements, then set aside. They are not missing: they were decided against.

Not in the first version

These are established requirements that the code does not write yet. A document that needs them will not get them by trying harder.

Choices that look like limits

• Every author is written, whatever their number. Never "et al.": a bibliography that hides names hides people who did the work.
• Nothing is ever completed from the internet. An entry missing a field is shown with the field missing, and the missing field is made visible.
• An entry whose type nobody planned for is displayed by a fallback template rather than left out.
• A reference that no citation names has no number, and sorts after every reference that has one.

The bibliography

The citations

The numbers

They follow the order the citations appear in the text, in a single sequence for the whole document. The bibliography is built in that order, so it is already the order it prints in.

Why: the column of numbers then gives what no other column gives, the place where a reference is first cited. Reading from one end to the other, the numbers go up, which tells a reader whether a reference is a new one without opening anything. An alphabetical order would give a sequence with no apparent logic.

Where the columns give way

On a narrow screen the number and the year are not shown, and the reference takes the whole width. Nothing else changes: the table stays a table, its columns stay columns, and the reader turns the two of them back on from the column selector the bibliography builds with its search field.

When: whenever the screen crosses that width, and not only when the page opens. A device is turned over and a window is resized without anything being loaded again, and the columns follow. Between two crossings, what the reader checked is left alone: the width decides the default, never the choice.

Why not stack the entry: laying a row out as blocks takes the roles of a table away from it, and a screen reader stops saying which cell it is reading and under which header. Hiding a column costs none of that, and the selector is the component the sortable table is built with.

Why at all: the number and the year are two characters and four characters, but a column asks for a share of the width all the same. Measured on a reference of 413 characters, they take 186 pixels out of 800, leaving 581 to the text, which reads in six lines. On a screen of 400 pixels they take 225 and leave 185, which is a dozen characters a line and a reference thirty lines tall.

Where: at the step of the phone held sideways, and not at the mobile border of the framework. A tablet held upright has the width for the three columns, and hiding them there would waste it.

Counted in what: in font sizes, 38.75 of them, and never in pixels. That is 620 pixels for a text of 16 and 698 for a text of 18, so the columns give way sooner in contrast mode, where the text is written larger. A media query could not do this, its condition being read before any variable is resolved; this threshold is held in JavaScript, which has no such limit.

What this is not: a feature withheld from a small screen. Everything the bibliography does on a wide screen, it does on a phone. Only the columns checked at the opening differ.

The citation in the source

A citation is a span bearing a data-bibtex attribute. Three consequences.

A span is allowed between two words of a sentence, which details is not: a browser closes the paragraph when it meets it, so it cannot stand inside a sentence. The attribute is what tells a citation from a cite element bearing the title of a work. And what is written inside the span is what a reader gets when JavaScript does not run, replaced by the number as soon as it does.

What opens, and what closes

Several contents may stay open at the same time, and none closes on its own: closing what nobody asked to close makes what is being read disappear.

The focus does not move when a content opens, so the page does not scroll; it comes back to the control when it closes, which matters when the closing came from inside the content. Whether a content is open is read on its control, which already declares it for a screen reader: keeping it a second time would make two truths possible.

The addresses

They come from the BibTeX fields, and they are optional. BibTeX has a single URL field; when a second address is needed, NOTE holds it. This is a habit of the house, not a standard, so what an address leads to is never read in the name of its field: it is read in the address itself.

Nothing is ever completed by going to the internet. Data that are well kept do not need it.

The language

Everything the program writes follows the language of the document. The language is read on the element, and is never written in the code. A text that cannot follow it says which language it is in, as WCAG 3.1.2 asks.

What is said to whoever wrote the document

In the console, and nowhere else: a key used twice, a key naming no reference. A reference that is never cited is not worth a message. The reader is told nothing: a bibliography that could not be built is not their doing.

What the data are made of

Two things are computed and never stored: the number of a reference, which is given at its first citation and does not exist for a reference nobody cites, and what an address leads to, which is read in the address.

The way, and why it is written here

Design first, then the tests, then the code. The design is a Merise analysis, from the communication between the actors down to where the code goes, and the UML diagrams that lead to it. It is written here, in full, so that whoever picks the work up has everything on one page.

The working notes are in notes/bibliography/. This chapter says the same thing, and is the one that is kept up to date. The two domains, the bibliography and the citations, are not a starting point: they came out of the operations below.

MCC: who exchanges what

Nothing is ever asked of the internet: a document reads its own data.

MCD: the associations

The entities are in the chapter above. What ties them:

MCT: the eight operations

Op3 does not need Op2: that is where the two domains come from, and publications.html is the proof, a bibliography with no citation at all.

Op8 is not "print" in the strict sense: it removes what only makes sense on a screen, and the browser lays the document on the pages. Laying a composed document on surfaces of fixed height is an operation of its own, and the slides need it too, which is what the slides pagination is about.

Op7 shows nothing by itself. It knows which place is wanted, never what it takes to show it, that depending on the support the document is read on. It therefore produces a request, and the treatment that answers it, reaching a place in the document, is modelled where the supports are, in the slides pagination. C26 and C27 are held by the two together: this dossier names the place, that one shows it. The place named never travels in the address of the page, which holds where the reader stands and nothing else.

Op5 is the only operation a support can take away. What triggers it, a search or a choice of columns, is asked for by whoever reads and acts; an audience does neither. So Op3 composes the bibliography without what triggers Op5 when it composes it in a presentation, and Op5 is then never triggered. What is read on its own stays, the order of a sorted column being written in its header and not only drawn. B26.

Three requirements are not operations: the work gives the same result every time, the bibliography exists before the table of contents is built, and the sentence stays readable when no operation has run.

MOT: where, when, and by whom

In the browser of whoever opens the page. Two moments, and both are requests from the reader: the request for the page, once, and a request inside the page, once per request.

PF1 before PF2 and PF3. PF3 before the table of contents is built. PF2 is not needed by PF3. Nothing is kept from one opening to the next: everything starts again, and gives the same result.

MLD: the tables

• REFERENCE (key, type, BibTeX fields, abstract, bibtex_text)
• AUTHOR (key, place, given_name, particle, family_name, suffix)
• LINK (key, address)
• CITATION (citation_id, place_in_the_text)
• CITED_KEY (citation_id, place_in_the_citation, written_key, key, page_aimed_at)

An author and a link exist only as part of a reference, so they carry its key. The key of a cited key may be empty: what is written may name no reference. Two rules the keys do not hold: a citation carries at least one key, and two citations never share a place in the text.

Not in the tables: the number of a reference, and what an address leads to. Both are computed.

MPD: where each table exists

What the author writes is <span data-bibtex="bigi2022lrec">Bigi, 2022</span>: a span is allowed inside a sentence, the attribute carries the key and tells a citation from a <cite> holding a title, and what is written inside stays readable when no operation has run.

Everything the program writes follows the language of the document, read on the element and never written in the code, which is the WCAG 3.1.2 criterion.

MOpT: where the code goes

The presentation module holds no treatment: it takes nothing in and gives nothing back, it only says what of a built bibliography each support shows. That is why the same bibliography, built once, is read on a page, on a slide and on paper. PF6 and PF7 need no module at all: they are links.

Written where each is: the modules that treat under wexa_statics/js/extras/book/, the presentation module in wexa_statics/css/extras/bibbook.css.

UML, and where it is written

The class diagram is the chapter below, the sequence when the page opens and the states of a consultation are the two chapters after it. The classes that carry the data come from the MLD, those that do the work from the MOpT, one per module. The presentation module has none: it holds no treatment, so there is nothing for a class to do.

What carries the data

Their fields are private and set at construction. Nothing modifies them afterwards, and what they give back is either a string or a copy.

What does the work

Errors

Three levels, and one place that catches.

run() never raises, and is the only place in the program that writes try. An error that is not a BibliographyError is a mistake in the program, and has to be seen.

In order

This is the only moment where the order matters. Everything else happens on a request from the reader.

The citations are numbered before the place of the bibliography is looked for: they are in the text, and the text is there. A document with nowhere to put its bibliography still reads.

read() may ask a server for a file, so run() gives back a promise, and whatever builds the table of contents waits for it. That is what holds C31.

Nothing is kept

Everything starts again at every opening, and gives the same result: the order of the text does not change, so the numbers do not either.

Two states

Activating the control opens it or closes it: clicking, Enter or Space, which a button answers to without anything being written for them. A control placed inside the content closes it too.

What changes nothing

• Opening another content: several stay open at the same time.
• Sorting: it moves rows, it opens and closes nothing.
• Searching: a content left open comes back open with its reference.
• Printing: what opens on a screen does not print, and the state stays.

Rules that hold everywhere

These are worth more than any list of signatures: they say what a caller never has to check.

• A field, a list or a map that is absent gives back an empty string, an empty array or an empty map, never null. The one exception is CitedKey.reference, because a key naming nothing is a case C8 asks to treat apart.
• The fields of a data class are private and set at construction. What they give back is a copy, so nothing outside can change what the BibTeX data say.
• BibtexParser.parse() never raises: an unreadable entry is left aside and said in the console, and the others are parsed all the same.
• CitationIndex.index() never raises, and starts again from nothing at every call.
• BookBibliography.run() never raises, and is the only place that writes try.
• ReferenceDisclosure.open() and close() have no precondition: calling either twice does nothing wrong.

Where a number comes from

The number of a reference is nowhere in the data. It is given at the first citation, taken up by the later ones, and does not exist for a reference nobody cites. It travels from CitationIndex to BibliographyTable in one object, CitedReference, together with the places the reference is cited at, and it travels through BookBibliography: the table never speaks to the citations.

How to read them

+ public, - private, / derived and never stored, {readOnly} does not change after construction, {ordered} the order matters, [0..1] may be absent. 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.

The data classes

field() always giving a string is what lets ReferenceFormatter write no existence test at all.

other exists in LinkKind so that an address nothing recognises is shown all the same, as a plain link. A reference is looked up before a CitedKey is built, never set afterwards.

The working classes

BibtexSource is the only class that knows where the data come from. templates says, for each type, which fields and in which order: changing a display is changing that map, and nothing else.

How an error travels

Three exception classes: BibliographyError, the mother, raised by nobody; MissingBibtexData, raised by BibtexSource.read(); MissingBibliographyPlace, raised by BookBibliography.run(). No other exception is raised by the program.

One handler, on run(). It catches BibliographyError, so both of them in one gesture, writes the message in the console, and ends without undoing what was already built. Anything that is not a BibliographyError is a programming mistake, and has to be seen.

An error in JavaScript must never do worse than the absence of JavaScript: without it the sentence stays readable, and that stays true when the program stops.

Four algorithms, and where they come from

They come from bib-list.js, written in 2008. Its code is not reused; these four readings are, because they are right and they handle what a naive one gets wrong.

What was not taken

bib-list.js converts LaTeX notations through a closed list of thirteen replacements, whose own comment admits it is incomplete, and produces HTML entities where plain characters are wanted. It also erases every brace, which loses the case a {SPPAS} protects.

Here, accents are converted by rule, an accent and a letter, and the braces that protect a case are removed without touching what they protect. A notation nobody knows is left as it was written rather than thrown away.