# MSet Instruction Author 01 - Concepts and instruction packages Status: **canonical-development** Branch: **MSet 64-bit** Current product: **MSet 2026 by GRAPHICO** Format covered: **MSet 2026 native instruction format 2026.1 plus legacy-readable packages** ## Purpose This is the first required module for an LLM that will read, explain, create, or modify an MSet 64-bit instruction. After this module, the model should understand what an MSet instruction is, how an instruction package is organized, which XML nodes form the visible instruction tree, and which files must be inspected before editing. This module does **not** yet teach full command composition, scale substitutions, Bentley key-in syntax, or Annotation Scale behavior. Do not claim full MSet Instruction Author capability after reading this module alone. ## Source authority For the 64-bit branch, use this precedence when sources disagree: 1. current MSet 2026 runtime/parser behavior and current contract tests, 2. current MSet 2026 specifications and accepted project decisions, 3. current runtime-verified MSet 2026 instruction packages, 4. MSet 10 manual and other legacy documentation. Do not import MSet 32-bit/V8i rules unless the user explicitly requests comparison or migration. ## 1. What is an MSet instruction? An MSet instruction is XML content that defines both: - the visible command structure presented by MSet, and - command fragments that MSet can send to the active Bentley host. The XML entry document is consumed by MSet and converted into the runtime instruction model. An instruction may be a single XML file, but real instructions can also be multi-file packages. ## 2. An instruction may be a package Do not assume that the entry XML contains the complete instruction definition. A package may contain: - the entry `.xml` file, - a DTD file, - external entity files such as `.ent`, - XML fragments such as `.ixml`, - other support files referenced by the XML or entities. A current runtime-verified package uses this shape: ```text MSet_Polohopis.xml MSet_Polohopis/ _mset.dtd _mset.ent texty.ent chranicky.ixml formaty.ixml popis1.ixml popis2.ixml popis3.ixml ``` The entry XML references files below `MSet_Polohopis/`. Those files can in turn reference other files or define entities that expand into command fragments or complete XML node fragments. ### Editing rule Before modifying an instruction package: 1. identify the entry XML, 2. inspect its DTD/entity declarations, 3. follow all relevant external entity/include references, 4. locate the real source of the content that must change, 5. preserve meaningful relative paths and package structure. Do not edit only the expanded appearance of a package if the actual source is an entity or included fragment. ## 3. Relative paths are part of the package contract External DTD/entity/include references are resolved relative to the instruction document and its referenced files. Therefore, when moving, copying, or returning a modified package: - preserve the directory layout when relative references depend on it, - do not flatten package files without deliberately rewriting and validating all affected references, - treat the complete package as one logical artifact. ## 4. Preserve the existing encoding Legacy documentation describes MSet instructions as ANSI text. Current MSet 2026 does not impose one universal source encoding for every instruction. The current runtime-verified `MSet_Polohopis` package explicitly uses `windows-1250` and is supported by MSet 2026. ### Canonical editing rule Preserve the existing encoding of each instruction/package file unless the user explicitly requests an encoding migration and the migrated package is validated. Do **not** assume that every MSet 2026 instruction must be UTF-8. Do **not** assume that every new MSet 2026 instruction must be Windows-1250. ## 5. Entry XML and Signum The XML root element must be `Instruction`. For MSet 2026 native-format instructions, the current supported format version is: ```xml FormatVersion="2026.1" ``` A missing `FormatVersion` is accepted as legacy compatibility mode. Do not invent another format version. The instruction Signum is not stored as an XML attribute. It is derived from the entry XML filename without its extension and converted to upper case. Example: ```text MSet_Polohopis.xml -> MSET_POLOHOPIS ``` `DisplayName` is an optional human-facing root attribute. For a new native-format instruction, prefer an explicit descriptive `DisplayName`. MSet 2026 also supports optional Instruction-level appearance metadata: ```text TextColor BackgroundColor ``` The canonical authoring representation is six-digit RGB hex (`#RRGGBB`). These attributes affect the MSet instruction UI only; they are not MicroStation element symbology and they are not named Bentley resources. Because both attributes are optional metadata, their addition does **not** change the native format number: `FormatVersion="2026.1"` remains current. When present and valid, Instruction-level colors take precedence over the per-user appearance fallback for that instruction. When absent, the existing user/default appearance remains in effect. Schematic example: ```xml ... ``` This is a structural example only; it is not a complete package template. ### DTD is mandatory **Every MSet instruction must have a DTD.** The DTD is part of the MSet instruction contract, not an optional style convention. Use the DTD form that matches the package shape: - multi-file instruction package -> keep the DTD/entity structure as package files and preserve all relative references, - deliberately self-contained single-file instruction -> embed the current MSet instruction DTD as an internal DTD subset. A DTD-less XML document is **not a valid MSet instruction for authoring purposes**, even if a permissive parser path might technically load such XML. Do not create or return an MSet instruction without its DTD. Current MSet 2026 DTD contract: ```xml ]> ``` A self-contained MSet 2026 instruction using this internal subset was runtime-loaded successfully in MSet `26.11.0.4` inside MicroStation 2026 on 2026-08-24. The same test also confirmed that its declared `` were accepted and the active MSet scale could be changed. This runtime evidence confirms that the internal-subset form is supported for a self-contained native instruction. The product authoring contract still requires a DTD in every MSet instruction. ## 6. Core XML node types The visible instruction hierarchy is built from these concepts: ```text Instruction +- optional Scales +- Page +- Group | +- Group | | +- Feature | +- Feature +- Feature ``` The exact allowed structure is governed by the instruction format/DTD and current parser rules. ### `Instruction` `Instruction` is the root node of the entry document. It can contain Pages and may contain an optional `Scales` element. Direct command text on `Instruction`, when present, is a lifecycle command executed when the instruction becomes active. It is not inherited into Feature effective commands. ### `Scales` `Scales` is optional. If present, its current parser rules require positive integer scale values and a positive `PrimaryScale` that is included in the declared scale list. A valid MSet 2026 instruction may omit `Scales`; MSet then uses its runtime defaults. Detailed scale behavior is taught in a later module. ### `Page` A `Page` represents one named page/tab in the MSet UI. Current rules: - `Cpt` is required, - a Page contains instruction-tree content, - direct Page command text is a Page lifecycle command, - the Page command is separate from Feature effective command composition. The first Page is also activated when an instruction initially becomes active. ### `Group` A `Group` is a navigational and inheritable command scope. Current rules: - `Cpt` is required, - a Group may contain nested Groups and/or Features, - a Group may contain its own local command fragment, - Group command fragments can contribute to descendant Feature execution. Detailed inheritance and composition are taught in the command-composition module. #### Canonical child ordering inside a `Group` The DTD permits `Group` and `Feature` children to be interleaved. For newly authored instructions, however, use this **default UI-authoring convention**: 1. local Group command text immediately after the opening `Group` tag, 2. nested `Group` children, 3. direct `Feature` children. In short: **Groups first, Features second, as a rule.** This is a style convention, not a parser restriction. An intentional exception is allowed when a different order clearly improves the user workflow. Do not reorder an existing instruction merely for aesthetics unless the user requested that cleanup. ### `Feature` A `Feature` is an executable leaf in the instruction tree. Current rules: - `Cpt` is required, - a Feature may contain command text, - a Feature may not contain child instruction nodes, - selecting a Feature causes MSet to build and dispatch its effective command. A Feature with empty local command text is valid. It may still receive effective behavior from ancestor Groups. ## 7. `Cpt` is display text, not a stable technical identifier `Cpt` supplies the visible caption of a Page, Group, or Feature. Do not assume captions are globally unique. Real instruction packages can contain repeated captions. When describing or editing a node, identify it by structural context/path when necessary, for example: ```text Page "Kreslenie" -> Group "400 Kataster nehnutelnosti" -> Group "402 UO" -> Feature "Hranica parcely" ``` Do not invent a technical ID from `Cpt` unless the format explicitly defines one. ## 8. Package-aware editing rules When an LLM is asked to modify an MSet instruction: - inspect the complete relevant package first, - preserve the entry filename unless the requested change requires a rename, - remember that renaming the entry XML changes its derived Signum, - preserve DTD/entity/include relationships, - preserve existing encoding unless migration is explicit, - change the real source file when content comes from an entity/include, - avoid duplicating entity-expanded content directly into the entry XML without a deliberate reason, - preserve unrelated structure and commands, - do not invent unsupported elements, attributes, macros, or Bentley key-ins, - do not treat a runtime-verified example as automatically defining the best style for all new instructions. ## 9. Example evidence vs. canonical rules A working package is strong evidence that MSet can load and execute that package. It is not automatically a recommendation to copy every historical or environment-specific detail into a new instruction. Examples in this knowledge base can be classified as: - `canonical-example` - recommended pattern for new authoring, - `runtime-verified` - known to work, but may contain historical or environment-specific content, - `legacy-example` - historical material for study, - `specialized-example` - product/workflow-specific material. Canonical learning rules take precedence over example style when the two differ. ## 10. What is deliberately not taught yet Do not infer missing behavior from this module. The following require later modules/reference pages: - exact Group-to-Feature command composition, - command separators and normalization details, - `$S`, `$C`, `$X`, - standard ScaleFactor substitutions, - exact scale-sensitive command syntax, - Bentley/MicroStation/OpenRail/OpenRoads key-in catalogues, - Annotation Scale behavior, - MSet control macros such as historical `$M(...)` semantics. In particular, do not generate `$M(...)` for MSet 2026 based only on legacy documentation. ## Completion check Before proceeding to the next Instruction Author module, the model should be able to answer all of these correctly: 1. Is an MSet instruction always only one XML file? **No.** 2. What is the required root element? **`Instruction`.** 3. What native `FormatVersion` is currently supported? **`2026.1`.** 4. What does missing `FormatVersion` mean? **Legacy compatibility mode.** 5. Where does Signum come from? **The entry XML filename without extension, upper-cased.** 6. May an editor ignore DTD/entity/include files? **No.** 7. Should an editor automatically convert CP1250 packages to UTF-8? **No.** 8. Is `Cpt` guaranteed to be a unique technical ID? **No.** 9. Is `Feature` an executable leaf? **Yes.** 10. For a newly authored self-contained single-file native instruction, what is the canonical DTD form? **Embed the current MSet DTD as an internal subset.** 11. Inside a newly authored Group, what child order should normally be used? **Nested Groups first, then direct Features.** 12. Does this module alone make the model a complete MSet Instruction Author? **No.** Next planned module: `02-command-composition.md`.