4.7 KiB
4.7 KiB
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
- Write the result to
docs/<SourceFileName>.html, named after the source file it documents (for exampledocs/RaylibGLView.htmlforRaylibGLView.swift). - 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
- 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.
- 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.
- Create three columns: line number, source line, explanation.
- 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.
- Do not add obvious explanations such as "Ends the block", "Continuation of the declaration" or descriptions of blank lines. Leave such cells empty.
- 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
- The result is a separate downloadable
.htmlfile opened in a browser. Keep all syntax highlighting and styling inside the file, with no external libraries, fonts, network requests or other external dependencies. - Put the code in
<pre><code>, preserving the original spaces and indentation. Escape HTML special characters so that the displayed code matches the source. - Include syntax highlighting for the relevant language. For Swift, distinguish keywords, types, strings, comments, numbers and directives.
- 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.
- Allow long code lines to wrap while preserving the original indentation:
white-space: pre-wrapandoverflow-wrap: anywhere. Do not require horizontal scrolling to read long expressions. - Do not use alternating coloured row shading.
- 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.
- Do not draw horizontal lines before completely blank lines: visually they abut the preceding fragment.
- Do not draw horizontal lines before lines with an empty explanation, including non-empty code lines. They visually continue the previous group.
- 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
- 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.
- 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.
- 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.
- For unchanged fragments, keep the original explanations verbatim. For the new code, add explanations of its purpose and how it works.
- Apply the same requirements for indentation, wrapping, column widths, explanation merging and horizontal separators to both files.
Verification and handoff
- Verify that the lines and numbering match the chosen version of the source.
- Verify that the original explanations are verbatim and that there are no obvious boilerplate comments instead of substantive explanations.
- Verify that
rowspanis correct, the column borders line up, the code wraps, there is no striped shading, and changes are highlighted only in the number column. - 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.