Files

86 lines
4.7 KiB
Markdown

# Exported tables with a source-file breakdown
This document describes preparing a self-contained HTML file for studying source
code in a browser: a line-by-line table with explanations and, if needed, a
separate version after the code has been changed.
## Output file
1. Write the result to `docs/<SourceFileName>.html`, named after the source file
it documents (for example `docs/RaylibGLView.html` for `RaylibGLView.swift`).
2. The document is the source of truth for the revision it names: capture the
file at the exact Git revision requested and record that revision in the
header, rather than documenting the current working tree.
## Source code and explanations
1. Use the exact version of the file the user requested. For the version prior to
a fix, obtain the contents from the corresponding Git revision rather than
substituting the current file. State the file name and the source revision in
the document.
2. Keep every line of the source, their order, the original numbers, blank lines
and indentation. Do not shorten expressions or reformat code for the sake of
the table.
3. Create three columns: line number, source line, explanation.
4. If the breakdown was already given in the conversation, carry over the original
explanations verbatim. Do not replace them with an abridged retelling or new
wording. Preserve the highlighting and notation from the code.
5. Do not add obvious explanations such as "Ends the block", "Continuation of the
declaration" or descriptions of blank lines. Leave such cells empty.
6. Place the explanation for several lines in a single vertically merged cell of
the third column via `rowspan`. Keep the individual numbers and code of each
line in the first two columns.
## HTML formatting
1. The result is a separate downloadable `.html` file opened in a browser. Keep
all syntax highlighting and styling inside the file, with no external
libraries, fonts, network requests or other external dependencies.
2. Put the code in `<pre><code>`, preserving the original spaces and indentation.
Escape HTML special characters so that the displayed code matches the source.
3. Include syntax highlighting for the relevant language. For Swift, distinguish
keywords, types, strings, comments, numbers and directives.
4. Make the second and third columns equal in width. Keep the number column
narrow; it does not take part in splitting the remaining space in half.
5. Allow long code lines to wrap while preserving the original indentation:
`white-space: pre-wrap` and `overflow-wrap: anywhere`. Do not require
horizontal scrolling to read long expressions.
6. Do not use alternating coloured row shading.
7. Align the horizontal separators in the code and explanation columns. When an
explanation is merged, remove the internal lines between the corresponding
code lines: the borders must separate the same semantic groups.
8. Do not draw horizontal lines before completely blank lines: visually they abut
the preceding fragment.
9. Do not draw horizontal lines before lines with an empty explanation, including
non-empty code lines. They visually continue the previous group.
10. Preserve the readability of the highlighting, the wrapping and the equal
column widths when changing the formatting; editing one property must not
undo the others.
## Separate version after the fix
1. On request, create a second HTML file with the changed version of the source.
Keep the first file with the version prior to the fix.
2. Use the line numbers of the new version. Compare it against the explicitly
stated source revision and determine the lines that were actually added and
changed.
3. Highlight in green only the numbers of the new and changed lines in the first
column. Do not colour entire table rows, the code background or the
explanations. Keep the normal code syntax highlighting.
4. For unchanged fragments, keep the original explanations verbatim. For the new
code, add explanations of its purpose and how it works.
5. Apply the same requirements for indentation, wrapping, column widths,
explanation merging and horizontal separators to both files.
## Verification and handoff
1. Verify that the lines and numbering match the chosen version of the source.
2. Verify that the original explanations are verbatim and that there are no
obvious boilerplate comments instead of substantive explanations.
3. Verify that `rowspan` is correct, the column borders line up, the code wraps,
there is no striped shading, and changes are highlighted only in the number
column.
4. Make sure the HTML is fully self-contained, and give the user a link to the
file. When updating an already open document, tell the user the page needs to
be refreshed.