User manual

Not written yet. This chapter is the help of the person who annotates: what the page shows, how an annotation is chosen and set, what is done to the files, and what is read of what came of it.

Developer manual

Not written yet. This chapter is for whoever reads or changes the code: how it is organized, what the page is made of, the events it answers, and the stylesheets.

Modeling

Problem and scope

Description

SPPAS annotates: it takes the files of a person and writes, beside them, what it found in them — the words, the sounds, the syllables, what was said at the same time as something else. What it can find is not one thing but a score of them, each with its own languages, its own configuration and its own needs.

The application "Annotate" is what stands between a person and those annotations. It shows the annotations which can be performed, lets them be selected and configured, performs the selected ones on the files, says what came of each, and keeps what it said so that it can be read again. It annotates nothing itself.

The annotations are not independent of one another. The phonetization needs the text normalization, the alignment needs the phonetization. Every annotation declares what it requires; what is missing is a place where a person can see it. A score of annotations offered as a flat list is a list one gets lost in.

"Annotate" is the page "Annotate" of the desktop interface of SPPAS, brought to the web. A person who knows the one must find her way in the other: the same steps, the same lists, the same report. What differs is how the files are given and how what was produced is reached, because a web page does not read the disk of the person who looks at it.

"Annotate" belongs to the SPPAS ecosystem and relies on its automatic annotations, which it never exposes. It is available both as a page of the SPPAS Dashboard and as an online application, addressing the same need in two contexts of use: within a working session on a local corpus, or as an occasional service.

Accessibility is treated here as a functional requirement rather than an added quality: what "Annotate" exposes — what an annotation does, whether it can be selected, how far the annotations have gone, how each of them went — is of no use if it is not perceivable.

Defining the needs

Problem statement and objectives

Performing automatic annotations raises a difficulty which is not technical: the user has to decide, before anything happens, which annotations to perform, in which language, with which configuration and into which file formats — among a score of annotations whose names say little to whoever did not write them. The decision is taken on a list, and the consequences are read afterward, file by file, in a report.

The central problem addressed by "Annotate" is thus:

how to let a user perform, on a set of files, the automatic annotations she selected, in the language and with the configuration she fixed, and read what came of each of them, without requiring any knowledge of how an annotation works.

This problem is sharpened by the conditions of use. Annotating is a batch operation: several annotations are performed, one after another, on a set of files whose contents are not examined when the user decides. It is also a long operation, and nothing can be undone: what an annotation wrote is written. "Annotate" must therefore let decisions be taken once and applied to every file, show how far the annotations have gone while they are performed, and remain accountable for each annotation and each file.

The objectives follow:

  • to let the user choose the output file format of every kind of file which is produced;
  • to let the user fix the language of the annotations, and another one for a given annotation;
  • to let the user find her way among the annotations, know what each one does and what it requires, select the ones to perform, and configure them;
  • to perform every selected annotation at one go on the files the user delimited, and to show how far it has gone;
  • to report what happened, annotation by annotation and file by file, and to keep the reports so that they are read again, or deleted;
  • to give the user access to the files which were produced, in a manner adapted to the context of use;
  • to guarantee accessibility, of the interface and of the information it exposes;
  • to remain the page the users of the desktop interface know.

"Annotate" does not aim to say what an annotation does or how: that is established in the API of SPPAS, whose classes are read here and not modeled. It does not aim to select the files, which are given by the provision of files, nor to show and check the options of an annotation, which is the service of the options'. What is left is the annotations as a set: which can be performed, which are selected, what they are performed with, and what came of it.

Expressing the needs

Choosing the output file formats

An annotation does not write one kind of file: what is produced is annotations, and it may be a sound, an image or a video as well. The user chooses one extension for every kind of file which can be produced, among those SPPAS is able to write for that kind; a default one is already selected, so that nothing has to be chosen by whoever has no preference.

Fixing the language

Most annotations need language resources, and a corpus is usually in one language. The user fixes it once, and every annotation which has resources for that language takes it. An annotation which has none is left without a language, and the user gives it another one on its own line. When the selected annotations do not all have the same language, the page says so rather than showing one of them.

Finding, selecting and configuring the annotations

The annotations are shown in three lists, one per type: those which take one file on its own, those which take two files of one speaker, and those which take two files of two speakers. From the main page, the user sees at once which lists hold a selected annotation.

In a list, each annotation says what it does, and gives the way to the published work it rests on — or, where there is none yet, how far its development has gone. It says what it requires, and the list is arranged so that an annotation comes after the ones it requires. Every annotation is shown, including the ones which cannot be selected on that machine: they are disabled and not hidden, so that two users have the same page, and what differs between them is what is installed.

Selecting an annotation selects no other. The user configures an annotation before it is performed, and what she fixed is kept as long as she stays on the page.

Delimiting the set of files to annotate

The files to be annotated come from the working context, not from the tool: in a working session, they are the files currently selected in the workspace; in an occasional use, they are the files the user brings to the tool. The requirement is the same in both cases — the user delimits a set, "Annotate" operates on that set, and none of its files is altered. The two contexts differ only in their material constraints, an occasional use being bounded by what a service can reasonably receive.

Performing the annotations, and following them

One gesture performs every selected annotation on the delimited files. The user may ask, before it, for one file gathering everything which was annotated for each file, to open it in an annotation editor. While the annotations are performed, the page says which one is being performed and how far it has gone, and nothing else can be started: there is one performance at a time.

Reading the procedure outcome report

The annotations are a series of operations sharing the same decisions. Some succeed, some do not, for reasons belonging to one annotation or to one file. The report is written while the annotations are performed, line by line, each line carrying how what it is about went. It is therefore readable whatever happened, including when the performance stopped before its end. The user reads it when the annotations have been performed, and reads again the reports of the previous ones; she deletes the ones which are of no use any more.

Reaching the produced files

Annotations which produce files the user cannot find have annotated nothing. In a working session, the produced files join the workspace and remain available to the following operations. In an occasional use, they are handed back to the user. The requirement is that the outcome be reachable without the user having to know where the tool put it.

Accessibility

Everything above rests on information being exposed: descriptions, languages, states, progress, reports. Contrast, legibility, text alternatives to any graphical encoding — an annotation which is selected, a line of a report which is an error —, keyboard operation and consistent terminology between the interface and the concepts are conditions of the tool working at all. On a web page, what is being decided and the list of the reports do not always fit side by side: the user says whether she sees the one, the other, or both.

Conceptual level

Requirements

The previous sections state what users need and why; this section states what the system does to answer it, and what it manipulates in order to do so.

Two markers are used throughout. [API-OK] denotes what is achievable with the current SPPAS API. [API-EXT] denotes what requires an extension of that API. A requirement marked [API-EXT] is part of the model; it remains inactive until the API supports it.

Concepts manipulated by the application

The data dictionary of this application. Thirteen concepts, and the model below names no other.

D1. Annotation
One automatic annotation SPPAS is able to perform. What it declares of itself — its name, its description, its types, its languages, its options, its references, how far its development has gone, what it requires — is written in the API and read from there.
D2. Type
What an annotation takes: one file on its own, two files of one speaker, or two files of two speakers. An annotation has one type or several.
D3. Selected annotation
An annotation the user decided to perform.
D4. Language
The language an annotation is performed in, among those it has resources for, or none. An annotation which has no language resource has no language.
D5. Kind of output file
What an annotation produces: annotations, and possibly a sound, an image or a video. Each kind is written with one extension.
D6. Output extension
The extension chosen for one kind of output file, among those SPPAS is able to write for that kind.
D7. Configuration
The values given to the options of one annotation.
D8. Requirement
An annotation which has to have been performed before another one.
D9. Merge option
A decision of the user: whether one file gathering everything which was annotated is created for each annotated file.
D10. Batch
The set of files delimited by the user, whose contents are unknown at the time decisions are taken.
D11. Performance
Every selected annotation performed at one go on the batch, with the decisions taken when it was asked for.
D12. Progress
Which annotation is being performed, and how far it has gone. It exists while a performance goes, and nothing of it is kept.
D13. Procedure outcome report
What a performance wrote of itself, line by line, while it went. Each line carries how what it is about went: OK, ERROR, WARNING, INFO or IGNORED. It is a file, and it is kept until it is deleted.

The language of the page, and the language of an annotation

There are two places where a language is fixed, and the second one exists because of the first.

The language of the page is chosen in one list, which holds every language at least one annotation has resources for, and the entry ---, which is no language. It is --- when the page is asked for. Fixing it gives it to every annotation which has resources for it; an annotation which has resources, but none for that language, is left without a language. An annotation which has no language resource is not concerned. Fixing --- leaves every annotation which has resources without a language.

The language of one annotation is chosen on the line of that annotation, among its own languages and ---. It is where the user gives a language to an annotation the language of the page left without one, and it changes no other annotation.

The list of the page then shows what the selected annotations hold: their language when they all have the same, --- when none has one, and the entry MIX when they do not all have the same. That entry is in the list only as long as it is true.

What an annotation requires

Every annotation declares the ones it requires. The page shows it on the line of each annotation, and each list is arranged so that an annotation comes after the ones it requires [API-EXT]: what requires what is written in the declarations, and the annex states what reading it asks of the API.

What is shown is not what is done. Selecting an annotation selects no other: one annotation is performed, what it wrote is corrected by hand, and the next one is performed on the corrected version. Selecting what an annotation requires in its place would perform the whole chain on what was not corrected.

The order in which the selected annotations are performed is the API's, and this application neither chooses it nor changes it.

The reports

Each performance writes one report, under a name no report bore before. The reports which are kept are listed beside the six steps, and one of them at most is checked: checking one unchecks the other. The report of the performance which has just ended is added at the top of the list, and checked.

Three things are done with that list: the checked report is shown; the checked report is deleted; every report which is not checked is deleted. Showing is offered only when a report is checked and its file is still there.

A report which is shown begins with the name of its file. Its lines are shown as they were written, and the state each of them carries is shown as what it is.

Online, there is no list of reports. The report of a performance is written where the files the user sent stand, with everything which was produced: it is one of the produced files. It is shown when the annotations have been performed, as it is locally; it is downloaded on its own, and it is in the archive which brings every produced file back at once. No report of a previous performance is kept for a given user, so there is nothing to list, to check or to delete: online, the panel of the reports is collapsed.

Organizing the needs

[010] Starting
  • [011] The user can initiate the automatic annotation of a set of files.
  • [012] The system initializes the page with the default extension of every kind of output file, no language, no annotation selected, the merge option off, and no batch.
[020] Understanding the process
  • [021] The system presents six steps, in this order: choose the output file formats, fix the languages, select and configure annotations, add files, perform the annotations, read the procedure outcome report.
  • [022] The system states what is missing before the annotations can be performed.
[030] Controlled progression
  • [031] The system allows the annotations to be performed only if at least one annotation is selected and the batch is not empty.
  • [032] The system performs one set of annotations at a time: nothing can be started while a performance goes.
[100] Output file formats
  • [101] The user can choose one extension for each kind of output file.
  • [102] The system restricts the choice to the extensions it is able to write for that kind.
  • [103] The system offers no choice for a kind which has no extension.
  • [104] The system holds the default extension of a kind until another is chosen.
[200] Languages
  • [201] The user can fix the language of the page, among every language at least one annotation has resources for, or none.
  • [202] The system gives the language of the page to every annotation which has resources for it, and leaves without a language an annotation which has resources but none for it.
  • [203] The user can fix the language of one annotation, among its own languages, or none.
  • [204] The system shows the language the selected annotations hold: the one they share, none, or that they differ.
[300] Annotations
  • [301] The system presents the annotations in one list per type; an annotation which has several types is in each of their lists.
  • [302] The system shows, for each type, whether at least one of its annotations is selected.
  • [303] The system presents, for each annotation, its name and its description.
  • [304] The system presents, for each annotation, a way to each of its references, telling a document from a web page; where it has none, how far its development has gone, when that is known; and nothing otherwise.
  • [305] The user can select an annotation, or take the selection back.
  • [306] Selecting an annotation selects no other.
  • [307] The system shows what each annotation requires, and arranges each list so that an annotation comes after the ones it requires [API-EXT].
  • [308] The system shows every annotation, and disables the ones which cannot be performed on that machine.
  • [309] The user can configure an annotation: its options are shown with their values, and what was fixed is kept or given up.
  • [310] The system keeps the decisions taken for as long as the user stays on the page.
[400] Batch
  • [401] The user delimits the set of files to annotate.
  • [402] The system operates on that set and alters none of its files.
  • [403] The system reports when the set is empty.
[500] Performing
  • [501] The user can ask for one file gathering everything which was annotated.
  • [502] The system performs every selected annotation on the batch, in the order of the API.
  • [503] The failure of one annotation never interrupts the others.
  • [504] The system names the report of each performance so that it replaces no other.
  • [505] The system shows which annotation is being performed, and how far it has gone.
[600] Reading the report
  • [601] The system shows the report of a performance when it has ended.
  • [602] The system shows the name of the file of the report which is read.
  • [603] The system shows each line with the state it carries.
  • [604] The system says so when a report cannot be read.
  • [605] Online, the user can download the report which is shown.
[700] Managing the reports
  • [701] The system lists the reports which are kept.
  • [702] The user can check one report at a time; the report of the performance which has just ended is checked.
  • [703] The user can show the checked report; the system offers it only when a report is checked and can be read.
  • [704] The user can delete the checked report.
  • [705] The user can delete every report which is not checked.
  • [706] Deleting a report deletes nothing of what was produced.
  • [707] Online, the system lists no report, and the panel of the reports is collapsed: [701] to [706] hold locally.
[800] Reaching the results
  • [801] The system makes the produced files reachable to the user.
  • [802] The system makes them reachable without the user knowing where they were written.
  • [803] Online, the report is one of the produced files, and the user can download every produced file at once.
[900] Restarting
  • [901] The user can annotate another batch: the provision of files starts over, and the decisions are kept.
  • [902] The user can reset the page: the decisions and the provision of files are taken back to what they were on arrival.
[1000] UX and accessibility
  • [1001] The system provides text alternatives to any graphical encoding: an annotation which is selected, a type which holds a selected annotation, the state of a line of a report.
  • [1002] The system uses consistent terminology between interface and concepts, and the terminology of the page of the desktop interface.
  • [1003] The system is operable by keyboard and by screen reader.
  • [1004] The system provides explicit messages at every decision point.
  • [1005] Choosing an extension, fixing a language or selecting an annotation replaces nothing on the page and never moves the focus.
  • [1006] The user can show the six steps, the reports, or both; online, the reports are collapsed.

Conceptual model

Annotate holds no data of its own but the reports. Everything else it manipulates belongs to one performance being decided, and is derived from a small number of user decisions. This section states who it exchanges with, which data exist, what produces them, and on which event each treatment runs.

Conceptual model of communication

Four actors border Annotate, and only one of them is a person. Three are neighbouring systems.

Actors
  • A1. The user — she chooses the output extensions, fixes the languages, selects and configures annotations, asks for them to be performed, follows them, reads the report, reaches what was produced, and manages the reports.
  • A2. The provider of files — it hands Annotate a workspace holding the files to be treated, possibly empty, in both contexts of execution, and it is told what Annotate takes, gives back and produced. It is the domain of the provision of files, and the batch is what it hands.
  • A3. The API of SPPAS — it says which annotations there are and what each declares, which extensions each kind of output file can be written with, it performs the selected annotations, says how far it has gone, writes the report, and names the report of each performance.
  • A4. The service of the options — it shows the options of one annotation and gives back the values which were fixed.
Flows
  • F1. A3 → Annotate — the annotations, and what each declares of itself; the kinds of output file, the extensions of each and its default one.
  • F2. Annotate → A1 — the six steps; the extensions of each kind; the languages; the annotations in one list per type, each with its name, its description, its references or how far its development has gone, its languages, what it requires, and whether it can be performed on that machine [021], [102] to [104], [201], [301], [303], [304], [307], [308].
  • F3. A1 → Annotate — the extension of one kind of output file [101].
  • F4. A1 → Annotate — the language of the page [201].
  • F5. A1 → Annotate — an annotation selected, or a selection taken back [305].
  • F6. A1 → Annotate — the language of one annotation [203].
  • F7. Annotate → A1 — which types hold a selected annotation, and the language the selected annotations hold [204], [302].
  • F8. Annotate → A4 — the options of one annotation, to be shown and fixed [309].
  • F9. A4 → Annotate — those options, with the values which were fixed, or that nothing was [309].
  • F10. A2 → Annotate — the batch: the workspace holding the files to be treated, possibly empty, files_for_app(); and that the person said it is ready, is_ready() [401].
  • F11. Annotate → A1 — what is still missing before the annotations can be performed [022], [403].
  • F12. A1 → Annotate — the merge option [501].
  • F13. A1 → Annotate — perform the annotations [031].
  • F14. Annotate → A3 — a name for the report of this performance [504].
  • F15. Annotate → A3 — what is to be performed: the annotations with what was decided on each, the output extensions, the batch, the name of the report, and the merge option [502].
  • F16. A3 → Annotate — which annotation is being performed, and how far it has gone.
  • F17. Annotate → A1 — the same [505].
  • F18. A3 → Annotate — the annotations have been performed: the batch, holding what was produced, and the report, written.
  • F19. Annotate → A2 — the files it takes and gives back while the annotations are performed, lock() and release(); what was produced, in the workspace it was handed, produced(); and that it has finished [801], [802].
  • F20. Annotate → A1 — a report: the name of its file, and its lines with the state each carries; or that it cannot be read; online, a link to download it [601] to [605].
  • F21. Annotate → A1 — locally, the reports which are kept, and the one which is checked [701], [702], [707].
  • F22. A1 → Annotate — a report checked; show the checked report [702], [703].
  • F23. A1 → Annotate — delete the checked report, or every report which is not checked [704], [705].
  • F24. A1 → Annotate — annotate another batch [901].
  • F25. Annotate → A1 — the produced files, reached without her knowing where they were written: online, the address of one archive holding all of them, the report included [801] to [803].
  • F26. A1 → Annotate — reset the page [902].

F15 carries the whole of what was decided, and not one annotation. The API performs what was selected, in its own order: this application chooses no order and imposes none [502]. What it reads of the requirements, it reads to show [307].

F15 carries a workspace, and not what an annotation reads. Which files an annotation takes among those of the batch is settled between the workspace and what that annotation declares. This application chooses no file, pairs no file and looks for none.

Nothing is written into what an annotation declares. A language fixed on an annotation, an annotation selected, an option configured: all of it is held for the performance being decided, and the declaration is what it was.

What goes to A2 is said of the workspace made for Annotate, and never of the one of the person, which never leaves that domain [402].

Conceptual model of data

Eight classes. Three are read from a neighbor and appear here with their identifier and nothing else; four belong to one performance being decided; one is what stays.

The classes of entities
ClassPropertiesWhat it is
ANNOTATION# annotationOne annotation SPPAS is able to perform (D1). What it declares is read from the API
KIND# kindOne kind of output file (D5). The extensions it can be written with are read from the API
FILE# fileOne file of the batch (D10). It is exposed by A2, and this domain holds its identity and nothing else
PERFORMANCE# performance, mergeWhat is decided, then performed at one go (D11), and the merge option (D9)
SELECTION# performance, # annotation, languageOne annotation which is to be performed (D3), and the language it is to be performed in (D4)
EXTENSION# performance, # kind, extensionThe extension the files of one kind are written with (D6)
VALUE# performance, # annotation, # option, valueThe value fixed for one option of one annotation (D7)
REPORT# reportWhat a performance wrote of itself, kept so that it can be read again (D13)
The relations
No.VerbLeg 1Leg 2
R1is decided inSELECTION (1,1)PERFORMANCE (0,n)
R2selectsSELECTION (1,1)ANNOTATION (0,n)
R3is chosen inEXTENSION (1,1)PERFORMANCE (1,n)
R4is the extension ofEXTENSION (1,1)KIND (0,n)
R5is fixed inVALUE (1,1)PERFORMANCE (0,n)
R6configuresVALUE (1,1)ANNOTATION (0,n)
R7is annotated byFILE (0,n)PERFORMANCE (0,n)
R8was written byREPORT (0,1)PERFORMANCE (0,1)
R9requiresANNOTATION (0,n)ANNOTATION (0,n)

R1, R3 and R5 are aggregations: a selection, an extension and a value exist only inside the performance they were decided for. R1 and R2 together identify a selection: an annotation is selected once and not twice.

The language is on the selection and not on the annotation. The language of the page is not a property of anything: it is a gesture which writes the language of every annotation concerned [202], and what the page shows afterward is read on the selected annotations [204].

A value is tied to an annotation and not to a selection. An annotation is configured whether it is selected or not, and what was fixed stays when the selection is taken back.

R8 reads (0,1) on both sides. A performance which was not asked for yet wrote no report; a report is read long after the performance which wrote it, which is gone. A report is identified by itself.

R9 is read and never written. It is what the annotations declare, and it is used to show [307]. It orders no performance.

A performance holds no file. R7 is a relation and not a holding: the batch is exposed by A2, and what this domain knows of a file is its identity [402].

Computed, and never held
  • The annotations of one type, which are those whose declaration names that type [301].
  • Whether a type holds a selected annotation [302].
  • The languages of the page, which are every language at least one annotation has resources for [201].
  • The language the selected annotations hold: the one they share, none, or that they differ [204].
  • The arrangement of a list, which follows from R9 [307].
  • Whether an annotation can be performed on that machine [308].
  • What is still missing before the annotations can be performed: an annotation selected, a batch which is not empty [031].
  • The progress, which the API says while it works [505].
  • The files produced, which stand where the API wrote them.
What one performance carries, in the words the code will use
  • extensions — one extension per kind of output file.
  • selected — the annotations which are to be performed.
  • lang — the language of each annotation, or none.
  • options — the values fixed for the options of each annotation.
  • merge — boolean.
  • batch — a set of files, possibly empty.
  • report — the name of the report this performance writes.
  • progress — which annotation is being performed, and how far it has gone.

Their dependencies, which the treatments below turn into events:

  • language of the page → lang
  • (selected ∧ lang) → what the page shows of the languages
  • (batch ∧ selected ∧ lang ∧ options ∧ extensions ∧ merge) → report, produced files
What is not modeled, and why
  • What an annotation declares of itself, which is the API's: it is read where it is written, and nothing here adds to it.
  • The options of an annotation and what a value may be, which the service of the options shows and checks. What is held here is the values which were fixed.
  • The files of the batch beyond their identity, which are A2's [402].
  • What a report says, which is written by the API. This application shows its lines, and the state each carries, as they stand.
  • The order of a performance, which is the API's [502].

Conceptual model of treatments

Thirteen treatments. Six are the decisions, one is the batch, two are the performance and what it produced, two are the reports, and the last two start again. Each one says on which event it runs, what it does, and under which condition each of its results is emitted.

The events
No.EventKindComes from
E1The page is asked forexternal[011]
E2The user chooses the extension of one kind of output fileexternalF3
E3The user fixes the language of the pageexternalF4
E4The user selects an annotation, or takes a selection backexternalF5
E5The user fixes the language of one annotationexternalF6
E6The user asks to configure an annotationexternalF8
E7The batch is exposedexternalF10
E8The user asks for the annotations to be performedexternalF13
E9The annotations have been performedinternalT08
E10The user asks to show the checked reportexternalF22
E11The user asks to delete reportsexternalF23
E12The user asks to annotate another batchexternalF24
E13A decision has changedinternalT02 to T07, T12, T13
E14The user resets the pageexternalF26

E13 is the event the page turns on. Every treatment which takes a decision emits it, and what the page shows of the decisions is said again: which types hold a selected annotation, the language the selected annotations hold, and whether the annotations can be performed [022]. No treatment is written for that announcement: it is a result of each of them.

Nothing here waits for two events. T08 is the only treatment with a condition on its synchronization, and that condition is read on the data it already holds.

T01 — Present the annotations
  • Event: E1.
  • Purpose: show what can be decided, and in which order.
  • Inputs: what the API declares (F1); the reports which are kept.
  • Outputs: the six steps, the lists of annotations, the list of reports.
  • Preconditions: none.
  • Postconditions: every decision can be taken.
  • Rules:
    • one list per type, and an annotation which has several types is in each of their lists;
    • what is shown of an annotation is what it declares, and nothing this application wrote;
    • an annotation shows its references, or how far its development has gone when it has no reference and that is known, or neither;
    • an annotation which has language resources shows its languages, and one which has none shows no choice;
    • each list is arranged so that an annotation comes after the ones it requires; one whose requirement is not in the list keeps its place;
    • every annotation is shown, and the ones which cannot be performed on that machine are disabled;
    • a kind of output file which has no extension is not shown;
    • the page starts as [012] says.
  • Emission: F2 and F21, always.
T02 — Choose an output extension
  • Event: E2.
  • Purpose: decide with which extension the files of one kind are written.
  • Inputs: user choice (one extension of one kind).
  • Outputs: extensions.
  • Preconditions: none.
  • Postconditions: extensions are available to T08.
  • Rules:
    • the extension is one the system is able to write for that kind;
    • choosing the extension of one kind says nothing of the others.
  • Emission: extensions, always; E13, always.
T03 — Fix the language of the page
  • Event: E3.
  • Purpose: give one language to every annotation which has resources for it.
  • Inputs: user choice (one language, or none).
  • Outputs: lang, for every annotation which has language resources.
  • Preconditions: none.
  • Postconditions: lang is available to T08.
  • Rules:
    • an annotation which has resources for that language takes it;
    • an annotation which has resources, but none for that language, is left without a language: it is not performed in another one, its selection is not taken back, and it is not disabled;
    • an annotation which has no language resource is not concerned;
    • fixing none leaves every annotation which has resources without a language;
    • selected or not, every annotation is concerned.
  • Emission: lang, always; E13, always.
T04 — Select an annotation
  • Event: E4.
  • Purpose: decide which annotations are performed.
  • Inputs: user choice (one annotation, selected or not).
  • Outputs: selected.
  • Preconditions: the annotation is not disabled.
  • Postconditions: selected is available to T08.
  • Rules:
    • selecting an annotation selects no other, and no other is refused;
    • an annotation whose requirement is not selected is selected all the same: what it finds is what is already beside the files;
    • an annotation left without a language is selected all the same.
  • Emission: selected, always; E13, always; F7, always.
T05 — Fix the language of one annotation
  • Event: E5.
  • Purpose: give an annotation a language which is not the one of the page.
  • Inputs: user choice (one language of that annotation, or none).
  • Outputs: lang, for that annotation.
  • Preconditions: the annotation has language resources.
  • Postconditions: lang is available to T08.
  • Rules:
    • the language is one that annotation has resources for;
    • no other annotation is changed;
    • the language of the page fixed afterward replaces it.
  • Emission: lang, always; E13, always; F7, when that annotation is selected.
T06 — Configure an annotation
  • Event: E6.
  • Purpose: give an annotation the values it is performed with.
  • Inputs: the options of that annotation, with their values.
  • Outputs: options, for that annotation.
  • Preconditions: none; the annotation is selected or not.
  • Postconditions: options are available to T08.
  • Rules:
    • the options are handed to the service of the options, which shows them (F8);
    • what was fixed is taken back when the user confirms, and the values are what they were when she gives up (F9);
    • nothing is judged here: what a value may be is that service's to answer, and what it means is the annotation's.
  • Emission: options, when the user confirms; E13, when the user confirms.
T07 — Delimit the batch
  • Event: E7, which is the person saying the workspace is ready (is_ready()).
  • Purpose: define the set of files to annotate.
  • Inputs: the workspace the provision of files hands, files_for_app().
  • Outputs: batch.
  • Preconditions: none.
  • Postconditions: batch is available to T08.
  • Rules:
    • the batch is delimited by the user, not by the system: it is the files she checked, in the container of the provision of files;
    • the system alters no file of the batch;
    • the batch may be empty, which forbids T08.
  • Emission: batch, always; E13, always; F11 saying the set is empty, when it is [403].
T08 — Perform the annotations
  • Event: E8, and at least one annotation selected and a batch which is not empty [031].
  • Purpose: perform every selected annotation on the batch, and write what happened.
  • Inputs: batch, selected, lang, options, extensions, merge.
  • Outputs: report, progress, produced files.
  • Preconditions: at least one annotation selected; batch not empty; no performance going.
  • Postconditions: the report is written; the produced files are in the workspace which was handed.
  • Rules:
    • the report is named first, under a name no report bore before (F14), and the name of the next one is prepared at once;
    • the whole of what was decided is handed to the API, which performs the selected annotations in its own order (F15);
    • the annotations are performed one after another, and one which fails does not undo the others: what was written before it was written;
    • the API says which annotation it is performing and how far it has gone, and it is shown as it says it (F16, F17);
    • the report is written by the API, line by line, while the annotations are performed;
    • where one file gathering everything was asked for, it is created by the API at the end of its own work;
    • nothing else is started while the annotations are performed [032];
    • the batch is the workspace files_for_app() hands at this request; its files are locked while the annotations are performed, lock(), and released when they have been, release();
    • this treatment alters no file of the batch: what is produced is written beside them and added to the workspace which was handed.
  • Emission: F17, while the annotations are performed; E9, when they have been, whatever each of them did.
T09 — Show the report, and make the produced files reachable
  • Event: E9.
  • Purpose: that the user reads what happened, and reaches what was produced without knowing where it was written.
  • Inputs: report; the workspace which was handed, holding what was produced.
  • Outputs: the report, shown and checked in the list; what was produced, given back to the provision of files.
  • Preconditions: the annotations have been performed.
  • Postconditions: the report of this performance is the one which is read and the one which is checked; every produced file is reachable through the provision of files [801], [802].
  • Rules:
    • locally, the report is added at the top of the list of the reports, and checked [702];
    • it is shown as T10 shows any report, in both contexts;
    • online, the report stands with the produced files and is given back with them: it is downloaded on its own [605], and the provision of files gathers every produced file in one archive, address_of_all(), the report included [803];
    • this application does not say where a file stands: it gives what was produced back to the provision of files, produced(), and says it has finished;
    • this treatment writes nothing and moves nothing.
  • Emission: F20, always; F21, locally; F19 and F25, always.
T10 — Show a report
  • Event: E10, which happens locally only [707].
  • Purpose: read what a performance wrote of itself, the one which has just ended or an older one.
  • Inputs: the checked report.
  • Outputs: the report, shown.
  • Preconditions: a report is checked, and its file is there.
  • Postconditions: the report which is read is the one which is checked.
  • Rules:
    • the name of the file is shown first [602];
    • the lines are shown as they were written, each with the state it carries: OK, ERROR, WARNING, INFO or IGNORED [603];
    • a report is read and not interpreted: nothing is counted from it and nothing is decided from it;
    • a report which cannot be read is said to be not available, with the reason [604];
    • when no report is checked, what was shown is emptied.
  • Emission: F20, always.
T11 — Delete reports
  • Event: E11, which happens locally only [707].
  • Purpose: remove the reports which are of no use any more.
  • Inputs: user choice: the checked report, or every report which is not checked.
  • Outputs: the reports which are left.
  • Preconditions: none.
  • Postconditions: the reports which were named are gone, and the others are untouched.
  • Rules:
    • deleting the checked report leaves no report checked, and nothing to show;
    • deleting every report which is not checked keeps the checked one;
    • a report which cannot be deleted is said so, stays in the list, and the others are deleted all the same;
    • nothing of what a performance produced is deleted with its report [706].
  • Emission: F21, always.
T12 — Annotate another batch
  • Event: E12.
  • Purpose: annotate other files, with the decisions already taken.
  • Inputs: user choice.
  • Outputs: batch, undefined; extensions, selected, lang, options and merge, as they were.
  • Preconditions: no performance going.
  • Postconditions: no batch, and the decisions are those the person had taken.
  • Rules:
    • the provision of files is asked to start over, start_over();
    • the reports are not touched;
    • nothing of what was written on disk is undone.
  • Emission: F11, always; E13, always.
T13 — Reset the page
  • Event: E14.
  • Purpose: take the page back to what it was on arrival, in one gesture. It is the other end of T12: this one puts back what that one keeps.
  • Inputs: user choice.
  • Outputs: extensions, selected, lang, options and merge, as they were on arrival at the page [012]; batch, undefined.
  • Preconditions: no performance going.
  • Postconditions: the decisions are those the page arrived with, and there is no batch.
  • Rules:
    • the provision of files is asked to start over, start_over(): a person who resets the page does not keep the files she had given it;
    • the reports are not touched;
    • nothing of what was written on disk is undone.
  • Emission: F2, always; F11, always; E13, always.

Organizational level

Organizational model of treatments

One procedure per treatment, numbered as it is. There are two contexts of execution and one organization: what differs between the local server and the wsgi service is who exposes the batch and where the reports stand, and nothing of what is done. Annotate is served by the two, which is why there is one table and not two.

PFWhat it doesTriggered byIn chargeWhereWhenNature
PF1 (T01)Presents the annotationsE1the serverthe serverwhen the page is asked forautomated
PF2 (T02)Chooses an output extensionE2the userthe browserwhenever she chooses one; it is sent with the performanceconversational
PF3 (T03)Fixes the language of the pageE3the user, among the languages the server wrote in the pagethe browserwhenever she fixes it; it is sent with the performanceconversational
PF4 (T04)Selects an annotationE4the userthe browserwhenever she selects one or takes it back; it is sent with the performanceconversational
PF5 (T05)Fixes the language of one annotationE5the userthe browserwhenever she fixes it; it is sent with the performanceconversational
PF6 (T06)Configures an annotationE6the service of the optionsas that service saysbefore a performance, as often as she wantsconversational
PF7 (T07)Delimits the batchE7the provider of files, and never Annotateoutside this applicationbefore Annotate is reached locally; when the files are given, onlineautomated
PF8 (T08)Performs the annotationsE8the server, then the APIthe serverwhen she asks, and only thenautomated
PF9 (T09)Shows the report, and makes the produced files reachableE9the server, then the provider of filesthe server, then her machineas soon as the annotations have been performed, then when she followsautomated, then conversational
PF10 (T10)Shows a reportE10the serverthe serverwhen she asks, locallyconversational
PF11 (T11)Deletes reportsE11the serverthe serverwhen she asks, locallyconversational
PF12 (T12)Annotates another batchE12the serverthe serverwhen she asksautomated
PF13 (T13)Resets the pageE14the serverthe serverwhen she asksautomated

Four procedures end in the browser, and they are four gestures. The extension picked, the language of the page fixed, the annotation selected, the language of one annotation fixed: each of them keeps or shows what the server already wrote in the page, and sends nothing. The languages of every annotation were written by the server in the choice of that annotation; fixing the language of the page sets each of those choices to that language where it holds it, and to --- where it does not. Which types hold a selected annotation, and which language the selected annotations hold, are read on those same fields. Nothing of what she is reading is replaced while she decides [1005]. What she decided is sent once, with the performance. RO1, RO8

PF7 is in nobody's charge here. The batch is exposed by a neighbor in both contexts, and this application reads it. It appears in this table so that the one procedure Annotate does not perform is written down. RO4

PF8 is the only long procedure, and it is followed. The request which asks for it starts the annotations on the server, in a thread, and answers at once; the page is not reloaded. It is what the Setup does with the installation of the features. The API is given something to say where it is — a progress, as every long operation of SPPAS is given one — and it sets on it which annotation it is performing and how far that one has gone. The page then asks, at regular intervals, where the performance stands, and is answered what that progress holds: a percent, a header and a text. A progress bar says it. When the hundred is reached, the page asks for the results, and what the server wrote replaces what was shown: the report, and the container of the provision of files. RO5

PF10 and PF11 exist locally only. Locally, the reports stand in the folder of the logs of SPPAS, where every performance of that machine wrote its own, and the list is theirs. Online, the report of a performance is written in the place the provision of files made for what the person sent, and it is one of the produced files: it is shown by PF9, downloaded with them, and it lasts as long as they do. RO7

What the user acts on

Client-side triggers

  • Choosing the extension of one kind of output file
  • Fixing the language of the page
  • Showing the list of the annotations of one type, and coming back from it
  • Selecting an annotation, or taking the selection back
  • Fixing the language of one annotation
  • Asking to configure an annotation (hands over to the service of the options)
  • Following a reference of an annotation, which opens in the browser
  • Setting the merge option
  • Requesting the annotations to be performed (triggers T08)
  • Showing the six steps, the reports, or both
  • Checking a report, and requesting it to be shown (T10)
  • Requesting the checked report, or every other one, to be deleted (T11)
  • Requesting another batch (T12), or a reset (T13)

Navigation

Annotate is a single page. The page of the desktop interface shows one panel at a time: the six steps with the reports beside them, one list of annotations per type, and the procedure outcome report. This one holds the same panels as sections of one page, shown and hidden where they stand: nothing is asked of the server to go from one to another.

From the six steps:

  • the button of a type shows the list of the annotations of that type, and the button at the top of that list comes back to the six steps;
  • performing the annotations shows the progress, then the procedure outcome report, and the button at its top comes back to the six steps;
  • showing the checked report shows the procedure outcome report the same way.

The six steps and the reports stand side by side. A group of three radio buttons — the six steps alone, both, the reports alone — says how much of each is shown, as on the page of the Journal: two panels side by side are unreadable on a narrow window. Both is what the page opens on locally; online, the reports are collapsed.

Rules of organization

  • RO1 — The client holds no knowledge of the annotations. What an annotation is, which languages it has and what it requires were written in the page by the server; the client shows and sets what is there.
  • RO2 — The two contexts of execution are one organization, and the two deployments are one implementation. What differs is who exposes the batch, and where the reports stand.
  • RO3 — The decisions are taken in any order. The six steps are numbered for the person to read; none of the first three is a precondition of another, and only the performance requires them.
  • RO4 — The batch is exposed by a neighbor and read. Annotate selects no file, in either context, and alters none [402].
  • RO5 — A performance is started by one request and runs on the server, in a thread; where it stands is read on the progress the API was given, and its results replace what was shown when it ends. The failure of one annotation never ends it [503].
  • RO6 — One performance at a time. While one goes, the page offers nothing which starts another, resets the page or asks for another batch, and the server refuses what would [032].
  • RO7 — Locally, the reports are those of the folder of the logs of SPPAS, and they are listed, shown and deleted. Online, the report is one of the produced files, no list exists, and the panel of the reports is collapsed [707].
  • RO8 — A decision is taken in the page and sent with the performance. Choosing an extension, fixing a language and selecting an annotation make no request, and replace nothing of what is read [1005]. Resetting and asking for another batch are of another kind: they take the batch back, which is the server's.
  • RO9 — What was decided is carried between two requests by what the page transmits. What the server holds between two requests is the performance which is going — its thread and its progress — and the manager of the provision of files.
  • RO10 — The order in which the selected annotations are performed is the API's. What this application works out from what the annotations require is the order they are shown in [307], [502].
  • RO11 — The options of an annotation are shown and checked by the service of the options. Annotate hands them over and takes the values back; how that is done, and where, is that service's to say.

RO6 is what the desktop interface does without saying it: its progress is a modal dialog, and nothing can be clicked under it. A web page has no modal progress, so the rule is written.

Constraints

What the code holds to

Gathered from the rules of the treatments and from the requirements they answer, and written here once so that each of them has one place and one only. Nothing is added: what follows was already said, and what this chapter buys is that a constraint can be pointed at.

No.ConstraintImposed by
C1Each kind of output file has one extension, and always one: its default one, until another is chosen.[012], [101], [104], T02
C2An extension is one the API is able to write for that kind; a kind which has none is not shown.[102], [103], T01
C3The language of an annotation is one it has resources for, or none.[202], [203], T03, T05
C4Fixing the language of the page concerns every annotation which has language resources, selected or not, and never one which has none.[202], T03
C5An annotation left without a language stays selected, and is not disabled.T03, T04
C6Selecting an annotation selects no other, and no other is refused.[306], T04
C7Every annotation is shown; one which cannot be performed on that machine is disabled, and cannot be selected.[308], T01, T04
C8What is shown of an annotation is what it declares, and nothing this application wrote.T01
C9An annotation is shown after the ones it requires, and the arrangement changes no performance.[307], [502], RO10
C10A decision makes no request, replaces nothing on the page and never moves the focus.[1005], RO8
C11The batch is read and no file of it is altered; no file is selected here.[401], [402], T07, RO4
C12The annotations are performed only with at least one annotation selected and a batch which is not empty.[031], T08
C13One performance at a time: nothing is started, reset or started over while one goes.[032], RO6
C14What a performance was started with does not change while it goes.T08, RO8
C15The order of a performance is the API's.[502], RO10
C16The failure of one annotation never interrupts the others.[503], T08
C17Each performance writes one report, under a name no report bore before.[504], T08
C18Where a performance stands is what the API said on the progress it was given: nothing is counted here.[505], RO5
C19A report is shown as it was written, each line with the state it carries; nothing is counted from it and nothing is decided from it.[603], T10
C20Locally, one report at most is checked, and the report of the performance which has just ended is.[702], T09
C21Deleting a report deletes nothing of what was produced.[706], T11
C22Online, no report is listed: the report is one of the produced files, and it is reached as they are.[707], [803], RO7
C23Where a produced file is reached is given by the provision of files, and shown by this application.[802], T09
C24Nothing of what was decided is held on the server between two requests. What is held is the performance which is going, and the manager of the provision of files.RO9
C25Which section of the page is shown is carried by nobody: the page shows and hides them where they stand.[1006], the navigation

C5 and C6 are the same decision seen twice. Nothing is decided for the person: an annotation is selected without what it requires, and it stays selected without a language. What is done with it is the API's to say, in the report.

C9 does not contradict C6. It bears on what is shown and on nothing else: the alignment is shown after the phonetization it requires, and selecting the one never selects the other.

C24 is where Annotate departs from Convert. A performance is held by the server while it goes, because it is followed as the Setup follows an installation: a thread advances it, and the progress it was given is read. What the person decided is held by nothing but her page.

Logical level

The tables

Each class of entities becomes a table, and its identifier becomes its key. Nine tables: three are what the API declares and are permanent, five belong to one performance, and one is what stays.

TableColumnsComes from
ANNOTATIONannotationThe class ANNOTATION
REQUIRESannotation, requiredR9, which is many to many
KINDkindThe class KIND
PERFORMANCEperformance, merge, reportThe class PERFORMANCE, and R8
SELECTIONperformance, annotation, languageThe class SELECTION, and R1 with R2
EXTENSIONperformance, kind, extensionThe class EXTENSION, and R3 with R4
VALUEperformance, annotation, option, valueThe class VALUE, and R5 with R6
BATCHperformance, fileR7, which is many to many
REPORTreportThe class REPORT

R1 and R2 both have their low cardinality on the side of SELECTION, which is (1,1): the table takes the two keys, and the two together identify it. One performance holds one annotation at most once. The same holds of EXTENSION with R3 and R4, which is C1 written as a key: one kind has one extension in one performance.

The language of an annotation which is not selected has no table. In the model, it is on the selection; on the page, every annotation has its choice of language, selected or not, and fixing the language of the page sets them all. What the performance is handed is the language of the selected ones, and the others are fields of the page.

The report is not keyed by its performance. A report is read long after the performance which wrote it, and a performance does not last. R8 reads (0,1) on both sides: the table PERFORMANCE takes the key of the report it writes, and REPORT stands by itself.

Four tables are read and never written. ANNOTATION, REQUIRES and KIND are what the API answers. BATCH is what the provider of files exposes, read at every request and altered by nothing here [402].

Not in the tables, and computed every time they are wanted: the annotations of one type, whether a type holds a selected annotation, the languages of the page, the language the selected annotations hold, the arrangement of a list, whether an annotation can be performed on that machine, what is still missing before the annotations can be performed, and the progress.

Physical level

Where each table stands

Here the machines are named, and not before. There is no database: three tables stand in the API of SPPAS, four in what the page transmits, one in a neighbor and one on a disk.

TableWhere it standsBetween two requestsWhat the user sees
ANNOTATIONThe API of SPPAS: the steps of a sppasParam, read at every requestIts ownThe annotations, in one list per type
REQUIRESThe API of SPPAS [API-EXT]Its ownWhat an annotation requires, and the arrangement of its list
KINDThe API of SPPAS: sppasFiles.OUT_FORMATS, read at every requestIts ownOne choice of extension per kind
PERFORMANCEWhat the page transmitsNothing: it is rebuilt at every requestHer decisions, as she took them
SELECTIONWhat the page transmitsNothingThe annotations she selected, and the language of each
EXTENSIONWhat the page transmitsNothingThe extension standing for each kind
VALUEWhat the page transmits, as the service of the options gives itNothingThe options of an annotation, when she configures it
BATCHWhat the provider of files exposesThat domain'sThe files she is annotating
REPORTA file. Locally, in the folder of the logs of SPPAS; online, in the place the provision of files made for what she sentThe fileLocally, the list of the reports; in both contexts, the lines of the one which is shown

The decisions change place when the performance starts. While the person decides, nothing is held on the server: the page carries what was decided and transmits it with the performance. The request which starts the performance writes all of it in a sppasParam — the annotations activated, the language and the options of each, the extensions, the workspace and the name of the report — and hands it to the thread. It is the object the API is performed with, and it is held for as long as the performance goes and no longer. C14, C24

The progress stands with the performance. It is a swappProgressBar, which is a sppasBaseProgress: the API sets on it a percent, a header and a text, and the requests which follow read them. It is made when the performance starts and dropped when it has ended. C18

The report is the one thing which stays. Locally, its name is given by sppasLogFile with the pattern report, as the desktop interface names it: the two interfaces list the same reports. Online, it is written with the produced files, and which operation of the provision of files gives that place is to be named in its dossier. C17, C22

Operational model of treatments

The organizational level said by what and when; this says in what tasks, and what among them cannot be half done.

One request is one unit. Every request begins by rebuilding what was decided from what the page transmitted, runs the one treatment it was asked for, and sends back what is to be shown. Nothing is begun in one request and finished in another, except T08: it is started by one request, the requests which follow ask where it stands, and the last one gives its report.

PFThe tasks, in orderWhat cannot be half done
PF1When the page is asked for: read the annotations from the API and, for each of them, what it declares; read the kinds of output file, their extensions and their default one; arrange each list; locally, list the reports; write all of it in the pageNothing: nothing is written
PF2, PF4, PF5In the page: keep the extension, the selection or the language; it is sent with the performanceNothing: nothing is sent
PF3In the page: set the choice of language of every annotation to the language fixed where it holds it, and to --- where it does not; show the language the selected annotations holdNothing: nothing is sent
PF6Hand the options of the annotation to the service of the options; take back the values, or nothing when she gives upNothing of this application's
PF8Rebuild; ask the provision of files for the batch, and verify one annotation selected, a batch which is not empty and no performance going; name the report; write what was decided in a sppasParam; make the progress; lock the batch; start the thread and answer. In the thread: have the API perform the annotations; release the batch, give back what was produced, and say it has finishedThe start: a performance is going, or none is. Not the performance itself
PF9Read the report; locally, add it to the list and check it; online, ask the provision of files for its address and for the address of the archive; write the section of the report and the container of the provision of filesNothing
PF10Read the checked report, and write the section of the reportNothing: nothing is written on a disk
PF11Delete the checked report, or each report which is not checked, one after anotherThe deletion of one report
PF12Rebuild; ask the provision of files to start over; answer the page with the decisions as they wereNothing
PF13Rebuild nothing; ask the provision of files to start over; answer the page as PF1 doesNothing

A performance is never half done, because nothing of it is undone

What an annotation writes, it writes as it goes, beside the files. There is no moment at which a performance is half made and has to be undone: an annotation which failed stops nothing, and the ones performed before it wrote what they wrote [503].

A performance which stops is not repaired. Nothing more is written and nothing more is said. The report was written line by line: it holds what was done until then, and it is read as any other [603].

The order is not this application's

The selected annotations are performed in the order of the API. An annotation which requires one which was not selected is performed all the same. What is read of the requirements is read for the person: to show them, and to arrange each list. C9, C15

One performance at a time

The thread which performs the annotations is what says a performance is going. While it is alive, a request which would start another one, reset the page or start over is refused, and the page, which shows the progress in place of the six steps, offers none of them. C13

Where the code goes

In sppas/ui/swapp/app_annotate/. One module per kind of knowledge, and every procedure has one module and one only.

ModuleWhat it doesProcedure
annotationsKnows which annotations there are and what each declares, which kinds of output file there are and their extensions; says which annotation is of which type, which languages the page offers, and arranges a list by what its annotations require. Reads no file of the userPF1
performanceNames the report, writes what was decided in what the API is performed with, makes the progress, starts the thread, and says whether a performance is going and where it standsPF8
reportsLists the reports, reads one with the state of each of its lines, and deletes those which are namedPF9, PF10, PF11
provisionReads the batch the provision of files hands, says what it locks and releases, gives back what was produced, asks for the addresses, and says when it has finished. Alters nothing of the batchPF7, PF8, PF9
decisionsRebuilds what was decided from what the page transmitted, and says what is still missingPF12, PF13, and the beginning of every other
presentationRenders the state, collects the decisions, triggers the eventsThe view of every procedure; PF2 to PF5, which happen in the page

What each one promises, which is the reason for the cutting:

  • The annotations module is the only one which reads what an annotation declares. Arranging a list is the one thing it adds, and it is given everything it needs: it is tested with nothing installed.
  • The performance module is the only one which has the API perform annotations, so it is the only one to read again the day that API changes.
  • The reports module is the only one which touches a report. It does not write one: the API does.
  • Provision is the only one which calls the provision of files on files. It is given the manager of that service by the response.
  • Decisions is the only one which knows what the page transmits. It holds no state of its own between two requests.
  • Presentation decides nothing. What it shows was decided before it was called, and the JavaScript it carries renders and nothing else.

The batch is provided, not constituted

Annotate does not select files. It receives a batch from its execution context and alters none of its files. In a local session, that context is the SPPAS workspace, or the files the person designates with the file chooser of the machine. In an online use, the batch results from files brought by the user to the service.

Annotate therefore depends on the provision of files, a service of swapp which has its own dossier, exactly as Convert does: a workspace holding the files to be treated and them only is handed, what is produced is added to it, and it is given back. The page of the desktop interface is given the workspace by its parent and sends it back when the annotations have been performed; this one asks the service, and gives back to the service.

Which files an annotation takes among those of the batch is not decided here: an annotation which takes two files finds them from the workspace and from what it declares.

Implementation model: MVC

  • Model: knows the annotations, performs T08, reads and deletes the reports, and is the only one which calls the provision of files on files. It is a façade over the automatic annotations of SPPAS.
  • Controller: identifies the task requested, checks its preconditions, chooses the treatment to run, calls the model, and prepares the data for display.
  • View: renders the state, collects the decisions, triggers the events. No business logic; JavaScript is rendering and interaction support only.

What receives a request is not the controller. The WhakerPy response handles the URL, receives the GET or POST and the events it carries, calls the controller once for that request, and bakes the returned tree — either a full page or an update payload.

Model

The façade AnnotateModel exposes the single interface the application expects and delegates to four specialized sub-models.

ModelAnnotations holds the knowledge of the annotations. It makes a sppasParam and reads its steps: for each annotation, its key, its name, its description, its types, its languages, its references, how far its development has gone and its options. It reads the kinds of output file, their extensions and their default one from sppasFiles. It gives the languages of the page, which are the languages of every annotation put together, and it arranges a list by what its annotations require.

ModelPerformance performs T08. It names the report, fills a sppasParam with what was decided, makes the progress, and starts a thread in which sppasAnnotationsManager performs the annotations, the merge option being given to it first. It holds the thread and the progress, and nothing else: it says whether a performance is going, and where it stands.

ModelReports lists the reports of the folder of the logs — the text files whose name holds report —, reads one, and deletes those it is named. Reading gives the lines as they were written, each with the state it carries: a line which starts a result bears one of OK, ERROR, WARNING, INFO and IGNORED, in the language of the interface, and that word is what the state is read from.

ModelProvision is the only class which calls the provision of files on files, as in Convert: files_for_app(), lock(), release(), produced(), address_of(), address_of_all(), and finished.

Controller

The controller is called once per request. It rebuilds the current state exclusively from the data transmitted to it. What carries that state is one object, AnnotateRecord: the view serializes it and the controller parses it back, and neither of them holds it between two requests.

Tasks:

  • start — transmitted: nothing. Preconditions: none. Triggers: T01. Produces: the page in its initial state [012].
  • perform — transmitted: the extensions, the selected annotations, the language of each, the values of the options, the merge option. Preconditions: at least one annotation selected; batch not empty; no performance going. Triggers: T08. Produces: the progress.
  • update — transmitted: nothing. Triggers: nothing. Produces: the percent, the header and the text of the progress, alone.
  • complete — transmitted: the decisions. Triggers: T09. Produces: the report, the container of the provision of files and, online, the addresses.
  • show — transmitted: the checked report, the decisions. Preconditions: a report is checked and can be read. Triggers: T10. Produces: the report. Locally.
  • delete_checked, delete_unchecked — transmitted: the checked report, the decisions. Triggers: T11. Produces: the list of the reports which are left. Locally.
  • restart — transmitted: the decisions. Preconditions: no performance going. Triggers: T12. Produces: the page without batch, the decisions as they were. The provision of files starts over.
  • reset — transmitted: nothing. Preconditions: no performance going. Triggers: T13. Produces: the page in its initial state. The provision of files starts over.

Nine tasks for thirteen treatments. T02 to T05 happen in the page and make no request RO8: what they decide is transmitted with perform. T06 is handed to the service of the options, and T07 is the provision of files'. update and complete are sent as the Setup sends them: event_name carries the first, and event_bake the second. The answer to update has a status of 202 until the hundred is reached.

What the page starts with
Default of each decision
Decision Default Reason
extension of a kindthe default extension of that kindwhat the API says
language of the page---no initiative
language of an annotationthe one its declaration holds, --- when it holds nonewhat the API says
annotationnot selectedno initiative
merge optionoffno initiative
panels shownboth locally; the six steps alone onlineRO7
Views

The WhakerPy response builds the whole HTML tree, and the structural elements common to the application — head, header, nav, footer — are factored there. The Annotate views build only the content of body > main.

Annotate has one applicative view, AnnotateView, built from the panels of the page of the desktop interface, which bear its names. They are sections of one page.

ActionAnnotatePanel presents the six steps, each with its title as the desktop interface writes it. Step 1: one choice of extension per kind of output file. Step 2: the choice of the language of the page. Step 3: one button per type, which shows the list of that type and says whether it holds a selected annotation — an icon whose state has a text alternative. Step 4: the container of the provision of files. Step 5: the merge option, and the button which performs the annotations; that button is disabled as long as no annotation is selected. Step 6: the button which shows the checked report, disabled as long as no report is checked. It holds the Reset button as well.

ReportsPanel presents, beside the six steps, the reports which are kept: one radio button per report, named after its file, the last one written at the top; and two buttons, one which deletes the checked report and one which deletes all the others. Online, it is collapsed.

A group of three radio buttons stands above the two panels and says which of them are shown. It is the segmented control of Whakerexa the Journal uses, a native radio group: reaching it with the keyboard and hearing which one holds come from the buttons themselves and not from a script.

AnnotationsPanel presents the annotations of one type: a button which comes back to the six steps, a title naming the type, then one EnableAnnotation per annotation of that type, arranged by what they require. There are three of them, one per type.

EnableAnnotation presents one annotation: what selects it, with its name; what configures it; its references, one link each, telling a document from a web page — or, when it has none and its development is known, a gauge with its percent; the choice of its language, when it has language resources; its description; and what it requires. An annotation which cannot be performed on that machine is there, disabled.

LogAnnotatePanel presents the progress while the annotations are performed, then the procedure outcome report: a button which comes back to the six steps, the title, the name of the file of the report, then its lines, each result bearing the class of its state. The state is in the text of the line as well, so the color is never the only thing which says it. Online, a link downloads the report, and another one the archive of every produced file. Under the report, the Start over button annotates another batch with the decisions already taken.

The container of the provision of files stands in the page as well. It is not a panel of Annotate: the response places it under the node it chose.

JavaScript is interface support. It shows and hides the sections. When the language of the page is fixed, it sets the choice of each annotation. When an annotation is selected or its language fixed, it says again which types hold a selected annotation and which language the selected annotations hold, the entry MIX included, and enables or disables the button which performs. When she asks for the annotations to be performed, it sends the fields of the form without reloading the page, shows the progress and asks at regular intervals where the performance stands; when the hundred is reached, it asks for the results and puts in the page what the server wrote. It creates no HTML and holds no knowledge of the annotations.

The classes of the model

/ marks what is derived and held by nobody. What the operations promise is the chapter on the contracts.

ClassFromAttributesOperations
AnnotateModelthe façade—annotations(), kinds(), languages(), batch(), start(batch, performance), is_performing(), progress(), reports(), read_report(name), delete_reports(names), address_of(filename), address_of_all(filenames)
ModelAnnotationsmodule annotations—annotations(), kinds(), languages(), arranged(annotations)
ModelPerformancemodule performancethread, progressstart(batch, performance), is_performing(), progress()
ModelReportsmodule reports—reports(), read(name), delete(names)
ModelProvisionmodule provision—batch(), lock(names), release(names), produced(workspace), address_of(filename), address_of_all(filenames), finished()
AnnotationANNOTATION, REQUIRESkey, name, description, types, languages, language, references, devel, requires, /can be performed—
KindKINDkind, extensions, default—
PerformancePERFORMANCE, SELECTION, EXTENSION, VALUEextensions, selected, lang, options, merge, report, /what is missingwhat_is_missing(batch)
ReportLineREPORTtext, state—
noneBATCHThe files are exposed by the provision of files, which names them already

What the core of SPPAS already holds is not held again here. Which annotations there are and what each declares is sppasParam; performing them is sppasAnnotationsManager; the kinds of output file and their extensions are sppasFiles; the types are annots.types; naming a report is sppasLogFile. Annotation and Kind are what is read of them to be shown, made at each request and kept by nobody.

What tells that an annotation cannot be performed on a machine is to be named. The API raises an exception for it; which one, and where, is not written here yet. Annotation carries the answer, and ModelAnnotations is the only class to read again the day it is named.

Performance.what_is_missing() is given the batch and does not hold it: what may be missing is an annotation selected and a batch which is not empty [031].

What is tied to what

TieLegsWhat it is
holdsAnnotateModel 1 — 1 each of the four sub-modelsA composition: the façade makes them, and nothing else reaches them
usesModelAnnotations → Annotation, KindA dependency: it makes them from the API, and keeps none
usesModelAnnotations → sppasParam, sppasFilesA dependency: what is read of the API to be shown
usesModelPerformance → sppasParam, sppasAnnotationsManager, sppasLogFileA dependency, and the only tie of this application to what performs annotations
holdsModelPerformance 1 — 0..1 swappProgressBarA composition: made when a performance starts, dropped when it has ended
usesModelPerformance → ModelProvisionA dependency: it locks, releases and gives back, in the thread
usesModelReports → ReportLineA dependency: it makes them from a file, and keeps none
usesModelProvision → the provision of filesA dependency, and the only tie of this application to that domain

In yUML

To be read at yuml.me, class diagram.

[AnnotateModel|annotations();kinds();languages();batch();start();is_performing();progress();reports();read_report();delete_reports();address_of();address_of_all()]++1-1>[ModelAnnotations|annotations();kinds();languages();arranged()]
[AnnotateModel]++1-1>[ModelPerformance|thread;progress|start();is_performing();progress()]
[AnnotateModel]++1-1>[ModelReports|reports();read();delete()]
[AnnotateModel]++1-1>[ModelProvision|batch();lock();release();produced();address_of();address_of_all();finished()]

[ModelAnnotations]-.->[Annotation|key;name;description;types;languages;language;references;devel;requires;/can be performed]
[ModelAnnotations]-.->[Kind|kind;extensions;default]
[ModelAnnotations]-.->[sppasParam]
[ModelAnnotations]-.->[sppasFiles]
[ModelPerformance]++1-0..1>[swappProgressBar]
[ModelPerformance]-.->[sppasParam]
[ModelPerformance]-.->[sppasAnnotationsManager]
[ModelPerformance]-.->[sppasLogFile]
[ModelPerformance]-.->[ModelProvision]
[ModelReports]-.->[ReportLine|text;state]

The classes of the view

ClassOperationsWhat it shows
AnnotateViewpopulate_tree_content(record), section, infoThe page, and the panels it holds. It is the module presentation: what is shown, and nothing of what it means
ActionAnnotatePanel—The six steps: the extensions, the language of the page, one button per type, the merge option and what performs, what shows the checked report; and the Reset button
ReportsPanel—Locally, the reports which are kept, one of them checked at most, and the two buttons which delete. Collapsed online
AnnotationsPanel—The annotations of one type, arranged by what they require
EnableAnnotation—One annotation: what selects it, what configures it, its references or how far its development has gone, its language, its description, what it requires. Disabled when it cannot be performed on that machine
LogAnnotatePanel—The progress, then the procedure outcome report: the name of its file and its lines, each with its state. Online, a link to the report and one to the archive. Under the report, the Start over button

What is tied to what

TieLegsWhat it is
holdsAnnotateView 1 — 1 ActionAnnotatePanel, 1 ReportsPanel, 1 LogAnnotatePanelA composition: a panel builds one part of one page and exists for it
holdsAnnotateView 1 — 3 AnnotationsPanelA composition: one per type
holdsAnnotationsPanel 1 — 0..n EnableAnnotationA composition: one per annotation of that type
usesAnnotateView → AnnotateRecordA dependency: it is given it and builds from it

In yUML

[AnnotateView|section;info|populate_tree_content()]++1-1>[ActionAnnotatePanel]
[AnnotateView]++1-1>[ReportsPanel]
[AnnotateView]++1-3>[AnnotationsPanel]
[AnnotateView]++1-1>[LogAnnotatePanel]
[AnnotationsPanel]++1-0..*>[EnableAnnotation]

[AnnotateView]-.->[AnnotateRecord]

The classes of the controller

ClassAttributesOperations
AnnotateControllerrecordis_a_task(events), handle(request_data), progress(), say_what_is_missing(), populate_view()
AnnotateRecordtask, performance, checked report, to_be_shownserialize(), parse(data), show(key, value)
AnnotateResponseRecipe—bake(), _process_events()

AnnotateController is the module decisions: what a request transmits, and which task it carries.

The response of WhakerPy is named here AnnotateResponseRecipe. It holds the model, which holds the performance which is going, and the manager of the provision of files, which that service requires an app to hold between two requests. It answers the progress alone; it answers the tasks of this application first, and offers what it does not recognize to the manager, consumes(); it places its container in the page, populate_view() then container(); it asks it whether the person said the workspace is ready, is_ready(); and it asks it to start over when she resets or asks for another batch, start_over().

What is tied to what

TieLegsWhat it is
holdsAnnotateResponseRecipe 1 — 1 AnnotateView, 1 AnnotateControllerA composition: it builds them, and they go when it goes
holdsAnnotateResponseRecipe 1 — 1 the manager of the provision of filesHeld between two requests, as that service requires
holdsAnnotateController 1 — 1 AnnotateRecordA composition: one record per request, made by the controller and kept by nobody
holdsAnnotateRecord 1 — 1 PerformanceA composition: what was decided lives inside what one request carries
usesAnnotateController → AnnotateModelA dependency: it calls the façade, once per request
usesAnnotateController → AnnotateViewA dependency: it hands it what to build from

In yUML

[AnnotateResponseRecipe|bake();_process_events()]++1-1>[AnnotateController|record|is_a_task();handle();progress();say_what_is_missing();populate_view()]
[AnnotateResponseRecipe]++1-1>[AnnotateView]
[AnnotateController]++1-1>[AnnotateRecord|task;performance;checked report;to_be_shown|serialize();parse();show()]
[AnnotateRecord]++1-1>[Performance|extensions;selected;lang;options;merge;report;/missing|what_is_missing()]

[AnnotateController]-.->[AnnotateModel]
[AnnotateController]-.->[AnnotateView]

The states

An annotation
StateWhenWhat is shown
disabledIt cannot be performed on that machineIts line, disabled; nothing of it can be set
not selectedNothing was said of itIts line, and what selects it
selectedIt is to be performedIts line, that it is selected, and its language; the button of each of its types says a selected annotation is there

Three states and no more. An annotation which is selected without a language, or without what it requires, is selected: neither is a state, and neither is a mistake. C5, C6

A performance
StateWhen
noneNo thread is alive: the page shows the six steps
goingThe thread is alive: the page shows the progress, and nothing which starts anything
endedThe thread is no longer alive: the page shows the report

A line of a report which states a result has one of five states: OK, ERROR, WARNING, INFO or IGNORED. They are the API's, and the line is what carries them. A line which states no result has no state.

The sequence, from the first request to the report

  1. The page is asked for. The annotations are read with what each declares, the kinds of output file with their extensions and, locally, the reports; all of it is written in the page, in its initial state [012].
  2. The batch is read from the provision of files. It is empty, and what is missing is said [403].
  3. The user chooses extensions and fixes the language of the page. Nothing is sent, and the choice of language of every annotation follows [202].
  4. She shows the list of a type, selects annotations, fixes the language of one of them, configures another, and comes back. The button of that type says a selected annotation is there [302].
  5. She designates her files in the container of the provision of files, and says they are ready.
  6. She asks for the annotations to be performed. Everything decided is sent at once, and the page is not reloaded; the preconditions are read on what was transmitted and on the batch.
  7. The report is named, the batch is locked, and the API performs the selected annotations, in its own order, in a thread. The page shows the progress and asks where the performance stands until the hundred is reached.
  8. The page asks for the results. The report is shown, with the name of its file; locally, it is at the top of the list of the reports, and checked.
  9. What was produced is reached through the provision of files: online, by a link to the report and a link to the archive of every produced file.
  10. She comes back to the six steps, and performs other annotations on the same batch, or asks for another batch, or resets the page.

Steps 3 to 5 happen in any order, and any of them may happen twice. The only thing which requires them is step 6.

The error policy

LevelWhat happensWhat is done
1What was asked cannot be done now: no annotation selected, an empty batch, a performance already goingNo treatment runs, and what is missing or what stands in the way is said [022]. It is not an error and nothing is raised
2One annotation is concerned: it failedNothing of this application's: the API writes it in the report, with the state of the line which says it, and goes on to the next
3A report cannot be read, or cannot be deletedIt is said, with the reason; a report which cannot be deleted stays in the list, and the others are deleted all the same
4Whoever runs the machine has to know: the annotations cannot be read, a performance cannot be startedSaid where he reads it, and the person is told that the annotations could not be performed

What is raised is caught by the response which answers the request, and by nothing below it. What an annotation writes about its own difficulties is not an error of this application: it is what that annotation said, and it is shown as such.

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 without looking. The treatments state their preconditions for one treatment; these state them for one operation, and the two say the same thing at two levels.

What holds everywhere

  • What is absent gives back an empty thing — an empty list, no language, no report — and never nothing at all.
  • Nothing of what was decided is held between two requests. What is held is the performance which is going, and the manager of the provision of files. C24
  • Only ModelPerformance has the API perform annotations, and only ModelAnnotations reads what an annotation declares.
  • Only ModelReports touches a report, and it writes none.
  • Only ModelProvision calls the provision of files on files.
  • A view decides nothing: what it shows was decided before it was called.
  • What is raised is caught by the response which answers the request, and no class below it writes a catch. What an annotation says of its own difficulties is not raised: it is in the report.

Class by class

AnnotateModel
OperationContract
Give the annotationspre: none. post: every annotation the API declares, each with what it declares and whether it can be performed on that machine; none is left out. C7, C8
Give the kinds of output filepre: none. post: every kind which has at least one extension, with its extensions and its default one. C1, C2
Give the languages of the pagepre: none. post: every language at least one annotation has resources for, each of them once
Give the batchpre: none. post: the workspace the provision of files hands, possibly empty. C11
Start a performancepre: a batch which is not empty, at least one annotation selected. post: a performance is going, and it is answered without waiting for it; when one was going already, nothing is started and it is said. C12, C13
Say whether a performance is goingpre: none. post: true while the thread which performs is alive, false otherwise
Give the progresspre: none. post: the percent, the header and the text the API set; the hundred, and nothing else, when no performance is going. C18
Give the reportspre: none. post: the names of the reports which are kept, the last one written first; empty when there are none, and empty online. C22
Read a reportpre: the name of a report. post: its lines as they were written, each with its state or with none. C19
Delete reportspre: names of reports. post: those which could be deleted are gone, the names of the others are given back, and nothing else was touched. C21
Give the address of a produced file, or of all of thempre: names of produced files. post: what the provision of files answers; empty where the person reaches them where they stand. C23
ModelAnnotations
OperationContract
Give the annotationspre: none. post: one Annotation per step of a sppasParam, in the order of the API, holding what that step answers and nothing this application wrote. The references are given with their address; how far the development has gone is given between 0 and 100. C8
Give the kindspre: none. post: what sppasFiles answers, relayed; a kind which has no extension is not given. C2
Give the languagespre: none. post: the languages of every annotation put together, each of them once
Arrange a listpre: annotations, each with what it requires. post: those annotations and no others, each standing after every one of the list it requires; an annotation whose requirement is not in the list keeps its place. It reads nothing and changes no performance. C9

Arranging is the one operation of this application which rests on nothing installed: what it is given comes back, in another order, nothing added and nothing removed.

ModelPerformance
OperationContract
Startpre: the preconditions of the performance are verified. post: the report is named, under a name no report bore before, and the name of the next one is prepared; a sppasParam holds what was decided and that only — the selected annotations activated and no other, the language and the options of each, the extensions, the workspace, the name of the report; the progress is made; the batch is locked; a thread is started, and the name of the report is given back. Raises when a performance is going. C13, C14, C17
What the thread doespre: started. post: the merge option was given to the API, then the annotations were performed in the order of the API; whatever each of them did, the batch is released, what was produced is given back, and that it has finished is said. C15, C16
Say whether a performance is goingpre: none. post: true while the thread is alive
Give the progresspre: none. post: what the API set on the progress it was given; nothing is counted here. C18
ModelReports
OperationContract
Give the reportspre: none. post: the names of the text files of the folder of the logs whose name holds report, and no other file of that folder
Read a reportpre: the name of a report, without its path. post: one ReportLine per line, in the order of the file; a line which states a result bears its state, any other bears none; nothing is counted and nothing is decided from it. Raises when the file cannot be read. C19
Delete reportspre: names of reports, without their path. post: each of them is deleted on its own, and one which cannot be does not keep the others from being; the names of those which are left are given back. No file which is not a report is deleted. C21
ModelProvision
OperationContract
Give the batchpre: none. post: the workspace the provision of files hands, holding the files to be treated and them only, possibly empty; the workspace of the person never reached. C11
Lock and releasepre: files of the batch. post: they are locked while the annotations are performed, and released when they have been; none is still locked afterward
Give back what was producedpre: the annotations have been performed. post: what was written is in the workspace which was handed, that workspace is given back, and that the batch has been treated is said. C23
Give an addresspre: the name of a produced file, or of several. post: what the provision of files answers, relayed. C23
Performance, AnnotateRecord
OperationContract
Say what is missingpre: a batch is given to it. post: an annotation when none is selected, the batch when it is empty, nothing when the annotations may be performed. It holds no batch. C12
Serialize a recordpre: none. post: everything a next request needs in order to rebuild what was decided, and nothing of the machine
Parse a recordpre: what a page transmitted. post: what was decided as it was, or the defaults when nothing was transmitted. An annotation is selected only if it was transmitted as such: selecting one selects no other. Parsed twice, it gives the same. C1, C6, C24
Put what is to be shownpre: none. post: it is in what is to be shown, and it is never serialized
AnnotateController
OperationContract
Handle a requestpre: called once for that request. post: the record is rebuilt from what was transmitted; the language transmitted for an annotation is kept only if that annotation has it, and a disabled annotation is never selected; the task is identified, its preconditions are read; the treatment ran, or none ran and what is missing or stands in the way is stated. C3, C5, C7
Say whether events carry a taskpre: none. post: true when the events carry a task of this application
Give the progresspre: none. post: the percent, the header and the text, as the model gives them
Have what is missing said againpre: the request was handled, and the provision of files says the workspace is ready. post: what is still missing is put in the dialog of information when the view is populated
Populate the viewpre: the request was handled. post: the view has the record; locally it holds the reports, online it holds none. C22
AnnotateView and its panels
OperationContract
Populate the treepre: a record. post: a tree holding what that record says and nothing more. Every field of a decision belongs to the form of the performance, wherever it stands in the page. C10
Give the section and what was saidpre: the tree was populated. post: the section of this application as it was built, and the text put in the dialog of information, empty if nothing was
ActionAnnotatePanelpost: the six steps, in their order and with their titles; one choice per kind of output file, the extension which holds selected; the choice of the language of the page; one button per type, saying whether it holds a selected annotation; the merge option; the button which performs, disabled when no annotation is selected; the button which shows the checked report, disabled when none is; the Reset button
ReportsPanelpost: locally, one radio button per report, at most one checked, and the two buttons which delete; online, collapsed and empty. C20, C22
AnnotationsPanelpost: the button which comes back, the title naming the type, and one EnableAnnotation per annotation of that type, in the order it was given them
EnableAnnotationpost: the annotation it stands for, as it declares itself: what selects it, what configures it, one link per reference or the gauge of its development or neither, the choice of its language when it has language resources and no choice otherwise, its description, what it requires. Disabled when the annotation cannot be performed on that machine. C7, C8
LogAnnotatePanelpost: the progress while a performance goes; then the name of the file of the report and its lines, each result bearing its state; that the report is not available, with the reason, when it could not be read; online, the link to the report and the link to the archive; under the report, the Start over button. C19, C23
AnnotateResponseRecipe
OperationContract
Answer the eventspre: the events of a request. post: the progress is answered alone, with a status of 202 until the hundred is reached; the tasks of this application are answered first; the rest is offered to the provision of files, and when it says the workspace is ready, what is still missing is said again; the provision of files is asked to start over on a reset and on another batch
Bakepre: a request, carrying a task or carrying none. post: the tree of the page, or the payload of an update, holding the container of the provision of files

Where each constraint is held

One place each. A constraint held in two would be a constraint held in neither.

No.Held by
C1AnnotateRecord, which gives a kind its default extension when none was transmitted
C2ModelAnnotations, giving the kinds
C3AnnotateController, which keeps a language only if the annotation has it
C4The page: the script sets the choices EnableAnnotation wrote, and an annotation which has no language resource has no choice to set
C5AnnotateController, which takes no selection back and disables nothing for a language
C6AnnotateRecord, parsing: what is selected is what was transmitted as such
C7ModelAnnotations, which says it of each annotation; EnableAnnotation shows it
C8EnableAnnotation, which writes nothing of its own
C9ModelAnnotations, arranging a list
C10AnnotateView, which ties every field of a decision to the form of the performance; the script sends that form and nothing before
C11ModelProvision, which is what reads the batch
C12Performance, saying what is missing, read by AnnotateController before it starts anything
C13ModelPerformance, which starts nothing while its thread is alive; AnnotateController reads it before a reset or another batch
C14ModelPerformance, which fills its own sppasParam when it starts and is given nothing afterward
C15ModelPerformance, which hands the whole to the API and orders nothing
C16The API; ModelPerformance stops nothing
C17ModelPerformance, naming the report
C18ModelPerformance, giving the progress
C19ModelReports, reading a report; LogAnnotatePanel shows it as it was given
C20ReportsPanel, whose reports are one group of radio buttons
C21ModelReports, deleting reports
C22AnnotateController, which gives the view no report when the server is not the local one
C23ModelProvision
C24AnnotateRecord, and AnnotateController, which keeps nothing after the request
C25The page: no field carries which section is shown

C4, C10 and C25 are held by the page. They are what [1005] costs: a decision which makes no request is a decision the server does not see until the performance is asked for, and what it then reads is checked again — C3, C6 and C7 are that check.

What is tested, and where

The models and the view

Thirty-eight tests: thirty-three for the sub-models and what was decided, and five for the view. The controller is not covered here and is owed.

Arranging a list, with nothing installed

No.What is checkedWhat it holds
TE1What comes back is what was given: not one annotation added, not one removedThe contract of arranging
TE2An annotation stands after every annotation of the list it requiresC9
TE3An annotation whose requirement is not in the list is in the list all the sameC9
TE4A chain of three is arranged the same way whatever order it was given in, the reverse includedC9
TE5A requirement which names no annotation changes nothing of the arrangementC9
TE6The same list given twice is arranged the same wayThe contract of arranging

ModelAnnotations, with the API and no file

No.What is checkedWhat it holds
TE7Every annotation the API declares is given, and no other[308], C7
TE8What is given of an annotation is what it declares: its name, its description, its types, its languages, its references, how far its development has goneC8
TE9An annotation which has two types is given for each of them[301]
TE10A kind of output file which has no extension is not given; the default extension of a kind is one of its extensionsC1, C2
TE11The languages of the page are those of every annotation put together, each of them once[201]
TE12What an annotation requires is read from its declaration, and one which declares none requires nothing[307]
TE13An annotation which cannot be performed on that machine is given all the same, and said soC7

TE12 fails until the field is read. It is written that way on purpose: this test is what says whether the extension of the annex was made.

What was decided

No.What is checkedWhat it holds
TE14What is missing is an annotation when none is selected, the batch when it is empty, and nothing when the annotations may be performedC12
TE15A record parsed twice gives the same decisions; nothing transmitted gives the defaultsC1, C24
TE16An annotation transmitted as selected, with no language, is selectedC5
TE17Selecting an annotation which requires another selects that one onlyC6

ModelPerformance, with annotations which really are performed

These need annotations to perform, and the ones they perform are written for the tests: one which writes a file, one which fails, one which takes its time. What is tested is this application, never an annotation of SPPAS.

No.What is checkedWhat it holds
TE18Starting answers before the performance has ended, and the performance goes on after the answerRO5
TE19A second start while one is going is refusedC13
TE20What is handed to the API holds every selected annotation activated, and no otherC6, C14
TE21What is decided after the start does not change what that performance is performed withC14
TE22An annotation which fails stops nothing: the performance reaches its end, and the report holds bothC16
TE23While a performance goes, the progress is what the API set; when none goes, it is the hundredC18
TE24Two performances write two reports, and the second one replaces nothing of the firstC17

ModelReports, with a disk

No.What is checkedWhat it holds
TE25The reports given are the text files whose name holds report, and no other file of the folder[701]
TE26A line which states a result bears its state, for each of the five; a line which states none bears no stateC19
TE27A report which is not there is said so, and nothing is given in its place[604]
TE28Deleting reports deletes those which were named, and no other fileC21
TE29A report which cannot be deleted does not keep the others from being, and its name is given backT11

ModelProvision, against the neighbor

No.What is checkedWhat it holds
TE30The batch is the workspace the provision of files hands, empty when nothing is checked, and the workspace of the person has not movedC11
TE31The files of the batch are locked while the annotations are performed, and none is still locked afterwardT08
TE32What was produced is given back once, when the annotations have been performed, and not at each of themT09
TE33Online, the report is among what the archive holds[803], C22

AnnotateView, the page as the server writes it

No.What is checkedWhat it holds
TE34Every field of a decision belongs to the form of the performance: the extensions, the languages, the selections, the merge optionC10
TE35The page holds one list per type, and an annotation which has two types is in both[301]
TE36An annotation which cannot be performed on that machine is in the page, disabledC7
TE37Online, the panel of the reports is collapsed and holds no reportC22
TE38The page of a first request has no annotation selected, the button which performs disabled, and the default extension of each kind selected[012]

What no test covers, and where they stand

  • The controller. It is owed, and it is what will check that a language an annotation has not is not kept, and that a disabled annotation is never selected.
  • The JavaScript. That fixing the language of the page sets the choice of every annotation, that the entry MIX appears and goes, and that the sections are shown and hidden, is checked in a browser and not here.
  • What an annotation does. It belongs to the API and is tested there; this application is answerable for what it handed over.
  • The two services, which have their own dossiers and their own tests. What is checked here is the tie.
  • The wording, and the WCAG rules, which are verified on the page and not on a fragment of it.

Six of the thirty-eight need nothing at all, eleven need nothing but the API, seven need annotations written for the tests, five need a disk, four need the neighbouring domain, and five the view.

They stand where the project puts its own: in tests/swapp/, which follows the shape of the sources.

Annexes

Annex: Extension of the SPPAS API

One extension is required by this document, and it is required by [307] alone.

E1 — What an annotation requires, read [API-EXT]

What The identifier of the annotation which has to have been performed before, carried by the declaration of an annotation and read with the rest of it.
Why The field is already written in the declarations — the phonetization says it requires the text normalization, the alignment says it requires the phonetization, the time group analysis says it requires the syllabification — and what reads a declaration does not read it. It reads the identifier, the name, the description, the type, the interface to run, the references, the degree of development, the options and the resources, and it passes over that one field. [307] asks for a value which is written and never loaded.
Bound to What an annotation requires — Requirements. Requirement [307].
What it costs One field read where the others are read. Nothing of what exists changes, and an annotation which declares nothing there requires nothing, which is what most of them say already.
What it is not It says what has to have been performed before, and never what will be made of an annotation afterward: what follows one is read on the others.
Note What is written there is not all sound. One declaration names a requirement which no annotation bears, and one writes a requirement with a mark in front of it which no other has. Both are read the day the field is read, and neither is settled here.

What the current API already provides

For contrast, and to bound the extension above, the following are available and require nothing [API-OK]:

  • the annotations and what each declares, the activation, the language and the options of each, the output extensions, the workspace and the name of the report: sppasParam;
  • performing the activated annotations, with a progress and the merge option: sppasAnnotationsManager;
  • the kinds of output file, their extensions and their default one: sppasFiles;
  • the types of annotation: annots.types;
  • a name for each report, which replaces no other: sppasLogFile.

Annex: Mockup of the interface

This annex is the page itself: the HTML the application writes, styled by Whakerexa. What is unreadable here will be unreadable there.

It shows the page the person arrives on: the six steps on the left, the reports on the right, and above them what says which of the two panels is shown — the same three radio buttons as the page of the Journal, written the same way. The fourth step is the files, the container of the provision of files: they are given after the decisions, and before what uses them. What that container holds is written by its service, and is not drawn here.

It shows one state: SPPAS on the machine of the person, two kinds of file which can be written, no annotation selected, and two reports kept. The names of the reports and the languages are examples.

Step 1: choose the output file format(s)

Step 2: fix the language(s)

Step 3: select and configure annotations

Step 4: add files

Step 5: perform the annotations

No annotation is selected.

Step 6: read the procedure outcome report

No report is checked.

Reports:

Annex: Legal notices