69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
# 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.
|