fixed main documentation

1 files changed, 39 insertions, 33 deletions

diff --git a/miniany/cc.wg b/miniany/cc.wg
index e686dd4..b546c7c 100644
--- a/miniany/cc.wg
+++ b/miniany/cc.wg
@@ -28,17 +28,17 @@ WordGrinder dumpfile v3: this is a text file; diff me!
 .clipboard.cw: 1
 .clipboard.margin: 0
 .clipboard.viewmode: 1
-.clipboard.wordcount: 6
-.documents.1.co: 9
-.documents.1.cp: 134
-.documents.1.cw: 10
+.clipboard.wordcount: 3
+.documents.1.co: 6
+.documents.1.cp: 244
+.documents.1.cw: 2
 .documents.1.margin: 0
 .documents.1.name: "main"
 .documents.1.sticky_selection: false
 .documents.1.viewmode: 1
-.documents.1.wordcount: 3073
+.documents.1.wordcount: 3192
 .fileformat: 8
-.findtext: "syscal,"
+.findtext: "geneate"
 .menu.accelerators.^@: "ZM"
 .menu.accelerators.^B: "SB"
 .menu.accelerators.BACKSPACE: "ZDPC"
@@ -146,7 +146,7 @@ WordGrinder dumpfile v3: this is a text file; diff me!
 .statusbar: true
 .current: 1
 #clipboard
-P TODO: add rest of REQUIREMENTS here!
+LB c.c in swieros
 .
 #1
 H1 CC - a self-hosting, bootstrappable, minimal C compiler
@@ -210,8 +210,8 @@ LB costs to implement it in the language: code complexity and size must be kept
 LB required features from the C runtime: for instance support of the whole Unicde characters
 LB required features from the operating system: for instance the requirement for a POSIX layer
 LB ugliness of the resulting code: it doesn't make sense to omit features which are somewhat hard to implement but can render readability of the code much better: best examples are the switch/case vs. if/else and the funny array indexing vs. structures in C4.
-P So we collect some ideas here about features we add or do not add and why. We also collect here what their implications are, when we are implementing them.
-P We also have to be careful what C4 can do for us and either add it there (but only if small enough) in order no to loose this test case.
+P So we collect some ideas here about features we add or do not add and why. We also collect here the implications when we are implementing them.
+P We also have to be careful what C4 can do for us and either add it there (but only if small enough) in order not to loose this test case.
 H3 Preprocessor for modularisation
 P Implementation status: no
 P Reasoning:
@@ -222,6 +222,7 @@ LB have a cat *.c concatenating all the source code
 P Counter arguments:
 LB we could have sort of a special tape filesystem with a directory at the beginning and offset to allow the preprocessor to find the files for the early destination OS
 LB there is no reason not to use the preprocessor on the host
+LB We can end up in nasty hen-and-egg problems with functions needing each other for different falvours of implementation (e. g. atoi in hosted and freestading), so we might end up duplicating source code.
 H3 Preprocessor for conditional compilation
 P Implementation status: no
 P Reasoning:
@@ -257,8 +258,8 @@ LB we could implement an early dump format for symbols (function signatures main
 P Some general notes:
 P GNU inline asm statement has become the de-facto standard (which is too complicated IMHO): I would require sort of a .byte 0xXX instruction only, for readablility maybe simple fasm-like syntax. We must be careful that our invention of an inline assembler can be mapped somehow to the GNU inline asm version, so that we can use that one on the host with gcc/clang/tcc/pcc..
 P c.c in swieros (the c4 successor) has asm(NOP), this is something we could implement easily. u.h contains an enum with opcodes (most likely doable or an easy architecture like the one in swieros, I doubt this works for Intel opcodes, but we should check if it works for our simplified Intel opcode subset).
-P There should though be only one single point of information for opcodes per architecture, so asm gets sort of an inline string generator for the assembly output. Or we share a common C-file with enums for the opcodes and cat it to both the assembler and the compiler during the build (should not result in increaed code size, as those are enums).
-P The asm(x) or asm(x,y) constructs can be mapped on the host compilers to asm __volatile__ .byte ugliness. In cc and c4 we can take the swieros approach. This should give us nice lowlevel inline assembly in a really simplified way (basically embedding bytes).
+P There should though be only one single point of information for opcodes per architecture, so asm gets sort of an inline string generator for the assembly output. Or we share a common C-file with enums for the opcodes and cat it to both the assembler and the compiler during the build (should not result in increaed code size, as those are enums).
+P The asm(x) or asm(x,y) constructs can be mapped on the host compilers to asm __volatile__ .byte ugliness. In cc and c4 we can take the swieros approach. This should give us nice lowlevel inline assembly in a really simplified way (basically embedding bytes).
 P Not having inline assembly means you need compilation units written and linked to the program in assembly, which - well - adds a linker and calling conventions, which might be too early in bootstrapping.
 H3 Object formats and linkers
 P Implementation status: no
@@ -267,7 +268,7 @@ LB requires file systems and linker formats like ELF
 P Alternative:
 LB make compilation units from a bunch of source code, this results in bigger binaries, as we cannot share too much. This might be acceptable for early bootstrapping. Later on it would be nice to add a linker as an optional addon (which can be used outside of bootstrapping).
 H3 Forward declarations of function prototypes
-P Implementation status: yes (TODO)
+P Implementation status: yes
 P Reasoning:
 LB Recursive descent parsing requires forward function declarations.
 P Caveats:
@@ -283,51 +284,54 @@ LB only used for (s)printfs string manipulation and output functions
 LB C4 doesn't implement variable arguments for defining functions, so we cannot bootstrap a freestanding version
 P Requirements
 LB on the hosted Linux envorinment we need syscalls to syscall, int 0x80, etc.
-LB we need inline assembly to create to syscalls
+LB we need inline assembly to create the syscalls
 P Alternative:
 LB create simple functions like putchar, putint, putstring (one per basic type) and some helpers like putnl
 LB use stlcat and stlcpy should be enought to compose label names
 LB instead of a generic syscall(..) we can easily work around this by having syscall1, syscall2, syscall3, ... with a fixed number of parameters
 P Counter arguments:
-LB we deviate from the C standard, printf just belongs to C
-LB printf is actually not hard to implement in a type-unsafe-way
-LB syscalls are variable arguments
+LB we deviate from the C standard, printf just belongs to C
+LB printf is actually not hard to implement in a type-unsafe-way
+LB syscalls have variable arguments
 H3 FILE* and stderr
 P Implementation status: no
 P Reasoning:
 LB requires FILE * structures, requires various write channels from the operating system
-LB we can write error messages into the output stream as comment ; ERROR in line 32, pos 2: generic error (TODO)
+LB we can write error messages into the output stream as comments like ; ERROR in line 32, pos 2: generic error (TODO)
 P Counter arguments:
 LB unbuffered FILE * is simple to implement
 LB almost all operating systems have the notion of stdout and stderr, we can set them to the same channel if an OS doesn't have them.
 H3 Typedefs
 P Implementation status: no
 P Reasoning:
-LB typedefs are syntactic sugar for typedef struct T as T, not strictly necessary and they don't make our code look too ugly.
+LB typedefs are syntactic sugar for typedef struct T as T, not strictly necessary and they don't make our code look too ugly.
 P Counter arguments:
 LB portability without preprocessor could make use of typedef ulong64 unsigned long int and similar constructs
 H3 For-loops
 P Implementation status: no
 P Reasoning:
-LB unless we start optimizing (SIMD) there is no real benefit, for a generic 'for', a strict for i=0 to N, i++ is easier to optimize, when you have a grammatical construct to help recognizing it.
+LB unless we start optimizing (SIMD) there is no real benefit for a generic 'for', a strict for i=0 to N, i++ is easier to optimize, when you have a grammatical construct to help recognizing it.
 LB the C for loop has a funny ending semicolon issue and you can add arbitraty code blocks into the three parts of the for, this is way too generic for a minimalistic language
 P Counter arguments:
-LB for loops are not hard to implement
+LB for-loops are not hard to implement
 H3 Passing arguments to main
 P Implementation status: yes
 P Reasoning:
 LB this is just passing an int (argc) and a char** (argv) from _start to main. This is also a convention shared with the operating system when it calls our process. Without that we would have a hard time to parametrize the calls to our process both on the host and in the target OS.
 P Counter argument:
 LB Do really everything over the input stream, but this would feel a little bit too mainframe-ish.
-H3 bool
+H3 Boolean Type
 P Implementation status: no
 P Reasoning:
-LB C89 has no boolean
+LB C89 has no bool type
 LB useful, but not strigtly necessary, we can live with int holding a boolean value
-H3 Union
+P Counter arguments:
+LB boolean and integer values and variables form a nice little type system for expressions so introducing booleans might have some educational value.
+H3 Union
 P Implementation status: no
 P Reasoning:
 LB in the compiler there is little benefit of compressing parts of e. g. ASTs into unions
+LB unions allow accessing the same memory via different means, this can also be achieved with code accessing the memory differentlyand doing some byte/word conversions for instance.
 P Counter arguments:
 LB for bootstrapping the operating system we might need unions (as well as packing and alignment)
 H3 Dangling else
@@ -341,7 +345,7 @@ LB Not really necessary as we could get away with if( a != null ) { if( 
 H3 Return statement
 P Implemention status: yes, but..
 P Reasoning:
-LB There are good reasons not to allow return everywhere in the code, see newest Oberon revisions allowing RETURN only at the end of the function declaration. There are benefits like easier detection whether the function returns a function, easier flow analysis (image returns in complicated if-else-statements). For now we allow it everywhere, but we should try hard not to use it in the middle of code blocks.
+LB There are good reasons for not allowing return everywhere in the code, see newest Oberon revisions allowing RETURN only at the end of the function declaration. There are benefits like easier detection whether the function returns a value, easier flow analysis (imagine returns in complicated if-else-statements). For now we allow it everywhere, but we should try hard not to use it in the middle of code blocks.
 LB There is an argument from the code correctness point of view as return in the middle of code makes the code hard to reason about (similar to too many if-else-statements)
 LB Allowing return only at the end of a function and nowhere else makes tail-recursion easy.
 LB Error handling is really hard when return appears everywhere in the body, it's much easier to check whether there is a return at the end and whether the returned type matches the prototype of the function,
@@ -350,23 +354,23 @@ P Implementation status: yes
 P Reasoning:
 LB Compared to a stack machine even the simplest register allocation algorithm produces much better code
 P Counter arguments:
-LB Stack machine with the top of stack in EAX is also quite a simple solution.
+LB Stack machine with the top of stack in EAX is also quite a simple and efficient solution (see Write Your Own Compiler, Holm).
 H3 Abstract Syntax Trees
 P Implementation status: yes
 P Reasoning:
 LB Delaying code generation is essential when doing an assignment (rvalue must be evaluated before lvalue), in const folding (do no generate code as you don't know the expression is a constant but instead just compute the current value of the constant expression).
 LB Separate semantic operation array index evaluation from definition of the size of an array for instance with the '[' character (we do not want to react on the scanner symbol directly).
-LB When evaluating a boolean expression we don't know yet it's context (can be in a if/while condition, in which case we would geneate a conditional jump or whether in an assignment where we would store the value to the boolean variable).
+LB When evaluating a boolean expression we don't know yet its context (can be in a if/while condition, in which case we would generate a conditional jump or it can be in an an assignment, in which case we would store the value into a boolean variable).
 P Caveats:
-LB Try to keep the scope of an AST as small as possible and as big as necessary (the output of the parser should not be the complete source code). Minimal is an expression and some context, maybe maximal is the scope of a function.
+LB Try to keep the scope of an AST as small as possible and as big as necessary (the output of the parser should not be the complete source code). The mininum we need is an expression and some context, the maximum maybe is the scope of a function.
 P Counter arguments:
 LB Readable AST code needs some trees and pointers to structs, but we want those anyway for better readable code (C4 for instance is not that readable in it's original array indexing version).
 H3 Builtin functions
 P Implementation status: yes
 P Reasoning:
-LB Adding putint/getchar style of functions as elements of the language is tempting, as it allows early debugging and testing (as in PASCAL). The fundemental conflict here is betweet Bootstrapping is better with stdout and stdin in the language (no function calls, no linker, etc. needed). But later on we want those functions be part of a language library and not of the langyage itself.
+LB Adding putint/getchar style of functions as elements of the language is tempting, as it allows early debugging and testing (as in PASCAL). The fundemental conflict here is that bootstrapping is better with stdout and stdin in the language (no function calls, no linker, etc. needed). But later on we want those functions be part of a language library and not of the language itself.
 P Caveats:
-LB Avoid code duplication (inline assembly in the compiler for the keyword implementation and with intline assembly in the language library). (TODO)
+LB Avoid code duplication (inline assembly in the compiler for the keyword implementation and with inline assembly in the language library). (TODO)
 H2 References
 P Compiler construction in general:
 LB "Compiler Construction"", Niklaus Wirth
@@ -381,12 +385,14 @@ LB https://github.com/rswier/c4/blob/switch-and-structs/c4.c, c4 adaptions to p
 LB https://github.com/EarlGray/c4: a X86 JIT version of c4
 LB https://github.com/jserv/amacc: based on C4, JIT or native code, for ARM, quite well documented, also very nice list of compiler resources on Github page
 P Other minimal compilers and systems:
-LB http://selfie.cs.uni-salzburg.at/: C* self-hosting C compiler (also emulator, hypervisor) for RISCV, inspiration for what makes up a minimal C language
-LB http://www.iro.umontreal.ca/~felipe/IFT2030-Automne2002/Complements/tinyc.c, Marc Feeley, really easy and much more readable, meant as educational compiler
-LB https://github.com/rswier/swieros.git: c.c in swieros, Robert Swierczek
+LB http://selfie.cs.uni-salzburg.at/: Christoph Kirsch, C* self-hosting C compiler (also emulator, hypervisor) for RISCV, inspiration for what makes up a minimal C language
+LB http://www.iro.umontreal.ca/~felipe/IFT2030-Automne2002/Complements/tinyc.c, Marc Feeley, really easy and much more readable, meant as educational compiler
+LB https://github.com/rswier/swieros.git: Robert Swierczek, c.c in swieros
+LB https://github.com/ras52/boostrap: Richard Smith, bootstrapping experiment
+LB http://t3x.org/t3x: Nils M Holm, the T3X programming language, especially the bootstrapping version T3X9
 P Assembly:
 LB https://github.com/felipensp/assembly/blob/master/x86/itoa.s, for putint (early debugging keyword)
-LB https://baptiste-wicht.com/posts/2011/11/print-strings-integers-intel-assembly.htm (earldy debugging keyword)
+LB https://baptiste-wicht.com/posts/2011/11/print-strings-integers-intel-assembly.htm (early debugging keyword)
 P Documentation:
 LB http://cowlark.com/wordgrinder/index.html: the fabulous editor which just does what it should do
 LB https://github.com/mity/md4c: markdown to HTML in C