Refine and relocate core_ondisk documentation#17
Conversation
Signed-off-By: Yifan Zhao <yifan.yfzhao@foxmail.com>
There was a problem hiding this comment.
Pull request overview
This PR relocates and expands the EROFS core on-disk format documentation into a dedicated ondisk/ section, updating navigation accordingly.
Changes:
- Add a new
src/ondisk/index.mdlanding page for on-disk format docs. - Move/rewrite the core on-disk format documentation to
src/ondisk/core_ondisk.md. - Update the
design.mdtoctree to point to the new on-disk documentation entry point and remove the old root-levelsrc/core_ondisk.md.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| src/ondisk/index.md | New on-disk documentation index page and toctree entry. |
| src/ondisk/core_ondisk.md | New/relocated core on-disk format spec with detailed structure descriptions. |
| src/design.md | Updates navigation to reference ondisk/index instead of the old core_ondisk.md. |
| src/core_ondisk.md | Removes the previous top-level core on-disk format document. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```{toctree} | ||
| :hidden: | ||
| core_ondisk.md | ||
| ondisk/index | ||
| merging.md |
There was a problem hiding this comment.
The design toctree now points to ondisk/index, but src/merging.md still links to #on_disk_superblock, which only worked when the superblock section was in the same page. Please update that link to a cross-document reference (e.g., a {ref} to the on_disk_superblock label, or a doc link to ondisk/core_ondisk with the anchor) so it doesn't break after this relocation.
There was a problem hiding this comment.
false positive. the link still works in src/merging.md
| # EROFS On-Disk Format | ||
|
|
||
| EROFS uses a compact, block-aligned on-disk layout that is deliberately kept as | ||
| minimal as possible to maximise runtime performance and simplify implementation. |
There was a problem hiding this comment.
Spelling/style consistency: most of the docs use American English (e.g., "maximize" in src/design.md). Consider changing "maximise" here to "maximize" to match the rest of the documentation.
| minimal as possible to maximise runtime performance and simplify implementation. | |
| minimal as possible to maximize runtime performance and simplify implementation. |
There was a problem hiding this comment.
I agree this part, I tend to use AE spelling.
src/ondisk/core_ondisk.md
Outdated
| to utilise unless `namehash` is also introduced, but that complicates the | ||
| overall implementation and expands directory sizes. | ||
|
|
||
| - It is harder to keep filenames and directory entries in the same directory | ||
| block (especially _large directories_) to minimise I/O amplification. |
There was a problem hiding this comment.
Spelling/style consistency: elsewhere in the docs (e.g., src/design.md) uses American English ("utilize", "minimize"). Consider changing "utilise"/"minimise" in this note to "utilize"/"minimize" for consistency.
| to utilise unless `namehash` is also introduced, but that complicates the | |
| overall implementation and expands directory sizes. | |
| - It is harder to keep filenames and directory entries in the same directory | |
| block (especially _large directories_) to minimise I/O amplification. | |
| to utilize unless `namehash` is also introduced, but that complicates the | |
| overall implementation and expands directory sizes. | |
| - It is harder to keep filenames and directory entries in the same directory | |
| block (especially _large directories_) to minimize I/O amplification. |
Signed-off-by: Yifan Zhao <yifan.yfzhao@foxmail.com>
SToPire
force-pushed
the
to-be-merge-core
branch
from
53eef02 to
e77313d
Compare
No description provided.