Improve Chapter 01 notation conventions lesson

docs/lessons/01_where_to_start/1.05_notation_and_typographical_conventions.md

@@ -1,63 +1,212 @@
-### Subchapter 1.05: Notation and Typographical Conventions
-
+## 1.05 Notation and Typographical Conventions
 
+Linux documentation is dense because it has to describe commands, files, user
+input, program output, optional arguments, placeholders, and warnings in a small
+space. This section explains the conventions used throughout the course so you
+can copy examples carefully and adapt them without guessing.
 
 !!! abstract "What you will learn"
-    - Explain where **Subchapter 1.05: Notation and Typographical Conventions** fits in day-to-day Linux operations.
-    - Use current Linux tooling to inspect, change, and verify the relevant system behavior.
-    - Connect the concept to a real operational scenario: a first-week junior admin onboarding into a small cloud team.
-
-!!! example "Field story"
-    Imagine a first-week junior admin onboarding into a small cloud team. Your job is not to memorize a command; it is to build a short evidence trail, choose a low-risk change, and prove whether the system improved.
+    - Distinguish literal commands from placeholders, prompts, and output.
+    - Read command syntax examples without copying explanatory punctuation.
+    - Recognize when examples require root privileges or a safe lab system.
+    - Record commands and results in a way another operator can reproduce.
 
 !!! success "Operator principle"
-    Identify the OS, distribution, support window, and package source before changing anything.
+    Copy commands only after you understand which parts are literal, which parts
+    are local values, and which parts affect the system.
 
-## Hands-on practice
+## Command Prompts
 
-Run these on a disposable VM, container, or lab machine unless the lesson explicitly says otherwise.
+Examples may show a prompt before a command. The prompt is context, not part of
+the command.
 
-1. Inspect the current state with a read-only command related to this topic.
-2. Save the command and output in a short lab note.
-3. Make one reversible change or simulate the change in a sandbox.
-4. Re-run the inspection and explain what changed.
+```console
+$ whoami
+student
+```
 
-## Check your understanding
+In this course:
 
-- What evidence would tell you that this system is healthy?
-- What is the riskiest command in this lesson, and how would you make it safer?
-- How would you explain section 1.5 to a teammate during an incident handoff?
+- `$` means a regular user shell.
+- `#` means a root shell or a command that requires administrative privileges.
+- Lines without a prompt are usually command output.
 
+Do not paste the prompt character itself. From the example above, run only:
 
-In the Linux world, notations and typographical conventions play a significant role in coding and understanding scripts.
+```bash
+whoami
+```
 
-To begin with, let’s talk about shebang (`#!`). It is the first line of any script that tells the system what interpreter to use for running the script. For example:
+When a command needs elevated privileges, the safer habit is to use `sudo` for a
+single command instead of switching into a long-lived root shell:
 
 ```bash
-#!/bin/bash
-echo "Hello, World!"
+sudo systemctl status ssh
 ```
 
-In this script, `#!/bin/bash` instructs the system to use `bash` as the interpreter to run the rest of the script, which is `echo "Hello, World!"`.
+## Literal Text and Placeholders
+
+Text in backticks is usually literal: type it exactly as shown unless the lesson
+says otherwise. Placeholder values stand for something from your own system.
+
+```bash
+ssh username@hostname
+```
+
+In that example, replace `username` and `hostname` with real values, such as:
+
+```bash
+ssh student@lab-vm-01
+```
+
+Common placeholder styles include:
+
+- `example.com`: a documentation domain, not a real target for your lab unless
+  the lesson explicitly uses it for a harmless test.
+- `HOSTNAME`, `USERNAME`, or `DEVICE`: values you must replace.
+- `/path/to/file`: a file path pattern, not necessarily an existing path.
+- `...`: omitted output or repeated arguments.
+
+## Syntax Markers in Manuals
+
+Manual pages often use compact notation. These symbols are descriptive; they are
+not usually typed as part of the command.
+
+| Marker | Meaning | Example |
+| --- | --- | --- |
+| `[value]` | Optional value | `ls [FILE]` can run as `ls` or `ls /tmp` |
+| `value...` | One or more values | `cp SOURCE... DIRECTORY` can copy many files |
+| `A \| B` | Choose one option | `systemctl start \| stop UNIT` |
+| `<name>` | Placeholder in some docs | Replace `<name>` with a real value |
+
+For example, this syntax summary:
+
+```text
+systemctl status [UNIT...]
+```
+
+Means both of these are valid:
+
+```bash
+systemctl status
+systemctl status ssh
+```
+
+It does not mean you should type the square brackets.
+
+## Files, Directories, and Programs
+
+The course uses a few typographical conventions consistently:
+
+- Commands and programs: `systemctl`, `grep`, `ssh`
+- Files and directories: `/etc/os-release`, `/var/log/`, `~/.ssh/config`
+- Services and units: `ssh.service`, `cron.service`
+- Environment variables: `PATH`, `HOME`, `SHELL`
+- Keyboard keys: `Ctrl+C`, `Tab`, `Enter`
 
-Next up, we have the commenting convention. Anything that follows the hash symbol (`#`) till the end of the line is regarded as a comment and is ignored by the interpreter. It's essential for leaving notes or summarizing the function of a line of code. For instance:
+Paths matter. `/etc/ssh/sshd_config` and `~/.ssh/config` are different files
+with different purposes. Before changing any file, inspect the exact path:
 
 ```bash
-# This script prints "Hello, World!"
-echo "Hello, World!"
+ls -l /etc/ssh/sshd_config ~/.ssh/config
 ```
 
-In this case, `# This script prints "Hello, World!"` is a comment that explains the script.
+## Quoting and Shell Expansion
 
-Let's move on to variables. They are symbols that stand for a value and are case-sensitive. We can define a variable `x` with value `10` in the following way:
+The shell interprets spaces, variables, wildcard characters, and quotes before
+it starts a program. Small punctuation changes can change the command.
 
 ```bash
-x=10
-echo $x
+echo "$HOME"
+echo '$HOME'
+ls *.conf
 ```
 
-With `$x`, we are accessing the value of the variable `x`.
+In most shells:
+
+- Double quotes allow variable expansion while preserving spaces.
+- Single quotes preserve text literally.
+- Wildcards such as `*` expand to matching filenames before the command runs.
+
+Use `printf '%q\n'` or `set -x` in a disposable shell when you are learning how
+an argument is interpreted:
+
+```bash
+printf '%q\n' "$HOME"
+```
+
+## Safe Copying Habits
+
+Before running an example command from any book, website, ticket, or chat:
+
+1. Identify whether it reads state, changes state, or deletes data.
+2. Replace placeholders with values from your own system.
+3. Remove prompts, line numbers, and explanatory punctuation.
+4. Prefer a read-only inspection command first.
+5. Save the exact command and output if the result matters.
+
+These commands are generally read-only:
+
+```bash
+uname -a
+cat /etc/os-release
+systemctl status ssh
+ip addr show
+df -h
+```
+
+These commands can change or remove system state and deserve extra review:
+
+```bash
+sudo systemctl restart ssh
+sudo apt upgrade
+sudo rm -rf /path/to/directory
+sudo usermod -aG sudo username
+```
+
+!!! warning "Do not paste destructive examples blindly"
+    Commands that remove files, repartition disks, change firewall rules,
+    restart network services, or edit authentication settings can lock you out
+    or destroy data. Practice those commands only in a disposable lab unless the
+    lesson gives a specific production-safe procedure.
+
+## Hands-on Practice
+
+Use a lab VM, container, or shell where mistakes are recoverable.
+
+1. Run a command with a regular prompt:
+
+   ```bash
+   whoami
+   ```
+
+2. Compare literal and expanded quoting:
+
+   ```bash
+   echo "$HOME"
+   echo '$HOME'
+   ```
+
+3. Inspect a documentation-style placeholder and rewrite it with your own
+   values:
+
+   ```bash
+   ssh username@hostname
+   ```
+
+4. Open one manual page and identify an optional argument:
+
+   ```bash
+   man ls
+   ```
+
+5. Write a short lab note with three columns: command, what was literal, and
+   what had to be replaced.
 
-Understanding these typographical conventions and notations are the very first step to deciphering Linux scripts. In the following chapters, we'll dive deeper into understanding and using more complex notations and conventions for manipulating data and automating tasks with scripts.
+## Check Your Understanding
 
-Remember, the Linux command line is a text interface, so paying attention to these conventions aids in understanding the intricacies of any Linux system. 🧠⌨️🐧
+- Why should you omit `$` or `#` when copying a command from an example?
+- What is the difference between `"$HOME"` and `'$HOME'`?
+- In `systemctl status [UNIT...]`, what does `[UNIT...]` mean?
+- What clues tell you that a command may change system state?
+- How would you document a command example so another operator can reproduce it?