Merge pull request #53 from s3k/main

doc: man pages 1,5,7 added

4 files changed, 456 insertions, 5 deletions

diff --git a/Makefile b/Makefile
index 0f88569..c83cd0c 100644
--- a/Makefile
+++ b/Makefile
@@ -41,7 +41,7 @@ OBJS = $(patsubst %.c, $(OBJ_DIR)/%.o, $(SRCS))
 # Installation paths
 PREFIX ?= /usr/local
 BINDIR = $(PREFIX)/bin
-MANDIR = $(PREFIX)/share/man/man1
+MANDIR = $(PREFIX)/share/man
 SHAREDIR = $(PREFIX)/share/zenc
 
 # Default target
@@ -62,21 +62,29 @@ $(OBJ_DIR)/%.o: %.c
 install: $(TARGET)
 	install -d $(BINDIR)
 	install -m 755 $(TARGET) $(BINDIR)/$(TARGET)
-	install -d $(MANDIR)
-	# Install man page if it exists
-	test -f man/zc.1 && install -m 644 man/zc.1 $(MANDIR)/zc.1 || true
+	
+	# Install man pages
+	install -d $(MANDIR)/man1 $(MANDIR)/man5 $(MANDIR)/man7
+	test -f man/zc.1 && install -m 644 man/zc.1 $(MANDIR)/man1/zc.1 || true
+	test -f man/zc.5 && install -m 644 man/zc.5 $(MANDIR)/man5/zc.5 || true
+	test -f man/zc.7 && install -m 644 man/zc.7 $(MANDIR)/man7/zc.7 || true
+	
 	# Install standard library
 	install -d $(SHAREDIR)
 	cp -r std $(SHAREDIR)/
 	@echo "=> Installed to $(BINDIR)/$(TARGET)"
+	@echo "=> Man pages installed to $(MANDIR)"
 	@echo "=> Standard library installed to $(SHAREDIR)/std"
 
 # Uninstall
 uninstall:
 	rm -f $(BINDIR)/$(TARGET)
-	rm -f $(MANDIR)/zc.1
+	rm -f $(MANDIR)/man1/zc.1
+	rm -f $(MANDIR)/man5/zc.5
+	rm -f $(MANDIR)/man7/zc.7
 	rm -rf $(SHAREDIR)
 	@echo "=> Uninstalled from $(BINDIR)/$(TARGET)"
+	@echo "=> Removed man pages from $(MANDIR)"
 	@echo "=> Removed $(SHAREDIR)"
 
 # Clean
diff --git a/man/zc.1 b/man/zc.1
index e69de29..57d5c5e 100644
--- a/man/zc.1
+++ b/man/zc.1
@@ -0,0 +1,108 @@
+.TH ZC 1 "2026-01-15" "Zen C 0.1.0" "User Commands"
+.SH NAME
+zc \- Zen C compiler and toolchain
+.SH SYNOPSIS
+.B zc
+.I command
+[\fIoptions\fR]
+.I file.zc
+.SH DESCRIPTION
+.B zc
+is the compiler for Zen C, a modern systems programming language that compiles to
+human-readable GNU C/C11. It provides type inference, pattern matching, generics,
+traits, async/await, and manual memory management with RAII capabilities while
+maintaining 100% C ABI compatibility.
+.SH COMMANDS
+.TP
+.B run
+Compile and execute the program immediately.
+.TP
+.B build
+Compile to an executable file (default mode).
+.TP
+.B check
+Check for syntax and semantic errors only; do not compile.
+.TP
+.B repl
+Start the interactive Read-Eval-Print Loop.
+.TP
+.B transpile
+Transpile to C code only without compiling to an executable.
+.TP
+.B lsp
+Start the Language Server Protocol daemon for editor integration.
+.SH OPTIONS
+.TP
+.BR \-o " " \fIfile\fR
+Specify output executable name.
+.TP
+.B \-\-emit\-c
+Keep the generated C file (out.c) after compilation.
+.TP
+.B \-\-freestanding
+Enable freestanding mode (no standard library).
+.TP
+.BR \-\-cc " " \fIcompiler\fR
+Select C compiler backend (gcc, clang, tcc, zig). Default: gcc
+.TP
+.BR \-O \fIlevel\fR
+Set optimization level (0-3, s, fast).
+.TP
+.B \-g
+Include debug information in the output.
+.TP
+.BR \-v ", " \-\-verbose
+Enable verbose output.
+.TP
+.BR \-q ", " \-\-quiet
+Suppress non-error output.
+.TP
+.B \-c
+Compile only; produce object file (.o) without linking.
+.SH ENVIRONMENT
+.TP
+.B ZC_ROOT
+Specifies the location of the Zen C standard library. If unset, searches in
+./std/, /usr/local/share/zenc/, and /usr/share/zenc/.
+.SH EXAMPLES
+.TP
+Compile and run a program:
+.nf
+.B zc run hello.zc
+.fi
+.TP
+Build an optimized executable:
+.nf
+.B zc build app.zc \-o myapp \-O3
+.fi
+.TP
+Transpile to C code:
+.nf
+.B zc transpile source.zc \-o output.c
+.fi
+.TP
+Use Clang as backend:
+.nf
+.B zc build app.zc \-\-cc clang
+.fi
+.SH EXIT STATUS
+Returns 0 on success, 1 on compilation error, or non-zero on execution failure (run mode).
+.SH FILES
+.TP
+.I out.c
+Temporary C file generated during compilation (removed unless \-\-emit\-c is specified).
+.TP
+.I /usr/share/zenc/
+Default standard library location.
+.TP
+.I ~/.config/zc/
+User configuration directory (future use).
+.SH SEE ALSO
+.BR zc (5),
+.BR zenc (7),
+.BR gcc (1),
+.BR clang (1)
+.SH BUGS
+Report bugs at: https://github.com/z-libs/Zen-C/issues
+.SH AUTHORS
+The Zen C development team.
diff --git a/man/zc.5 b/man/zc.5
new file mode 100644
index 0000000..d2aacd8
--- /dev/null
+++ b/man/zc.5
@@ -0,0 +1,104 @@
+.TH ZC 5 "2026-01-15" "Zen C 0.1.0" "File Formats"
+.SH NAME
+zc \- Zen C source file format and build directives
+.SH DESCRIPTION
+Zen C source files use the
+.B .zc
+extension and contain Zen C language code. Files may include special build
+directives at the top to configure compilation without requiring external
+build systems.
+.SH BUILD DIRECTIVES
+Build directives are special comments placed at the beginning of source files,
+using the format
+.BR "//> " \fIdirective\fR: " " \fIarguments\fR
+.PP
+Supported directives:
+.TP
+.BR "//> link:" " " \fI\-lfoo\fR " or " \fIpath/to/lib.a\fR
+Link against a library or object file.
+.TP
+.BR "//> lib:" " " \fIpath/to/libs\fR
+Add a library search path (\-L flag).
+.TP
+.BR "//> include:" " " \fIpath/to/headers\fR
+Add an include search path (\-I flag).
+.TP
+.BR "//> cflags:" " " \fI\-Wall \-O3\fR
+Pass arbitrary flags to the C compiler.
+.TP
+.BR "//> define:" " " \fIMACRO\fR " or " \fIKEY=VAL\fR
+Define a preprocessor macro (\-D flag).
+.TP
+.BR "//> pkg\-config:" " " \fIgtk+\-3.0\fR
+Run pkg-config and apply \-\-cflags and \-\-libs automatically.
+.TP
+.BR "//> shell:" " " \fIcommand\fR
+Execute a shell command during the build process.
+.TP
+.BR "//> get:" " " \fIhttp://url/file\fR
+Download a file if it does not exist locally.
+.TP
+.B //> immutable\-by\-default
+Make all variables immutable unless declared with
+.BR mut .
+.SH SYNTAX ELEMENTS
+.SS Comments
+.TP
+.B // comment
+Single-line comment
+.TP
+.B /* ... */
+Multi-line comment
+.SS Imports
+.TP
+.BI "import " \[dq]module\[dq]
+Import a Zen C module
+.TP
+.BI "include " <header.h>
+Include a C header file
+.SS Raw C Blocks
+.PP
+.nf
+.B raw {
+    // Raw C code injected directly
+.B }
+.fi
+.SH EXAMPLES
+.SS Basic Program with Directives
+.nf
+//> link: \-lm
+//> cflags: \-O3
+//> immutable\-by\-default
+
+import "std/io.zc"
+
+fn main() {
+    println "Hello, Zen C!";
+}
+.fi
+.SS Using pkg-config
+.nf
+//> pkg\-config: sdl2
+//> cflags: \-std=c11
+
+import <SDL2/SDL.h>
+
+fn main() {
+    SDL_Init(SDL_INIT_VIDEO);
+    // ...
+}
+.fi
+.SH FILE LOCATIONS
+.TP
+.I *.zc
+Zen C source files
+.TP
+.I std/*.zc
+Standard library modules
+.TP
+.I ./imports/
+Project-local modules
+.SH SEE ALSO
+.BR zc (1),
+.BR zenc (7),
+.BR pkg\-config (1)
diff --git a/man/zc.7 b/man/zc.7
new file mode 100644
index 0000000..62be674
--- /dev/null
+++ b/man/zc.7
@@ -0,0 +1,231 @@
+.TH ZENC 7 "2026-01-15" "Zen C 0.1.0" "Miscellaneous"
+.SH NAME
+zenc \- Zen C language conventions and overview
+.SH DESCRIPTION
+Zen C is a modern systems programming language that compiles to C11. It combines
+high-level ergonomics with zero runtime overhead. This manual describes the
+language semantics, type system, and programming conventions.
+.SH TYPE SYSTEM
+.SS Primitive Types
+.TS
+tab(|);
+l l l.
+Type|C Equivalent|Description
+_
+int, uint|int, unsigned int|Platform integer
+i8..i128|int8_t..__int128_t|Fixed-width signed
+u8..u128|uint8_t..__uint128_t|Fixed-width unsigned
+isize, usize|ptrdiff_t, size_t|Pointer-sized
+f32, f64|float, double|Floating point
+bool|bool|Boolean (true/false)
+char|char|Single character
+string|char*|Null-terminated string
+void|void|Empty type
+.TE
+.SS Aggregate Types
+.TP
+.B Arrays
+Fixed-size with value semantics:
+.BR "int[5]" ", " "[int; 5]"
+.TP
+.B Tuples
+Anonymous product types:
+.B "(int, string)"
+.TP
+.B Structs
+Named record types with fields
+.TP
+.B Enums
+Tagged unions (sum types) with data
+.TP
+.B Unions
+Untagged unions (unsafe)
+.SH MEMORY MANAGEMENT
+.SS Manual Memory
+.PP
+Zen C provides manual memory management with ergonomic helpers:
+.TP
+.B defer statement
+Execute code when scope exits
+.TP
+.B autofree modifier
+Automatically free variable on scope exit
+.TP
+.B Drop trait
+Implement custom cleanup logic (RAII pattern)
+.SS Example
+.nf
+fn process_file() {
+    var f = fopen("data.txt", "r");
+    defer fclose(f);  // Automatic cleanup
+    
+    autofree var buffer = malloc(1024);
+    // ...
+} // buffer freed, file closed automatically
+.fi
+.SH CONTROL FLOW
+.SS Pattern Matching
+.PP
+Zen C provides exhaustive pattern matching via
+.BR match :
+.PP
+.nf
+match value {
+    1 => action1(),
+    2 | 3 => action2(),
+    4..10 => action_range(),
+    _ => default_action()
+}
+.fi
+.SS Loops
+.TP
+.BI "for " "i in 0..10"
+Range-based iteration
+.TP
+.BI "for " "item in collection"
+Iterator-based loop
+.TP
+.B while condition
+Conditional loop
+.TP
+.B loop
+Infinite loop (use
+.B break
+to exit)
+.TP
+.BI "repeat " "n"
+Execute block n times
+.SS Advanced Control
+.TP
+.B guard condition else { ... }
+Early return if condition false
+.TP
+.B unless condition { ... }
+Execute if condition false
+.SH OPERATORS
+.SS Null-Safety Operators
+.TP
+.B ??
+Null coalescing:
+.B "val ?? default"
+.TP
+.B ??=
+Null assignment:
+.B "val ??= init"
+.TP
+.B ?.
+Safe navigation:
+.B "ptr?.field"
+.TP
+.B ?
+Try operator: propagate errors
+.SH GENERICS AND TRAITS
+.SS Generic Types
+.PP
+.nf
+struct Box<T> {
+    item: T;
+}
+
+fn identity<T>(val: T) -> T {
+    return val;
+}
+.fi
+.SS Traits
+.PP
+Define shared behavior:
+.PP
+.nf
+trait Drawable {
+    fn draw(self);
+}
+
+impl Drawable for Circle {
+    fn draw(self) {
+        // implementation
+    }
+}
+.fi
+.SH CONCURRENCY
+Zen C provides async/await built on pthreads:
+.PP
+.nf
+async fn fetch() -> string {
+    // Background execution
+    return "data";
+}
+
+fn main() {
+    var future = fetch();
+    var result = await future;
+}
+.fi
+.SH METAPROGRAMMING
+.SS Compile-Time Execution
+.TP
+.B comptime { ... }
+Execute code at compile time
+.TP
+.BI "embed " \[dq]file\[dq]
+Embed file as byte array
+.TP
+.BI "import plugin " \[dq]name\[dq]
+Load compiler plugin
+.SS Attributes
+.PP
+Modify compiler behavior:
+.BR @must_use ", " @inline ", " @packed ", " @deprecated
+.SH INLINE ASSEMBLY
+Zen C supports GCC-style inline assembly with simplified syntax:
+.PP
+.nf
+fn atomic_add(a: int, b: int) -> int {
+    var result: int;
+    asm {
+        "add {result}, {a}, {b}"
+        : out(result)
+        : in(a), in(b)
+        : clobber("cc")
+    }
+    return result;
+}
+.fi
+.SH COMPILER COMPATIBILITY
+.TS
+tab(|);
+l c l.
+Compiler|Support|Notes
+_
+GCC|100%|Full feature support
+Clang|100%|Full feature support
+Zig cc|100%|via zig cc wrapper
+TCC|~70%|Missing nested functions, __auto_type
+.TE
+.SH EXAMPLES
+.SS Hello World
+.nf
+fn main() {
+    println "Hello, World!";
+}
+.fi
+.SS Generic Vector
+.nf
+import "std/vec.zc"
+
+fn main() {
+    var nums = Vec<int>::new();
+    nums.push(42);
+    nums.push(100);
+    println "{nums.length()} items";
+}
+.fi
+.SH FILES
+.TP
+.I /usr/share/zenc/std/
+Standard library location
+.SH SEE ALSO
+.BR zc (1),
+.BR zc (5),
+.BR gcc (1)
+.SH STANDARDS
+Zen C targets C11 with GNU extensions. Generated code is ABI-compatible with C.