Repository navigation
Conversation
The tables that list a vocabulary are written by hand, and they had drifted: the site said four themes shipped when five did, its error page said it listed every exception the package throws and left five of them out, and the Word options table was on two pages and the two copies already differed. Every vocabulary is now read out of the library that owns it and compared with the page that carries it, in both directions. A page says which of its blocks is the list of what by marking it, and a second copy of a list is a failure as well: two copies drift apart and the one nobody reads is the one that is wrong. The drifted claims are corrected, and the tables that were in two places are in one now.
A table can be checked against the code and a sentence cannot: the counts, the claims of completeness and the rules a page states are prose, and a prose claim is correct only until the code moves. The suite in tests/ asks the code how many there are and the page how many it says, checks a page that claims to list every exception against the classes the package throws, and checks the rules against the library that has to behave that way. The phrases that were wrong and have been corrected go into the FORBIDDEN map, which now covers the whole site and not only the command-line pages: a sentence that was wrong is wrong wherever it is written, and the pages that drifted most were the ones nothing was checking.
The workflow built the site with npm run build, which renders "This example did not build" into the page and succeeds anyway: a broken example was a green build. The strict build is the one that is asked for now, and the two checks that keep the pages true of the code run beside it.
The index of the site is a template, and a template carries a page's summary in the page it builds from — so a phrase that was wrong is looked for in the Markdown and in the templates that render it.
The frontmatter keys of the Word half are open-ended — the library validates two of them and reads the rest — so there is no list of them to check a page against. The options, the style slots and the themes are.
Both halves can write a word in a style of its own, and the syntax and the attributes are the same in the two. The page that explains how a directive works is where the shared vocabulary belongs, and the eight attributes are a vocabulary the reference check reads out of both halves and holds to one list — so a half that grew a ninth attribute is caught rather than documented.
An inline directive in a deck is a text style, so every one of them is either a name the theme has or a build that stops with the styles it has named. The page says so, and the claims check it: the refusal, the message, the theme's file, and the three forms the raw one takes. The example is the raw form, because no theme that ships carries named styles yet — the named one is proved by a theme of the test's own.
A name the theme does not have, a label that holds Markdown, an attribute nobody reads — each of them reaches the document as the characters the author typed, because a sentence and a parser nobody asked to change should not change the syntax of every document converted after it. The round trip keeps the word and loses the style, and the page says so: a style is written as direct formatting, and the reader reads bold, italic and strike and no colour.
Three directives and not two, three methods on the renderer and not two, and the exception a theme naming a face there is no table for — each of them a count the code is asked about, and each of them now checked. The index pages carry the inline directive as well, because a deck's dialect now has one and the index is where the dialect is listed.
Three sentences were wrong and have been corrected: the round-trip page's count of what does not survive, the Word index's count of the directives, and the presentation index's count of the renderer's methods. A count that was wrong once tends to come back, because the code moved on and the sentence did not — so the phrases are here, and a page that says one again is a failure.
The reference tables are read out of the libraries and compared with the pages that carry them, and a vocabulary the two halves share is read out of both of them and held to one list — so the attributes an inline style takes are the same eight in the deck and in the document.
A word in a named style comes back as the word, without the style and without the colour it was drawn in, and the package's own list of what does not travel now says so. The index summarised that list, and the summary was one item short.
A template is the furniture of a deck — the wordmark, the rule, the page number — written once and drawn on every slide that names it. It is a slide of the deck's own Markdown whose frontmatter names a template and nothing else, and it is not a slide of the deck: it is not drawn, it has no number, and it does not count towards the number of slides. Four things decide what one is, and the pages now say them: the body holds chrome and nothing else, a slide may name several templates, `layout:` and `template:` are independent, and the deck's own templates override the imported ones of the same name. A template may also live in a file beside the deck, named with `chrome:` in the deck's own frontmatter. `::slide-number` is a shape like any other, and `of=true` writes the number of the deck after the number of the slide. A rule is a sentence rather than a name, so each is checked against the library that has to behave that way: a definition that is drawn, a template that holds a heading, a chrome file that is not there, an imported template the deck overrides, and a page number that is the number of the deck.
Seven directives place objects in a document: a picture, a caption, a page break, a section, a floating box, a shape and a form field. The Word half never refuses — a directive a writer cannot express is given the author's own characters back and the loss is reported — so the pages say which format carries what, and the round trip says what comes back of each. The reference table carries the ten names the library draws, and a new vocabulary carries the four features a format cannot hold for them, read out of the class that names them. A caller that builds its own registry draws fewer than ten, and the page says so: the handlers that are not given are not drawn, and a conversion through `MarkdownToWord` hands over all of them.
Ten sentences were wrong and have been corrected: the counts of the frontmatter keys, the free shapes and the Word directives, the two examples that claimed to use every frontmatter key, the claim that the container form of a drawn name is claimed rather than drawn, and the snippet that read a loss by two methods it does not have. A count that was wrong once tends to come back, because the code moved on and the sentence did not — so the phrases are here, and a page that says one again is a failure.
The reference tables are read out of the libraries and compared with the pages that carry them. A vocabulary joins them: the features a Word format cannot carry, which the pages list beside the directives they belong to.
Contributor
Author
|
Consolidated into #15, on the branch |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The site's tables of names are written by hand, and they had already drifted. This makes them generated from the code and adds a test suite for the prose.
What drifted, and is now checked
pitchwas missingtools/check-reference.phpnow reads 17 vocabularies and 181 names out of the class that owns each one, and compares the page that carries it — in both directions. A documented name the code does not have, and an existing name the document does not list, are both failures.And the rule extends past the site: a vocabulary may be read out of both halves and compared with each other, so a half that grew a ninth attribute is caught in the deck and in the document.
The claims, which a table cannot carry
tests/Claims/holds the prose claims as tests — the counts, the completeness, the rules. Every one fails againstmain, becausemainpredates the features they are about.Three were already waiting on this work and are now real tests rather than pending ones: "refuses a note that is closed but is not last, and says why", "says how the attributes of a shape are separated", and "finds a theme that sits beside the deck" — the last of which is REVIEW.md §8, from before this work began.
What this pull request adds to the site
The slide templates and
::slide-numberin the slides half, and the seven object directives in the Word half, with a loss matrix saying what ODT and RTF cannot carry. The three new exceptions listed. The frontmatter key set now nine, the free shapes thirteen, the Word directives ten.The order of the merges
This pull request must be merged last. The site's continuous integration checks the libraries out from
main, so the reference checks compare the pages against libraries that do not have the templates, the object directives or the text styles until those pull requests are merged. Merge the two libraries first.Three things the writing turned up
The site was wrong about
:::toc, and so was a snippet. It said the body of a container is "silently dropped" — nothing is claimed, andDocumentRendererdraws the body as ordinary Markdown with the fence gone. Andcontent/general/errors.mdshowed aLossby two methods it does not have:MarkdownWord\Losshas public properties, so the snippet was a fatal error. It was wrong onmaintoo, before this work. Both are corrected, and the old phrasings are in theFORBIDDENmap so they cannot come back.The deck's own frontmatter is the first slide's — so a deck that opens with a
---block and then another---gets an empty first slide, andchrome:has to be on the slide that opens the deck. The site now says so.And a bug in the Word half, not in the documentation: the Word README's format table says a table's column alignment is "carried | dropped | carried", and the ODT really does drop it — but
Format::Odt::drops()does not list it, sopendingLosses()says nothing. A reader who aligns a column and converts to ODT loses it in silence. That is a library fix and it is not in this pull request; it is reported there.