mirr
This commit is contained in:
1 parent
f0972f0d5b
commit
cd82f445d3
2 files changed
+167
-201
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user