M0: establish EduNumbers course foundation

.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/

.gitignore

@@ -0,0 +1,4 @@
+build/
+.DS_Store
+__pycache__/
+*.pyc

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.

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`.

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

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.

Makefile

@@ -0,0 +1,39 @@
+PANDOC ?= pandoc
+PYTHON ?= python3
+PDF_ENGINE ?= xelatex
+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) --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 \
+		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

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`.

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; }

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"
+...

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"
+...

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.

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.

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.

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.

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.

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.

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.