AppMessages (issie)

AppMessages Module

Namespace: global
Assembly: Renderer.dll

The words Issie says to the user, where they are long enough to be worth reading as prose.

WHAT IS HERE. The Info window's four written tabs, the waveform simulator's five help panels,
the memory help, the twenty field explanations in the Properties pane, and the confirmation
popups whose body is several sentences rather than one - thirty-five messages, about 25,000
characters. They were spread through the view functions that show them, written as React
element trees with the words threaded between `str` and `bSpan` and `li` - fine to render and
very hard to read, which is a problem for text whose only job is to read well. Written as
markdown here, the whole of Issie's long-form help can be read end to end and reviewed as
writing.

WHAT IS NOT HERE, and should not be moved in.

- Short labels, button captions and headings. A caption is easier to judge beside the button it
sits on than in a list of thirty other strings.
- The Catalogue's component tooltips. They are short, they are one per component, and each sits
beside the component type it describes, which is what makes them easy to keep true.
- One-line confirmation bodies - "The current sheet has unsaved changes." A sentence that short
belongs with the buttons it is explaining.
- `failwithf` and `Log` messages. They are addressed to whoever is maintaining Issie, not to
the user, and belong at the point that fails.
- Anything assembled from a design: the components in a combinational loop, the ports of a
mismatched instance. The sentence around such a list can live here; the list cannot.
- The Keyboard Shortcuts tab, which is generated from the shortcut table so that it cannot
drift from the keys that actually fire.

THE RISK THIS RUNS. Text kept away from the code that shows it goes stale - Issie has had that
exact bug, a help menu item whose name had drifted from the panel it opened, so that choosing
it said "Feature not explained". What limits it is that only the words moved: which message to
show, and when, stays at the point that shows it, so a message cannot be reached by a route
this module knows nothing about. Every entry also carries a comment saying what it is and where
it appears, which is what makes an entry that no longer matches its use site noticeable while
reading.

That is weaker than a check. `MarkdownTests` reads every message here and fails on one that
will not render, but nothing yet fails on an entry that has quietly stopped being used, or on a
comment that has stopped being true. Both would be worth adding - the first is a source scan
for each entry's name, of the kind `SourceHygiene` already does for printf.

Markdown is rendered by `Markdown.render` - see that module for the subset supported. Tooltips
are the exception: they are drawn by CSS from a `data-tooltip` attribute, which can hold text
and nothing else, so tooltip entries are plain sentences with no markup.

Nested modules

Modules	Description
Confirm	The bodies of popups that stop and explain before doing something. Only the ones that are several sentences of explanation are here. A one-line body - "The current sheet has unsaved changes." - stays beside the buttons it belongs to, where it is easier to judge than in a list. The buttons, and what they do, stay in the code: what moves is the paragraph that has to persuade the user which button to press.
Expressions	The collapsible "Expression syntax" note under the Properties pane, shown only on a sheet that declares properties. Every numeric box in the pane accepts an expression, but until a sheet has a property there is nothing to write in one except the number the box already holds, so the note would be advertising a feature with no use. See ParameterView.expressionSyntaxHelp.
Fields	What each field in the Properties pane means, shown when its label is hovered. PLAIN TEXT, not markdown. These are drawn by CSS from a `data-tooltip` attribute, which holds characters and nothing else - there is nowhere for a `` to go. Keep each to what the field does and, where there is one, the thing people get wrong. Keyed by the label the field displays, which is what makes a field acquire its explanation by being labelled: no call site passes anything, the same label reads the same way wherever it appears, and a label with no entry here renders with no tooltip rather than the wrong one. A label that is reworded loses its explanation, which is the safe direction to fail in.
Info	The tabs of the Info window, which opens from the Info button and from "New to Issie? Start here" on the startup menu. Its Keyboard Shortcuts tab is not here: it is generated.
Memories	The Memories info button, beside a RAM or ROM's properties. How initial data works, which is the thing people get wrong about memories.
TruthTable	Why the Truth Table tab will not make a table, shown by its "Why is there no table?" button. Plain sentences with no markup, like the field explanations above: these go to `Notifications.errorPropsNotification`, which draws its text into a Bulma notification and holds characters and nothing else. Neither message names the components at fault, which is the rule this module states: a list assembled from a design cannot live here. They are highlighted on the schematic instead, which says the same thing better - the reader looks at the circuit rather than matching labels - and it is what lets these two stay one sentence each. The two conditions are tested in order, so each message may assume the one before it has already been ruled out.
WaveHelp	The waveform simulator's help panels. Three of these names come from the "WaveSimHelp" right-click menu in ContextMenus.fs and must stay spelled the same as the items there; the other two come from the viewer's own Info button. The names are matched in UIPopups.viewWaveInfoPopup, which is where that correspondence is enforced.