doc: change doc hierarchy

DEVNOTE.md

@@ -71,4 +71,4 @@ TODO...
 ### Bump Manifest Version Up
 
 - Update version value in document `doc/manifest.md`.
-- Update version value in example `doc/example.*.toml`.
+- Update version value in example `example/*.toml`.

doc/render-context.md

@@ -0,0 +1,22 @@
+# Render Context
+
+A render context is the set of top-level variables that MetaGlot passes into a user-provided Liquid template when `metaglot render` executes. The context carries the resolved translation data — one entry per language read from the PO files, each holding the text of every manifest entry — together with the extra variables a metadata type needs, such as the manifest's source language or per-language identifiers.
+
+Every rendering shares the following semantics:
+
+- Templates are read as UTF-8, and the rendered output is written as UTF-8 (without BOM) using the system's native line endings. The parent folder of an output file is created when it does not exist.
+- The renderer runs in strict mode: referencing a variable or a property that does not exist fails the render.
+- The text of an entry falls back to the manifest source string when the entry is untranslated, missing from the PO file, or marked fuzzy.
+- The language of a PO file is resolved from its `Language:` header, falling back to the file name without extension; two PO files describing the same language and PO entries unknown to the manifest are rejected.
+- Some metadata types consist of multiple files; for them the `--*-path` command line arguments are themselves in-memory Liquid templates, rendered with the same mechanism into per-file output paths.
+
+Filters are documented separately in [filters.md](filters.md).
+
+The render context of every supported metadata type is described in its own document:
+
+- [Windows RC resource files](render-context/rc.md) — language identifiers, string table statements and version information values.
+- [Windows MSIX packages](render-context/msix.md) — the package manifest and the per-language resources files.
+- [Windows InnoSetup scripts](render-context/inno.md) — the installation script and the per-language messages files.
+- [Linux desktop entries](render-context/desktop.md) — localized keys with locale postfixes.
+- [Linux AppStream metadata](render-context/appstream.md) — translations marked with `xml:lang`.
+- [macOS bundles](render-context/plist.md) — the bundle `Info.plist` and the per-language `InfoPlist.strings` files.

doc/render-context/appstream.md

@@ -45,4 +45,4 @@ AppStream uses the element without `xml:lang` as the untranslated default, mirro
 
 ## Filters
 
-All filters described in [filters.md](filters.md) are available when rendering AppStream XML files: the general filters available in every rendering, and the AppStream filters such as `xml_escape`. Note that translated descriptions may legitimately carry AppStream markup (e.g. `<em>`); such values must not be passed through `xml_escape`, and deciding what to escape is the template author's responsibility.
+All filters described in [filters.md](../filters.md) are available when rendering AppStream XML files: the general filters available in every rendering, and the AppStream filters such as `xml_escape`. Note that translated descriptions may legitimately carry AppStream markup (e.g. `<em>`); such values must not be passed through `xml_escape`, and deciding what to escape is the template author's responsibility.

doc/render-context/desktop.md

@@ -41,4 +41,4 @@ Name={{ default.strings.name | desktop_escape }}
 
 ## Filters
 
-All filters described in [filters.md](filters.md) are available when rendering desktop entry files: the general filters available in every rendering, and the desktop filters such as `desktop_escape`.
+All filters described in [filters.md](../filters.md) are available when rendering desktop entry files: the general filters available in every rendering, and the desktop filters such as `desktop_escape`.

doc/render-context/inno.md

@@ -38,7 +38,7 @@ Keep the `case` branches aligned with the languages you ship PO files for: an un
 
 ## Path Template Contexts
 
-The `--iss-path` and `--isl-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](filters.md) are available to them.
+The `--iss-path` and `--isl-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](../filters.md) are available to them.
 
 ### `--iss-path`
 

doc/render-context/msix.md

@@ -10,7 +10,7 @@ Every component below renders with its **own environment**, so the filters avail
 
 ## Path Template Contexts
 
-The `--manifest-path` and `--resources-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](filters.md) are available to them.
+The `--manifest-path` and `--resources-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](../filters.md) are available to them.
 
 ### `--manifest-path`
 

doc/render-context/plist.md

@@ -10,7 +10,7 @@ Every component below renders with its **own environment**, so the filters avail
 
 ## Path Template Contexts
 
-The `--plist-path` and `--strings-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](filters.md) are available to them.
+The `--plist-path` and `--strings-path` arguments are in-memory Liquid templates rendered into output paths. Only the general filters described in [filters.md](../filters.md) are available to them.
 
 ### `--plist-path`
 

doc/render-context/rc.md

@@ -37,4 +37,4 @@ The resolved text of an entry falls back to the manifest source string when the
 
 ## Filters
 
-All filters described in [filters.md](filters.md) are available when rendering RC files: the general filters available in every rendering, and the RC filters such as `rc_escape`.
+All filters described in [filters.md](../filters.md) are available when rendering RC files: the general filters available in every rendering, and the RC filters such as `rc_escape`.