Support iOS for ogs-blue (#7)

This commit was merged in pull request #7.
This commit is contained in:
kornerr committed 2026-10-30 15:17:24 +01:00
1 parent 37c4e6f442
commit 2b556a4a58
58 files changed
+710 -300

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# Mirrored source-file study documents
Use this workflow when comparing corresponding source files across platforms.
The established example is `docs/render-platform-comparison.html`.
For a single-file study, follow `docs/file-summary.md` instead.
## Source and scope
- Read sources from the exact requested Git revision with `git show REV:path`.
If no revision is specified, use HEAD and record its full commit hash.
- Discover matching relative filenames beneath the two platform directories.
State which platform-only files are excluded; never invent a counterpart.
- Produce one downloadable, self-contained HTML document in `docs/`, with
navigation links and one section per file pair. Preserve earlier documents
unless removal is requested.
- Record both source paths and the source revision. Preserve every source line,
original line number, indentation and blank line. Escape HTML characters.
## Comparison layout
- Use one table per pair with three columns: first platform's numbered source,
second platform's numbered source, and explanation. Do not create separate
line-by-line explanation tables or a Status column.
- Align corresponding function starts where possible. Insert missing-line
placeholders to keep later functions aligned; preserve source order and
original numbers. For example, macOS renderEffect line 12 aligns with iOS
line 16 at revision f0972f0d5ba796e3fa417081f43c00a9654b2aa6.
- Within each function or intervening block, align lines sequentially unless
better semantic alignment is needed. Equal line numbers need not share a row
when function alignment requires padding.
- Compare the exact source text in each aligned row, including whitespace.
Fill BOTH line-number backgrounds green when they match. Fill numbers orange
when they differ. A missing line is an orange-filled dash, not a plain dash.
Keep code backgrounds neutral and retain syntax highlighting.
- Include two filled statistics boxes beneath each section heading: green for
matching line count and percentage, orange for mismatched count and percentage.
Show the total line count as plain text alongside them.
- Count actual lines across BOTH files, including blank lines. A matching pair
contributes two matching lines; a differing pair contributes two mismatches;
a platform-only line contributes one mismatch. Missing placeholders do not
count. Percentages use the combined actual-line total. Recalculate after any
alignment change, and explain this counting convention in the document.
## Explanations
- Explain each distinct point once across the document, at its first relevant
occurrence. Leave later cells empty unless they add information.
- Eliminate semantic repetition, not just identical sentences. Do not repeat
platform/import boilerplate such as “UIKit serves iOS” for every import.
- Explain shared behavior once. Label iOS/macOS details only when needed to
distinguish behavior. Explain the reason or consequence of platform differences.
- Avoid redundant function summaries when the individual operations already
explain the same behavior. Leave blank lines and closing braces unexplained.
- When realigning rows, anchor each platform-specific explanation to its own
source line rather than to the old visual row.
## Presentation and verification
- Inline all CSS and syntax highlighting; no external fonts, scripts or requests.
- Use `<pre><code>`, `white-space: pre-wrap`, and `overflow-wrap: anywhere`.
Give the code columns equal width; ensure long lines remain readable without
horizontal scrolling. Do not use striped row shading.
- Verify every source line and number against the named Git revision, in order,
with no omissions or duplicates. Check function anchors, placeholder fills,
both matching-number fills, statistics, and explanation attachment.
- Review explanations for repeated clauses as well as repeated sentences.
- Inspect the rendered HTML for layout problems. Return a clickable file link;
tell the user to refresh an already open document after updates.