various docs fixes #659
various docs fixes #659
Conversation
leggewie
commented
Mar 23, 2025
•
- s/containin/containing/ (already approved by @EvilOlaf)
- various rewordings
- and most importantly, an outdated reference to lib/configuration.sh updated
s/containin/containing/
commit a4a4cc3 moved lib/configuration.sh to lib/functions/configuration/main-config.sh
WalkthroughThe update refines documentation by addressing grammatical issues and improving clarity. Text modifications include the addition of articles, correction of typographical errors, and slight rewording of instructions related to patch handling and image customization. The configuration file path has been updated to point to a more specific location. Additionally, a reference to vendor firmware images has been corrected to fix a typographical error. There were no changes made to the declarations of exported or public entities. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/User-Guide_Getting-Started.md (1)
71-71: Typo Correction Verified & Style SuggestionThe corrected typo is now fixed, ensuring that the previously misspelled word is properly rendered. As an optional improvement for style and clarity, consider hyphenating the compound adjective to yield “vendor‐provided kernel” rather than “vendor provided kernel.”
🧰 Tools
🪛 LanguageTool
[grammar] ~71-~71: A determiner may be missing.
Context: ...ns vendor provided kernel which usually has best hardware support while version can be o...(THE_SUPERLATIVE)
docs/Developer-Guide_User-Configurations.md (4)
5-5: Clarify and Polish Patch InstructionsThe introductory sentence for user patches is now updated; to further improve clarity, consider inserting a definite article and adjusting punctuation. For example, rephrase:
- Current: “User patches directory structure mirrors directory structure of
patch.”- Suggested: “The user patches directory structure mirrors that of the
patchdirectory.”
This change can enhance readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~5-~5: Possible missing comma found.
Context: ...ory, for kernel or u-boot. There are no limitations except that all patches must have the f...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~5-~5: You might be missing the article “the” here.
Context: ...ser patches directory structure mirrors directory structure ofpatch. Look for the hint...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~5-~5: Possible missing article found.
Context: .... Look for the hint at the beginning of patching process to select the proper directory ...(AI_HYDRA_LEO_MISSING_THE)
10-10: Grammar Correction in Patch Override InstructionThe sentence “Patches with the same file name and path in
userpatchesdirectory tree override those one inpatch.” contains a grammatical error. Replacing “those one” with “those in the” makes the instruction clearer.-Patches with the same file name and path in `userpatches` directory tree override those one in `patch`. +Patches with the same file name and path in the `userpatches` directory tree override those in the `patch` directory.
22-22: Fix Word Order in Kernel Config HintThere is a minor word order issue in the phrase “to the select proper config file name.” Changing it to “to select the proper config file name” improves grammatical correctness.
-Look for the hint at the beginning of the kernel compilation process to the select proper config file name. +Look for the hint at the beginning of the kernel compilation process to select the proper config file name.🧰 Tools
🪛 LanguageTool
[uncategorized] ~22-~22: These words/punctuation marks might seem a little out of order. For clarity and coherence, try switching them around.
Context: ...ng of the kernel compilation process to the select proper config file name. Example: ...(AI_EN_LECTOR_REPLACEMENT_WORD_ORDER)
43-43: Ensure Language ConsistencyThe text “...just before finalising the image.” should use American English for consistency with the project guidelines. Consider changing “finalising” to “finalizing.”
-... just before finalising the image. +... just before finalizing the image.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/Developer-Guide_User-Configurations.md(2 hunks)docs/User-Guide_Getting-Started.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/User-Guide_Getting-Started.md
[grammar] ~71-~71: A determiner may be missing.
Context: ...ns vendor provided kernel which usually has best hardware support while version can be o...
(THE_SUPERLATIVE)
docs/Developer-Guide_User-Configurations.md
[uncategorized] ~5-~5: Possible missing comma found.
Context: ...ory, for kernel or u-boot. There are no limitations except that all patches must have the f...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~5-~5: You might be missing the article “the” here.
Context: ...ser patches directory structure mirrors directory structure of patch. Look for the hint...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~5-~5: Possible missing article found.
Context: .... Look for the hint at the beginning of patching process to select the proper directory ...
(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~22-~22: These words/punctuation marks might seem a little out of order. For clarity and coherence, try switching them around.
Context: ...ng of the kernel compilation process to the select proper config file name. Example: ...
(AI_EN_LECTOR_REPLACEMENT_WORD_ORDER)
🔇 Additional comments (6)
docs/Developer-Guide_User-Configurations.md (6)
14-14: User Configuration Explanation ClearThe explanation regarding the behavior of
userpatches/lib.configis clear and informative.
29-29: User Provided Sources Config Overrides Are ClearThe instructions for handling
userpatches/sources/$LINUXFAMILY.confare well written and need no further modifications.
39-39: Instruction for Image Customization is ClearThe directive to customize the image by editing
userpatches/customize-image.shis straightforward. No changes are necessary here.
45-45: Overlay Directory Instruction ClearThe instructions on adding files to the image via the overlay directory are clear and concise.
47-47: Architecture Note ClarificationThe note regarding how additional apt packages and commands are handled based on the target architecture is informative and clearly presented.
53-53: Partition Expansion Instruction is DetailedThe explanation about preventing or configuring partition expansion using
/root/.no_rootfs_resizeor/root/.rootfs_resizeis thorough and clear.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/Developer-Guide_User-Configurations.md (5)
5-5: Refine Article Usage and Punctuation in Patch Instructions.
The updated text is clearer; however, consider inserting the definite article "the" (e.g. “outside the build script”) and adding a comma after “directory” (in “appropriate directory, for kernel or u-boot”) to enhance readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~5-~5: Possible missing comma found.
Context: ...ory, for kernel or u-boot. There are no limitations except that all patches must have the f...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~5-~5: You might be missing the article “the” here.
Context: ...ser patches directory structure mirrors directory structure ofpatch. Look for the hint...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~5-~5: Possible missing article found.
Context: .... Look for the hint at the beginning of patching process to select the proper directory ...(AI_HYDRA_LEO_MISSING_THE)
14-14: Enhance Clarity for Configuration File Usage.
The explanation foruserpatches/lib.configis clear. If applicable, you might replace “it will be called” with “it will be sourced” to better reflect typical shell behavior. Also, check for any extra spaces before references such aslib/functions/configuration/main-config.sh.
29-29: Ensure Consistent File Reference Terminology.
Consider changing “If fileuserpatches/sources/$LINUXFAMILY.confexists” to “If the fileuserpatches/sources/$LINUXFAMILY.confexists” for consistency with other sections.
46-46: Clarify Architecture-Specific Behavior.
The note on how additional apt packages or commands incustomize-image.share handled is informative. A slight rewording could further clarify that these commands are executed in a virtualized environment matching the target SBC’s architecture.
52-52: Improve Clarity on Partition Resize Instructions.
The explanation on preventing partition expansion and configuring resize operations is comprehensive but a bit lengthy. Consider rephrasing it and adding commas to clearly separate clauses. For example:-You can prevent the partition expansion from within `customize-image.sh` by a `touch /root/.no_rootfs_resize` or configure the resize operation by either a percentage or a sector count using `/root/.rootfs_resize` (`50%` will use only half of the card's size if the image size doesn't exceed this or `3887103s` for example will use sector 3887103 as partition end. Values without either `%` or `s` will be ignored). +You can prevent the partition expansion from within `customize-image.sh` by executing `touch /root/.no_rootfs_resize`, or you can configure the resize operation by specifying a percentage or a sector count using `/root/.rootfs_resize` (for example, `50%` will use only half of the card's size if the image size doesn't exceed this, and `3887103s` will indicate that the partition should end at sector 3887103; values without either `%` or `s` will be ignored).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/Developer-Guide_User-Configurations.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/Developer-Guide_User-Configurations.md
[uncategorized] ~5-~5: Possible missing comma found.
Context: ...ory, for kernel or u-boot. There are no limitations except that all patches must have the f...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~5-~5: You might be missing the article “the” here.
Context: ...ser patches directory structure mirrors directory structure of patch. Look for the hint...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~5-~5: Possible missing article found.
Context: .... Look for the hint at the beginning of patching process to select the proper directory ...
(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~50-~50: Possible missing comma found.
Context: ...you define $FIXED_IMAGE_SIZE at build time the partition containing the rootfs wil...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (4)
docs/Developer-Guide_User-Configurations.md (4)
22-22: Good Clarity in Config File Instructions.
The instructions for usinguserpatches/linux-$LINUXFAMILY-$BRANCH.configare clear and concise.
38-38: Clear Instructions for Custom Image Customization.
The updated text provides straightforward guidance on customizing the image by editing the designated file.
42-42: Straightforward Guidance on Placing Custom Code.
The explanation about placing your custom code and testing variables is clear and well-structured.
44-44: Concise File Addition Instructions.
The instructions on how to add files to the image by usinguserpatches/overlayare directly understandable.
|
|
||
| [ o.k. ] Started patching process for [ kernel sunxi-edge 4.4.0-rc6 ] | ||
| [ o.k. ] Looking for user patches in [ userpatches/kernel/sunxi-edge ] | ||
|
|
||
| Patch with same file name in `userpatches` directory tree substitutes one in `patch`. To _replace_ a patch provided by Armbian maintainers, copy it from `patch` to corresponding directory in `userpatches` and edit it to your needs. To _disable_ a patch, create empty file in corresponding directory in `userpatches`. | ||
| Patches with the same file name and path in the `userpatches` directory tree override those one in the `patch` directory. To _replace_ a patch provided by Armbian maintainers, copy it from `patch` to the corresponding directory in `userpatches` and edit it to your needs. To _disable_ a patch, create an empty file in the corresponding directory in `userpatches`. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Clarify Override Instructions for Patches.
The phrase “override those one in the patch directory” is a bit awkward. Consider rephrasing it to, for example, “override the patches in the patch directory” or “override the patch provided in the patch directory” for improved clarity.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/Developer-Guide_User-Configurations.md (1)
10-10: Improve Override Instruction Wording.
The phrase “override those one in thepatchdirectory” still sounds awkward. Consider rephrasing it to “override the patches in thepatchdirectory” or “override the patch provided in thepatchdirectory” for better clarity. This comment is similar to a previous suggestion.
🧹 Nitpick comments (1)
docs/Developer-Guide_User-Configurations.md (1)
52-52: Nitpick on Partition Resize Configuration Instructions.
The sentence is clear overall but could be improved with minor punctuation and wording adjustments. For example, consider adding a comma after “for example” and rephrasing “by atouch /root/.no_rootfs_resize” to “by executingtouch /root/.no_rootfs_resize” for enhanced clarity.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/Developer-Guide_User-Configurations.md(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/Developer-Guide_User-Configurations.md
[uncategorized] ~50-~50: Possible missing comma found.
Context: ...you define $FIXED_IMAGE_SIZE at build time the partition containing the rootfs wil...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (7)
docs/Developer-Guide_User-Configurations.md (7)
5-6: Clarify Patch Placement Instructions.
The updated wording clearly specifies that patches can be added outside the build script and placed in the appropriate directories for kernel or u-boot. Overall, the text is straightforward and improves clarity.
14-14: Updated Configuration File Reference.
The text now correctly referenceslib/functions/configuration/main-config.sh, which clearly indicates the location for available configuration variables.
22-22: User Kernel Config Instructions Clarity.
The instructions regarding the use of a custom kernel configuration file are concise and clear.
38-38: Clear Image Customization Introduction.
The directive to run additional commands to customize the image and the prompt to edit a specific file are well communicated.
42-42: Detailing Customization Script Usage.
The explanation on where to place code in the customization script and how it will be executed (within a chroot environment before finalizing the image) is clear and helpful.
44-44: Overlay Files Inclusion Guidance.
The instruction on how to add files to the image using theuserpatches/overlaydirectory and access them via/tmp/overlayin the script is straightforward.
46-46: Advisory on Architecture-Specific Execution.
The note that commands incustomize-image.shwill automatically be installed/executed/virtualized for the build target's architecture is informative and clear.
|
I suggest to go through rabbits suggestions. Otherwise good. |
|
Closing in favor of #669 (mess due main branch change) |