WIP

docs/User-Manual.md

@@ -1,14 +1,14 @@
-# User Manual for the Cyclone Scheme->C Compiler
+# User Manual for the Cyclone Scheme-to-C Compiler
 
 - [Introduction](#introduction)
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Usage](#usage)
-  - Compiling Scheme files / libraries
+  - [Compiling Scheme Programs](#compiling-scheme-programs)
-    include requirements on input files, generated files, etc
+  - [Compiling Scheme Libraries](#compiling-scheme-libraries)
-  - Command line options
+  - [Command Line Options](#command-line-options)
-    - especially include debug ones, such as -t (and what about -d?)
+  - [Generated Files](#generated-files)
-  - Interpreter
+  - [Interpreter](#interpreter)
 - Language Details
   - explain how programs are setup
   - outline scheme language based on r7rs, link to it.
@@ -51,6 +51,49 @@ TODO: installation procedure for development????
 
 # Usage
 
+## Compiling Scheme Programs
+
+A Scheme program may be compiled using the `cyclone` command:
+
+    $ cyclone  examples/fac.scm
+    $ examples/fac
+    3628800
+
+## Compiling Scheme Libraries
+
+Scheme code can be organized into libraries that are compiled separately from programs. Cyclone intends a library to represent a single C module (or file) when compiled.
+
+Each library should be placed into a `.sld` file that corresponds to the library name. For example, the library `(scheme cyclone util)` would be defined in the `.sld` file as:
+
+    (define-library (scheme cyclone util)
+      ... )
+
+And should be located in the file `scheme/cyclone/util.sld`.
+
+Cyclone will not automatically generate libraries when compiling a program. Each library will need to be built separately prior to building the program.
+
+## Command Line Options
+
+`cyclone` has the following command line options:
+
+Option | Notes
+`-t`            | Show intermediate trace output in generated C files
+`-d`            | Only generate intermediate C files, do not compile them
+`-h, --help`    | Display usage information
+`-v`            | Display version information
+
+## Generated Files
+
+The following files are generated during the Cyclone compilation process:
+
+File Extension | Notes
+`.meta` | These text files contain the expanded version of any macros exported by a Scheme library, and allow other modules to easily use those macros during compilation. This file is not generated when compiling a program.
+`.c` | C code file generated by Cyclone.
+`.o` | Object file generated by the C compiler from the corresponding `.c` file.
+(None) | Final executable file generated by the C compiler when compiling a program.
+
+## Interpreter
+
 # Licensing
 Cyclone is available under the [MIT license](http://www.opensource.org/licenses/mit-license.php).