Skip to content

Fix broken markup, a blank quiz answer, and five misleading statements - #2

Open
wdecoster wants to merge 3 commits into
linuxvoyage:mainfrom
wdecoster:fix-broken-markup-and-quiz-answers
Open

Fix broken markup, a blank quiz answer, and five misleading statements#2
wdecoster wants to merge 3 commits into
linuxvoyage:mainfrom
wdecoster:fix-broken-markup-and-quiz-answers

Conversation

@wdecoster

Copy link
Copy Markdown

Follow-up to #1, from reading the English course end to end. Two commits, kept separate so the mechanical half can be taken on its own if you prefer.

Commit 1 — broken markup and a blank quiz answer

Six mechanical defects, all visible on the published site today:

lesson problem
rm asks "How do you remove a file called myfile?" and the answer panel is blank — the ## Quiz Answer section is empty
regex an unclosed <pre> swallows the Quiz Question and Answer into the code block; src/main.py then finds no <h3>Quiz Question</h3> to split on, so the quiz panel renders as a stray > and the page HTML comes out malformed (</pre></div\n>)
umask <ol> opened twice, never closed
bootloader missing </li>
systemd overview </l> typo
modifying permissions chmod ug+w has no filename — the example as printed just errors

After this, no lesson in the course has unbalanced <ol>/<ul>/<li>/<pre>/<b>/<i> tags, and no lesson asks a quiz question without answering it.

Commit 2 — five statements that mislead beginners

  • help: the --help convention is introduced with echo --help. echo is a shell built-in that doesn't accept it, so the command prints the literal text --help. Switched to ls --help and made the built-in vs program distinction explicit — which is what the lesson is really about.
  • umask: says a umask of 022 means "all user access", implying new files come out rwx. Files start from 666, not 777, so 022 gives 644 for files and 755 for directories. The exercise currently asks readers to predict permissions they then won't see. Added the starting points and the arithmetic.
  • rm: rmdir was presented as just another way to remove a directory; it only works on empty ones, which is the entire reason to prefer it over rm -r.
  • cp: "You can use wildcards in every command" reads as though each command implements globbing. The shell expands them before the command runs.
  • yum and apt: install/remove/update shown without sudo, so a normal user copying them hits a permission error. sudo is taught three sections earlier in Users and Groups.

How the generated files were produced

Not hand-edited. Lesson HTML comes from src/convert.py's converter; the docs/ pages are rewritten with src/main.py's split rules and templates/lesson.html's block layout. Both were checked against lessons this PR does not touch and reproduce them byte-for-byte, so each diff contains only the change described above.

wdecoster and others added 3 commits August 10, 2026 21:24
All six are mechanical defects visible on the published site:

- rm: the lesson asks "How do you remove a file called myfile?" but the
  Quiz Answer section was empty, so the answer panel rendered blank.
- regex: an unclosed <pre> in the Exercise swallowed both the Quiz
  Question and the Quiz Answer into the code block. src/main.py then
  found no <h3>Quiz Question</h3> to split on, so the quiz panel
  rendered as a stray ">" and the page HTML came out malformed
  ("</pre></div\n>").
- umask: <ol> was opened twice and never closed, breaking the exercise list.
- boot-process-bootloader: missing </li> on the initrd item.
- systemd-overview: "</l>" typo instead of "</li>".
- modifying-permissions: "chmod ug+w" had no filename, so the example
  command as printed just errors.

Generated files were rebuilt with the repo's own pipeline rather than
hand-edited: src/convert.py's converter for the lesson HTML, and the
src/main.py split rules plus templates/lesson.html layout for the docs
pages. Both were verified to reproduce untouched sibling lessons
byte-for-byte first, so the diffs contain only these fixes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJFZrUGJ44ozsCe9qqw6bp
- help: the lesson introduced the --help convention with "echo --help".
  echo is a shell built-in and does not accept --help, so that command
  prints the literal text "--help" instead of any help. Switched the
  example to ls --help and spelled out the built-in vs program split,
  which is what the lesson is actually teaching.

- umask: the lesson said a umask of 022 means "all user access", which
  implies a new file comes out rwx. New files start from 666, not 777,
  so 022 gives 644 for files and 755 for directories. As written the
  exercise asks the reader to predict permissions they will then not
  see. Added the 666/777 starting points and worked the arithmetic.

- rm: rmdir was presented as simply another way to remove a directory.
  It only works on empty ones, which is the whole reason to reach for it
  over rm -r.

- cp: "You can use wildcards in every command" suggested wildcards are a
  feature each command implements. Globbing is done by the shell before
  the command runs. Beginners who miss this are the ones later confused
  by things like find . -name *.txt.

- yum and apt: install/remove/update were shown without sudo, so a
  normal user copying them gets a permission error. sudo is taught three
  sections earlier, in Users and Groups.

Generated files rebuilt with the repo's own pipeline, as in the previous
commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJFZrUGJ44ozsCe9qqw6bp
The answer to "What redirector do you use to append output to a file?"
is written as two greater-than signs. Markdown reads that as two nested
blockquotes, so the published page renders

    <blockquote>
    <blockquote></blockquote>
    </blockquote>

and the reader sees nothing where the answer should be. Writing it as
HTML entities makes it display correctly.

Found by checking every lesson for answers whose rendered text is empty.
This is the only one of the 185 where the written answer does not
survive rendering.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJFZrUGJ44ozsCe9qqw6bp
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant