From b53bb63c3c7d22d6a6916e7f5a0a329d3df5ddf7 Mon Sep 17 00:00:00 2001 From: pos Date: Mon, 28 Sep 2026 11:02:49 +0200 Subject: [PATCH 1/4] M0: establish EduNumbers course overview --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8fee95c..0f49713 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,56 @@ # EduNumbers -EduNumbers + +**Learn how computers represent numbers, one bit at a time.** + +EduNumbers is a bilingual (Norwegian/English) course about number systems and numeric representation relevant to computing. It starts from first principles and develops toward practical use in programming, assembly language, digital electronics, debugging, file formats and networking. + +## M0 goals + +- One canonical Markdown source tree per language. +- Norwegian is the primary language; English is a first-class parallel edition. +- Build the course as HTML, EPUB, Kindle-compatible EPUB/AZW3 where available, and PDF. +- Establish a practical curriculum covering binary, hexadecimal, octal, conversion, integer representation, arithmetic, bit operations, endianness, fixed/floating point and related computing representations. +- Keep all examples reproducible with open tools. + +## Course layout + +- `course/no/` — Norwegian course sources +- `course/en/` — English course sources +- `exercises/` — exercises +- `solutions/` — worked solutions +- `examples/` — small runnable examples +- `book/` — publication metadata and CSS +- `scripts/` — build/validation helpers +- `site/` — static site assets + +## Build + +Requirements: GNU Make, Pandoc, Python 3. Optional format validators/converters are detected automatically. + +```sh +make all +``` + +Individual targets: + +```sh +make html +make epub +make pdf +make kindle +make check +``` + +Artifacts are written below `build/`. + +## Languages + +Norwegian is the canonical teaching language for M0. English follows the same chapter structure and learning objectives. + +## License + +Course text and documentation: Creative Commons Attribution 4.0 International (CC BY 4.0). + +Example software: MIT License unless otherwise stated. + +See `LICENSE`, `LICENSES/CC-BY-4.0.txt` and `LICENSES/MIT.txt`. From aab7e624c35391bde3ff4a0a1258ffbb17c7ee9d Mon Sep 17 00:00:00 2001 From: pos Date: Mon, 28 Sep 2026 11:04:23 +0200 Subject: [PATCH 2/4] M0: add bilingual course foundation and publishing pipeline --- .github/workflows/build.yml | 29 ++++++++++++++++++++ .gitignore | 4 +++ COURSE.md | 39 ++++++++++++++++++++++++++ LICENSE | 8 ++++++ LICENSES/MIT.txt | 9 ++++++ Makefile | 38 ++++++++++++++++++++++++++ book/epub.css | 5 ++++ book/metadata-en.yaml | 7 +++++ book/metadata-no.yaml | 7 +++++ course/en/00-introduction.md | 9 ++++++ course/en/01-positional-systems.md | 11 ++++++++ course/no/00-introduksjon.md | 32 ++++++++++++++++++++++ course/no/01-posisjonssystemer.md | 44 ++++++++++++++++++++++++++++++ course/no/02-binaer.md | 17 ++++++++++++ course/no/03-heksadesimal.md | 26 ++++++++++++++++++ exercises/no/01-grunnlag.md | 10 +++++++ scripts/check_sources.py | 20 ++++++++++++++ solutions/no/01-grunnlag.md | 10 +++++++ 18 files changed, 325 insertions(+) create mode 100644 .github/workflows/build.yml create mode 100644 .gitignore create mode 100644 COURSE.md create mode 100644 LICENSE create mode 100644 LICENSES/MIT.txt create mode 100644 Makefile create mode 100644 book/epub.css create mode 100644 book/metadata-en.yaml create mode 100644 book/metadata-no.yaml create mode 100644 course/en/00-introduction.md create mode 100644 course/en/01-positional-systems.md create mode 100644 course/no/00-introduksjon.md create mode 100644 course/no/01-posisjonssystemer.md create mode 100644 course/no/02-binaer.md create mode 100644 course/no/03-heksadesimal.md create mode 100644 exercises/no/01-grunnlag.md create mode 100755 scripts/check_sources.py create mode 100644 solutions/no/01-grunnlag.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..c1c8305 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,29 @@ +name: Build course + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install publishing toolchain + run: | + sudo apt-get update + sudo apt-get install -y pandoc texlive-xetex calibre + - name: Check sources + run: make check + - name: Build HTML, EPUB, PDF and Kindle + run: make all + - name: Upload course artifacts + uses: actions/upload-artifact@v4 + with: + name: edunumbers-course + path: build/ diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1d53624 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +build/ +.DS_Store +__pycache__/ +*.pyc diff --git a/COURSE.md b/COURSE.md new file mode 100644 index 0000000..3bc9175 --- /dev/null +++ b/COURSE.md @@ -0,0 +1,39 @@ +# EduNumbers curriculum + +EduNumbers teaches number systems as they are encountered in real computers, from first principles to practical debugging and systems work. + +## Learning path + +1. Numbers and representations +2. Decimal positional notation +3. Binary +4. Hexadecimal +5. Octal +6. Converting between bases +7. Powers of two and storage units +8. Unsigned integers +9. Signed integers and two's complement +10. Binary arithmetic and CPU flags +11. Bitwise operations +12. Bit masks and bit fields +13. Memory addresses and dumps +14. Endianness +15. BCD +16. Fixed-point numbers +17. Floating point and IEEE 754 +18. Gray code, biased representations and encoded values +19. Number notation in assembly language +20. Number notation in C and Python +21. Digital electronics and hardware registers +22. Networks and file formats +23. Debugging and reverse engineering +24. Historical and unusual bases +25. Final practical byte-buffer project + +## Teaching pattern + +Each chapter should use the cycle **PREDICT → STEP → OBSERVE → EXPLAIN**, followed by short exercises and a practical computing example. + +## M0 scope + +M0 establishes the publication pipeline, bilingual source layout, curriculum, introductory chapters, exercises and automated checks. Later milestones deepen every topic and add interactive explorers. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e4cff24 --- /dev/null +++ b/LICENSE @@ -0,0 +1,8 @@ +# Licensing + +Unless a file states otherwise: + +- Course text, documentation, exercises, solutions and publication assets are licensed under the Creative Commons Attribution 4.0 International license (CC BY 4.0). +- Software and code examples are licensed under the MIT License. + +See https://creativecommons.org/licenses/by/4.0/ and `LICENSES/MIT.txt`. diff --git a/LICENSES/MIT.txt b/LICENSES/MIT.txt new file mode 100644 index 0000000..dc691b9 --- /dev/null +++ b/LICENSES/MIT.txt @@ -0,0 +1,9 @@ +MIT License + +Copyright (c) 2026 Ploos AS + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..87a4d77 --- /dev/null +++ b/Makefile @@ -0,0 +1,38 @@ +PANDOC ?= pandoc +PYTHON ?= python3 +NO_SRC := $(sort $(wildcard course/no/*.md)) +EN_SRC := $(sort $(wildcard course/en/*.md)) + +.PHONY: all html epub pdf kindle check clean +all: check html epub pdf kindle + +build: + mkdir -p build/html/no build/html/en build/epub build/pdf build/kindle + +check: + $(PYTHON) scripts/check_sources.py + +html: build + $(PANDOC) --standalone --toc --metadata-file=book/metadata-no.yaml $(NO_SRC) -o build/html/no/index.html + $(PANDOC) --standalone --toc --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/html/en/index.html + +epub: build + $(PANDOC) --toc --css=book/epub.css --metadata-file=book/metadata-no.yaml $(NO_SRC) -o build/epub/edunumbers-no.epub + $(PANDOC) --toc --css=book/epub.css --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/epub/edunumbers-en.epub + +pdf: build + $(PANDOC) --toc --metadata-file=book/metadata-no.yaml $(NO_SRC) -o build/pdf/edunumbers-no.pdf + $(PANDOC) --toc --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/pdf/edunumbers-en.pdf + +kindle: epub + @if command -v ebook-convert >/dev/null 2>&1; then \ + ebook-convert build/epub/edunumbers-no.epub build/kindle/edunumbers-no.azw3; \ + ebook-convert build/epub/edunumbers-en.epub build/kindle/edunumbers-en.azw3; \ + else \ + cp build/epub/edunumbers-no.epub build/kindle/edunumbers-no-kindle.epub; \ + cp build/epub/edunumbers-en.epub build/kindle/edunumbers-en-kindle.epub; \ + echo 'Calibre not installed; Kindle-compatible EPUB retained.'; \ + fi + +clean: + rm -rf build diff --git a/book/epub.css b/book/epub.css new file mode 100644 index 0000000..f039be0 --- /dev/null +++ b/book/epub.css @@ -0,0 +1,5 @@ +body { font-family: serif; line-height: 1.45; } +code, pre { font-family: monospace; } +table { border-collapse: collapse; margin: 1em 0; } +th, td { border: 1px solid #888; padding: .35em .6em; } +h1, h2, h3 { page-break-after: avoid; } diff --git a/book/metadata-en.yaml b/book/metadata-en.yaml new file mode 100644 index 0000000..7825942 --- /dev/null +++ b/book/metadata-en.yaml @@ -0,0 +1,7 @@ +--- +title: "EduNumbers – Number Systems for Computing" +author: "Ploos AS" +lang: en +rights: "CC BY 4.0" +subtitle: "From bits and hex to integers, endianness and floating point" +... \ No newline at end of file diff --git a/book/metadata-no.yaml b/book/metadata-no.yaml new file mode 100644 index 0000000..87bbc8a --- /dev/null +++ b/book/metadata-no.yaml @@ -0,0 +1,7 @@ +--- +title: "EduNumbers – Tallsystemer for databehandling" +author: "Ploos AS" +lang: nb-NO +rights: "CC BY 4.0" +subtitle: "Fra bits og hex til heltall, endianness og flyttall" +... \ No newline at end of file diff --git a/course/en/00-introduction.md b/course/en/00-introduction.md new file mode 100644 index 0000000..8336322 --- /dev/null +++ b/course/en/00-introduction.md @@ -0,0 +1,9 @@ +# Introduction + +Computers ultimately store bit patterns. A value only gains meaning when those bits are interpreted according to some representation. + +This course teaches number systems from that perspective: not only how to convert values on paper, but how binary, hexadecimal, signed integers, masks, endianness and numeric formats appear in real software and hardware. + +## Learning outcomes + +By the end of the course you should be able to read and convert common bases, reason about integer widths and two's complement, use bitwise operations, inspect memory and hex dumps, explain byte order, and recognize common numeric representations in programming, assembly language, hardware registers, protocols and file formats. \ No newline at end of file diff --git a/course/en/01-positional-systems.md b/course/en/01-positional-systems.md new file mode 100644 index 0000000..b831495 --- /dev/null +++ b/course/en/01-positional-systems.md @@ -0,0 +1,11 @@ +# Positional systems and bases + +In a positional numeral system, a digit's value depends on both the digit and its position. + +Decimal `347` means `3 × 10² + 4 × 10¹ + 7 × 10⁰`. + +Binary `1011₂` means `1 × 2³ + 0 × 2² + 1 × 2¹ + 1 × 2⁰ = 11`. + +Common computing bases are binary (2), octal (8), decimal (10) and hexadecimal (16). + +A central lesson is that a sequence such as `10` does not by itself determine a value: `10₂` is two, `10₈` is eight, and `10₁₆` is sixteen. \ No newline at end of file diff --git a/course/no/00-introduksjon.md b/course/no/00-introduksjon.md new file mode 100644 index 0000000..40e7747 --- /dev/null +++ b/course/no/00-introduksjon.md @@ -0,0 +1,32 @@ +# Introduksjon + +Datamaskiner lagrer ikke «123», «A» eller «-7» på samme måte som mennesker skriver dem. De lagrer mønstre av bits. Betydningen kommer fra hvordan vi velger å tolke disse mønstrene. + +I dette kurset lærer du både å regne med ulike tallsystemer og å kjenne dem igjen i faktisk programvare og maskinvare. + +## Læringsmål + +Etter kurset skal du blant annet kunne: + +- lese og skrive binære, desimale, oktale og heksadesimale tall; +- konvertere mellom baser; +- forstå unsigned og signed heltall; +- forklare two's complement, overflow og wraparound; +- bruke bitvise operasjoner og bitmasker; +- lese adresser og enkle hex-dumps; +- forklare little endian og big endian; +- forstå grunnideen bak fixed point, BCD og IEEE 754; +- kjenne igjen tallrepresentasjoner i assembler, C, Python, registre, protokoller og filformater. + +## Første idé: tall er ikke skrivemåten + +Tallet tolv kan skrives på flere måter: + +- desimalt: `12` +- binært: `1100₂` +- heksadesimalt: `C₁₆` +- oktalt: `14₈` + +Verdien er den samme. Representasjonen er forskjellig. + +Dette skillet er grunnlaget for resten av kurset. \ No newline at end of file diff --git a/course/no/01-posisjonssystemer.md b/course/no/01-posisjonssystemer.md new file mode 100644 index 0000000..865079b --- /dev/null +++ b/course/no/01-posisjonssystemer.md @@ -0,0 +1,44 @@ +# Posisjonssystemer og baser + +I et posisjonssystem bestemmes verdien til et siffer både av selve sifferet og plasseringen. + +Det desimale tallet `347` betyr: + +`3 × 10² + 4 × 10¹ + 7 × 10⁰`. + +Det binære tallet `1011₂` betyr: + +`1 × 2³ + 0 × 2² + 1 × 2¹ + 1 × 2⁰ = 11`. + +## Base + +Basen forteller hvor mange forskjellige sifre systemet bruker før en ny posisjon må tas i bruk. + +| Base | Navn | Sifre | +|---:|---|---| +| 2 | binær | 0–1 | +| 8 | oktal | 0–7 | +| 10 | desimal | 0–9 | +| 16 | heksadesimal | 0–9, A–F | + +I programmering brukes ofte prefikser som `0b1011` for binært og `0x2A` for heksadesimalt. Syntaksen varierer mellom språk og assemblere. + +## PREDICT + +Hva betyr `10` i base 2, base 8 og base 16? + +## STEP + +I enhver base `b` betyr skrivemåten `10` verdien `1 × b¹ + 0 × b⁰`. + +## OBSERVE + +Dermed er: + +- `10₂ = 2₁₀` +- `10₈ = 8₁₀` +- `10₁₆ = 16₁₀` + +## EXPLAIN + +Sifferrekkefølgen alene er ikke nok. Du må også vite hvilken base som brukes. \ No newline at end of file diff --git a/course/no/02-binaer.md b/course/no/02-binaer.md new file mode 100644 index 0000000..e6d7fc2 --- /dev/null +++ b/course/no/02-binaer.md @@ -0,0 +1,17 @@ +# Binært: base 2 + +Binært bruker bare sifrene `0` og `1`. Hver posisjon representerer en potens av to. + +| Bitposisjon | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +|---|---:|---:|---:|---:|---:|---:|---:|---:| +| Verdi | 128 | 64 | 32 | 16 | 8 | 4 | 2 | 1 | + +Eksempel: `10110110₂` har verdien `128 + 32 + 16 + 4 + 2 = 182`. + +## Bits, nibble og byte + +En **bit** kan ha verdien 0 eller 1. Fire bits kalles ofte en **nibble**. Åtte bits utgjør normalt en **byte**. + +Med `n` bits finnes `2ⁿ` forskjellige bitmønstre. Åtte bits gir derfor 256 mønstre, fra `00000000` til `11111111`. + +Hvorfor det siste mønsteret tolkes som 255, -1 eller noe helt annet, avhenger av representasjonen. Det kommer vi tilbake til. \ No newline at end of file diff --git a/course/no/03-heksadesimal.md b/course/no/03-heksadesimal.md new file mode 100644 index 0000000..5faddaf --- /dev/null +++ b/course/no/03-heksadesimal.md @@ -0,0 +1,26 @@ +# Heksadesimalt: base 16 + +Heksadesimalt passer svært godt til binære datamaskiner fordi ett hex-siffer tilsvarer nøyaktig fire bits. + +| Hex | Binær | Desimal | +|---|---|---:| +| 0 | 0000 | 0 | +| 1 | 0001 | 1 | +| 2 | 0010 | 2 | +| 3 | 0011 | 3 | +| 4 | 0100 | 4 | +| 5 | 0101 | 5 | +| 6 | 0110 | 6 | +| 7 | 0111 | 7 | +| 8 | 1000 | 8 | +| 9 | 1001 | 9 | +| A | 1010 | 10 | +| B | 1011 | 11 | +| C | 1100 | 12 | +| D | 1101 | 13 | +| E | 1110 | 14 | +| F | 1111 | 15 | + +Derfor blir `1101 0010₂` direkte til `D2₁₆`. + +Denne egenskapen er grunnen til at hex brukes så mye i adresser, maskinkode, debugger-visninger, registerverdier, farger, protokoller og filformater. \ No newline at end of file diff --git a/exercises/no/01-grunnlag.md b/exercises/no/01-grunnlag.md new file mode 100644 index 0000000..8db1162 --- /dev/null +++ b/exercises/no/01-grunnlag.md @@ -0,0 +1,10 @@ +# Øvelser: grunnlag + +1. Skriv `13₁₀` i binær form. +2. Hva er `101101₂` i desimal form? +3. Konverter `1111 0010₂` direkte til heksadesimal. +4. Hva er `0x2A` i desimal? +5. Hvor mange forskjellige bitmønstre finnes med 4, 8 og 16 bits? +6. Forklar med egne ord hvorfor `10` kan representere forskjellige verdier. +7. Skriv alle potensene av to fra `2⁰` til `2¹⁶`. +8. Finn den største unsigned verdien som kan representeres med 8 bits. \ No newline at end of file diff --git a/scripts/check_sources.py b/scripts/check_sources.py new file mode 100755 index 0000000..fa17d8a --- /dev/null +++ b/scripts/check_sources.py @@ -0,0 +1,20 @@ +#!/usr/bin/env python3 +from pathlib import Path +import sys + +required = [ + Path('README.md'), Path('COURSE.md'), + Path('course/no/00-introduksjon.md'), + Path('course/en/00-introduction.md'), + Path('book/metadata-no.yaml'), Path('book/metadata-en.yaml'), +] +missing = [str(p) for p in required if not p.is_file()] +if missing: + print('Missing required M0 files:') + print('\n'.join(f'- {p}' for p in missing)) + sys.exit(1) +for p in Path('course').rglob('*.md'): + if not p.read_text(encoding='utf-8').strip(): + print(f'Empty source: {p}') + sys.exit(1) +print('M0 source checks passed') diff --git a/solutions/no/01-grunnlag.md b/solutions/no/01-grunnlag.md new file mode 100644 index 0000000..492fd02 --- /dev/null +++ b/solutions/no/01-grunnlag.md @@ -0,0 +1,10 @@ +# Løsningsforslag: grunnlag + +1. `13₁₀ = 1101₂`. +2. `101101₂ = 32 + 8 + 4 + 1 = 45₁₀`. +3. `1111 0010₂ = F2₁₆`. +4. `0x2A = 2 × 16 + 10 = 42`. +5. Med `n` bits finnes `2ⁿ` mønstre: 16, 256 og 65 536. +6. Verdien av en posisjon bestemmes av basen. `10_b = b`. +7. `1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536`. +8. `2⁸ - 1 = 255`. \ No newline at end of file From 6b933ee49bb2c70df165fd0ec82945a0534e6b12 Mon Sep 17 00:00:00 2001 From: pos Date: Mon, 28 Sep 2026 11:04:39 +0200 Subject: [PATCH 3/4] M0: add CC BY 4.0 licensing notice --- LICENSES/CC-BY-4.0.txt | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 LICENSES/CC-BY-4.0.txt diff --git a/LICENSES/CC-BY-4.0.txt b/LICENSES/CC-BY-4.0.txt new file mode 100644 index 0000000..e362581 --- /dev/null +++ b/LICENSES/CC-BY-4.0.txt @@ -0,0 +1,9 @@ +Creative Commons Attribution 4.0 International (CC BY 4.0) + +Course text, documentation, exercises, solutions and publication assets in EduNumbers are licensed under CC BY 4.0 unless a file states otherwise. + +License summary and legal code: +https://creativecommons.org/licenses/by/4.0/ +https://creativecommons.org/licenses/by/4.0/legalcode + +Copyright (c) 2026 Ploos AS From dc2f634977530a7c26c2810d3fb957b34b07817f Mon Sep 17 00:00:00 2001 From: pos Date: Mon, 28 Sep 2026 11:08:50 +0200 Subject: [PATCH 4/4] M0.1: use XeLaTeX for Unicode-safe PDF builds --- Makefile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 87a4d77..4da6d8a 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,6 @@ PANDOC ?= pandoc PYTHON ?= python3 +PDF_ENGINE ?= xelatex NO_SRC := $(sort $(wildcard course/no/*.md)) EN_SRC := $(sort $(wildcard course/en/*.md)) @@ -21,8 +22,8 @@ epub: build $(PANDOC) --toc --css=book/epub.css --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/epub/edunumbers-en.epub pdf: build - $(PANDOC) --toc --metadata-file=book/metadata-no.yaml $(NO_SRC) -o build/pdf/edunumbers-no.pdf - $(PANDOC) --toc --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/pdf/edunumbers-en.pdf + $(PANDOC) --pdf-engine=$(PDF_ENGINE) --toc --metadata-file=book/metadata-no.yaml $(NO_SRC) -o build/pdf/edunumbers-no.pdf + $(PANDOC) --pdf-engine=$(PDF_ENGINE) --toc --metadata-file=book/metadata-en.yaml $(EN_SRC) -o build/pdf/edunumbers-en.pdf kindle: epub @if command -v ebook-convert >/dev/null 2>&1; then \