|
1 | | -# TODO |
| 1 | +# Todo List |
2 | 2 |
|
3 | | -## Small TODOs |
| 3 | +## Immediate Tasks |
4 | 4 |
|
5 | | -- Instead of just saying, "It makes things more clear," explain how it makes things more clear. |
6 | | - - Example: |
7 | | - - **Explanation**: Bash globbing, using patterns like `*`, directly matches filenames in the specified directory without invoking an external command. Unlike `ls`, which produces plain text output that may misinterpret or mishandle filenames containing spaces, newlines, or special characters, Bash globbing handles these scenarios correctly and efficiently. When a glob pattern is used (e.g., `/path/to/dir/*`), the shell itself expands the pattern into a list of matching filenames. This approach ensures that each filename, regardless of its complexity or the characters it contains, is correctly identified and processed. Consequently, Bash globbing is more reliable and secure than parsing the output of ls, which can easily lead to errors or security vulnerabilities when encountering unconventional filenames. |
8 | | -- Ensure terminology is consistent and correct throughout the document. (e.g., "Block statements" vs. "Control statements") |
| 5 | +Pages requiring review and improvement (completed pages are highlighted as green): |
9 | 6 |
|
10 | | -## Big(ger) TODOs |
| 7 | +- [x] Home Page |
| 8 | +- [x] Aesthetics |
| 9 | +- [ ] Bashism |
| 10 | +- [ ] Common Mistakes |
| 11 | +- [ ] Error Handling |
| 12 | +- [ ] Style |
11 | 13 |
|
12 | | -- Add a section explaining the perils of using `eval` and why it should be avoided. |
13 | | -- Add a section explaining how to properly use `set -e`. |
14 | | -- Add information regarding how to deal with logical operators (or redirect and i/o operators), similar to that of inside "Formatting Multi-lined Commands", to _____... |
15 | | -- Add information to (some section) specifying that global variables should often be placed at the top of the script. This ensures that the script isn't reliant on variables defined within a function. (or something like that) |
16 | | -- While out of scope of this document, consider adding information to "Using Quotes" in style.md about the background of using quotes and how they are used in other programming languages. This could help readers understand the importance of quotes in Bash and why they should be used consistently. |
17 | | -- Add a section describing the importance of shebangs... |
| 14 | +Action items for these pages: |
| 15 | + |
| 16 | +- Replace vague explanations (like "It makes things more clear") with specific, detailed reasoning. |
| 17 | + - **Example**: |
| 18 | + - **Explanation**: Bash globbing, using patterns like `*`, directly matches filenames in the specified directory without invoking an external command. Unlike `ls`, which produces plain text output that may misinterpret or mishandle filenames containing spaces, newlines, or special characters, Bash globbing handles these scenarios correctly and efficiently. When a glob pattern is used (e.g., `/path/to/dir/*`), the shell itself expands the pattern into a list of matching filenames. This approach ensures that each filename, regardless of its complexity or the characters it contains, is correctly identified and processed. Consequently, Bash globbing is more reliable and secure than parsing the output of ls, which can easily lead to errors or security vulnerabilities when encountering unconventional filenames. |
| 19 | +- Standardize terminology throughout the document (e.g., consistently use either "Block statements" or "Control statements", not both). |
| 20 | + |
| 21 | +## Substantial Enhancements |
| 22 | + |
| 23 | +- [ ] Create a dedicated section detailing the dangers of `eval` usage and recommended alternatives. |
| 24 | +- [ ] Develop comprehensive guidelines for the proper implementation of `set -e` with examples. |
| 25 | +- [ ] Document best practices for working with logical operators and I/O redirection operators, following the format established in the "Formatting Multi-lined Commands" section. |
| 26 | +- [ ] Add guidance on variable scope best practices, emphasizing that global variables should be declared at the script's beginning to prevent dependency issues with function-local variables. |
| 27 | +- [ ] Consider expanding the "Using Quotes" section in style.md to include comparative context from other programming languages, highlighting why consistent quoting practices are particularly important in Bash. |
| 28 | +- [ ] Draft a new section explaining shebang (`#!`) importance, proper syntax, and common implementations. |
0 commit comments