diff --git a/Docs/dictionary-configuration-format.md b/Docs/dictionary-configuration-format.md new file mode 100644 index 0000000000..6b28f8a609 --- /dev/null +++ b/Docs/dictionary-configuration-format.md @@ -0,0 +1,308 @@ +# The Dictionary Configuration File Format + +This document describes the `.fwdictconfig` file that controls how FieldWorks Language +Explorer (FLEx) lays out a dictionary or reversal-index view, and shows how a technical +user can make changes by editing the file directly — including changes the **Configure +Dictionary** dialog cannot make on its own. + +It is written for people who are comfortable editing XML in a text editor and who already +understand FLEx concepts such as writing systems, paragraph vs. character styles, and the +entry/sense structure of a dictionary. + +## When you would edit the file by hand + +Almost everything in a configuration can be set from **Tools ▸ Configure ▸ Dictionary**. +Hand-editing is for the changes the dialog does not expose. This guide walks through two such +edits — equally common, and each impossible from the dialog alone: + +- **Paragraph display on a writing-system field** — show a writing-system field as its own + styled paragraph instead of inline within the entry. +- **Grouping fields under a heading** — collect several unrelated fields into one + organizational block. + +The principle is the same in both: the dialog can adjust a node that already has the +structure in question, but it cannot *add* that structure. Hand-editing adds it — and once it +is there, the dialog reads and preserves it. + +## Where the files live + +There are two locations. + +**Shipped defaults (read-only templates).** These are installed with FieldWorks under the +program's `Language Explorer/DefaultConfigurations/` folder, e.g. +`DefaultConfigurations/Dictionary/Lexeme.fwdictconfig`. FLEx treats these as factory +templates and never writes to them: when you customize a configuration in the dialog, FLEx +saves your changes to a project copy instead of back to the shipped file. They are also +replaced every time FieldWorks is installed or upgraded. + +**Project copies (the editable ones).** When you customize a configuration, FLEx writes a +copy into your project folder under: + +``` +/ConfigurationSettings/Dictionary/ +/ConfigurationSettings/ReversalIndex/ +``` + +These project copies are the files you edit. Don't edit a shipped default: +the program will not persist UI changes there, your edits would be lost on the next +upgrade, and the default only serves as the template that gets cloned into new projects — +it has no effect on a project that already has its own copy. + +## Before you edit: work on a named copy + +1. Open **Configure Dictionary**, click **Manage Configurations…**, select the + configuration closest to what you want, and click **Copy**. Give it a distinct name + (e.g. `Lexeme — paragraphs`). This writes a new file into + `/ConfigurationSettings/Dictionary/`. +2. Close FLEx (so your edits are not competing with an in-memory copy), open that file in a + text editor, and confirm the root element reads `version="26"` (the current version). +3. Make a backup copy of the file before editing. +4. Edit, save, reopen FLEx, and check the result. + +**Edit a named copy rather than a customized factory configuration.** In Manage +Configurations, a configuration that is a customized version of a shipped default shows a +**Reset** button, while a separately-named copy shows a **Remove** button. Reset reloads +the factory defaults over your file and discards every hand edit; Remove deletes the file +outright. Working on a clearly-named copy means the only destructive action available is an +explicit Remove — there is no Reset that would silently restore factory content over your +work. + +**Leave the `version` attribute unchanged.** A copy from a current FLEx is already at the +current version, so the migration FLEx runs on upgrades skips it. See *Appendix: configuration +migration on upgrade* for the mechanics. + +## Anatomy of the file + +The root element is `DictionaryConfiguration`: + +```xml + + + + ... + + +``` + +Each displayed element is a `ConfigurationItem`. Items nest: a `ConfigurationItem` contains +child `ConfigurationItem` elements for its sub-fields, and optionally one options element. +The attributes you will touch most often are: + +| Attribute | Meaning | +| --- | --- | +| `name` | The label shown in the dialog's tree. | +| `field` | The FieldWorks field this node displays (e.g. `DefinitionOrGloss`). Do not invent values. | +| `isEnabled` | Whether the node is shown (`true`/`false`). | +| `before` / `between` / `after` | Literal text inserted before the content, between repeated items, and after the content. | +| `style` | The name of the FLEx style applied to this node. Must be a style that exists in the project. | +| `styleType` | `character` or `paragraph` — whether `style` is a character or paragraph style. Omitted means the default for the node. | +| `cssClassNameOverride` | An alternate CSS class name for export. | + +Writing-system fields carry a writing-system options element as a child: + +```xml + + +``` + +`writingSystemType` is one of `vernacular`, `analysis`, `both`, `pronunciation`, or +`reversal`. Each `Option` names a writing system (`id`) and whether it is shown. + +## Walkthrough: paragraph display on a writing-system field + +A field that displays in one or more writing systems carries one of two option types: + +- `WritingSystemOptions` — the ordinary type; the writing systems are shown inline. +- `WritingSystemAndParaOptions` — a superset that adds the attribute `displayInParagraph`. + When `true`, the field is rendered as its own paragraph in the node's style instead of + inline; its writing systems still appear together within that paragraph. + +The dialog shows a *"display in paragraphs"* checkbox **only on nodes that already carry +`WritingSystemAndParaOptions`** — in the shipped configurations these are the +analysis-writing-system note fields (Grammar Note, Discourse Note, General Note, and so on) +and Encyclopedic Info. It cannot switch a plainly-configured field to the paragraph-capable +type; that switch is the hand edit. + +**Definition (or Gloss)** is one such field — just a "for instance"; the same two edits work +on any node with writing-system options. As shipped in `Lexeme.fwdictconfig` it uses plain +writing-system options, displayed inline: + +```xml + + + + +``` + +To display the definition as its own styled paragraph, make **two** changes: + +```xml + + + + +``` + +1. **Change the options element** from `WritingSystemOptions` to + `WritingSystemAndParaOptions` (both the opening and closing tag) and add + `displayInParagraph="true"`. The `writingSystemType`, `displayWSAbreviation`, and the + `