4.0 KiB
4.0 KiB
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
f0972f0d5b. - 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, andoverflow-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.