Added information on source tree

doc/integration.texi

@@ -0,0 +1,220 @@
+@c  This document is part of the ease.js manual
+@c  Copyright (c) 2011 Mike Gerwitz
+@c    Permission is granted to copy, distribute and/or modify this document
+@c    under the terms of the GNU Free Documentation License, Version 1.3
+@c    or any later version published by the Free Software Foundation;
+@c    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c    Texts.  A copy of the license is included in the section entitled ``GNU
+@c    Free Documentation License''.
+
+@node Integration
+@chapter Integrating ease.js
+
+Before diving into ease.js, let's take a moment to get you set up. How ease.js
+is integrated depends on how it is being used - on the server or in the client
+(web browser). You may also wish to build ease.js yourself rather than
+downloading pre-built packages. Depending on what you are doing, you may not
+have to build ease.js at all.
+
+@menu
+* Source Tree:: Describes the project source tree
+@end menu
+
+@node Source Tree
+@section Source Tree
+Before building, you need to get a hold of the source tree. Either download an
+archive (tarball, zip, etc), or clone the Git repository. We will do the latter.
+Feel free to clone from your favorite source.
+
+@example
+  # to clone from GitHub (do one or the other, not both)
+  $ git clone git://github.com/mikegerwitz/easejs
+
+  # to clone from Gitorious (do one or the other, not both)
+  $ git clone git://gitorious.org/easejs/easejs.git
+@end example
+
+The repository will be cloned into the @file{./easejs} directory. Let's take a
+look around.
+
+@example
+  $ cd easejs
+  $ ls -d */
+  doc/  lib/  test/  tools/
+@end example
+
+The project contains four main directories:
+
+@table @file
+@item ./
+The root directory contains basic project files, such as @file{README},
+@file{Makefile} and @file{index.js}.
+
+@item doc/
+Contains documentation source files (you are currently reading part of it - the
+manual).
+
+@item lib/
+Contains the actual source code for the various modules.
+
+@item test/
+Contains unit tests.
+
+@item tools/
+Various tools used during build process.
+@end table
+
+Let's take a look at each directory in more detail.
+
+@menu
+* Root Directory::   Contains basic project files
+* Doc Directory::    Contains source documentation files (manual)
+* Lib Directory::    Contains project source files (modules)
+* Test Directory::   Contains unit tests
+* Tools Directory::  Contains build tools
+@end menu
+
+@node Root Directory
+@subsection Root Directory
+The root directory contains basic project files for common operations.
+
+@table @file
+@item index.js
+This file is loaded automatically when @samp{require( 'easejs' )} is used.
+
+@item LICENSE
+Contains the project license.
+
+@item Makefile
+Invoked by the @command{make} command. Used for building ease.js.
+
+@item package.json
+Used by @command{npm}, a package manager for Node.js, to automate installation.
+
+@item README.md
+Serves as a quick reference for the project, in markdown@footnote{See
+@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen
+because it is displayed nicely on GitHub.
+
+@item TODO
+Incomplete tasks. Future direction of the project. If you're looking to help
+out, take a look at this file to see what needs to be done.
+@end table
+
+These files will be discussed in further detail when they are actually used.
+
+
+@node Doc Directory
+@subsection Doc Directory
+The @file{doc/} directory contains the source files for the manual. The source
+files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.}
+format. Instructions for compiling the documentation are included later in this
+chapter.
+
+API documentation is @emph{not} included in this directory. It is generated from
+the source code.
+
+
+@node Lib Directory
+@subsection Lib Directory
+The @file{lib/} directory contains the source code for the project. Each source
+file represents a single CommonJS module and is written in JavaScript.
+
+@table @file
+@item class.js
+The main Class module. This contains all the functionality necessary to declare
+and extend classes, implement interfaces, etc. This is the bulk of ease.js.
+
+@item interface.js
+Allows declaration and extension of Interfaces.
+
+@item member_builder.js
+Responsible for building class members.
+
+@item propobj.js
+Builds the internal property instance object that is passed around to methods of
+specific class instances. This is the magic behind visibility support, and
+therefore encapsulation.
+
+@item prop_parser.js
+Parses property strings. Note that the name refers to JavaScript properties,
+which are any members of an object. Therefore, this module works on all members.
+
+@item util.js
+General utility functions for property parsing, object cloning, browser
+fallbacks, etc.
+@end table
+
+Unless you are developing for ease.js, you needn't concern yourself with these
+files. @file{index.js}, in the root directory, contains mappings to these files
+where necessary, exposing the useful portions of the API for general use. You
+can use ease.js without even recognizing that the @file{lib/} directory even
+exists.
+
+
+@node Test Directory
+@subsection Test Directory
+The @file{test/} directory contains all the unit tests for the project. ease.js
+follows a test-driven development model. Every single aspect of the framework is
+tested to ensure that features work as intended both server-side and across all
+supported web browsers. The tests also ensure that bugs are not introduced for
+anything that has been covered. This should also give outside developers
+confidence. If a developer makes a modification to ease.js and does not cause
+any failing tests, it's likely that their change didn't have negative
+consequences on the integrity of the framework.
+
+All tests are prefixed with @samp{test-}, followed by the name of the module,
+followed optionally by the specific part of the module that is being tested. The
+tests are written in JavaScript and use Node.js's @file{assert} module. They may
+be run individually or at once during the build process.
+
+Tests are discussed later on in this chapter.
+
+
+@node Tools Directory
+@subsection Tools Directory
+The @file{tools/} directory contains scripts and data necessary for the build
+process. The tools are shell scripts that may be run independently of the build
+process if you find them to be useful. The remaining files are data to accompany
+those tools.
+
+@table @file
+@item combine
+Concatenates all the modules and wraps them for client-side deployment. If
+requested, the tests are also wrapped and concatenated so that they may be run
+in the web browser. The contents are stripped of trailing commas using the
+@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can
+use whatever process he/she wishes to do so. In the future, minification will be
+part of the build script.
+
+@item rmtrail
+Removes trailing commas from object and array definitions. Reads from standard
+in. @emph{This script is not intelligent.} It was designed to work with ease.js.
+It does not, for example, check to ensure that it is not removing commas from
+within strings. This would not be a difficult addition, but is currently
+unnecessary. Use caution when using this tool outside of ease.js.
+
+@item browser-test.html
+Skeleton page to be used after the build process. Runs ease.js unit tests in the
+web browser and reports any failures. This is very important to ensure that
+ease.js operates consistently between all supported browsers. The tests that are
+run are the same exact tests that are run server-side.
+
+@item combine-test.tpl
+Contains a client-side implementation of any modules required for testing. This
+file contains mainly assertions. It is included by the @command{combine} script
+when tests are requested.
+
+@item combine.tpl
+Contains the basic functionality required to get CommonJS modules working
+client-side. This is a very basic implementation, only doing what is necessary
+for ease.js to work properly. It is not meant to be a solution for all of your
+client-side CommonJS problems.
+@end table
+
+While the tools may be useful outside of ease.js in some regard, please note
+that they have been tailored especially for ease.js. They do not contain
+unnecessary features that ease.js does not need to make use of. Therefore, you
+may need to adapt them to your own project and individual needs should you
+decide to use them in your own projects.
+

doc/manual.texi

@@ -42,11 +42,13 @@ This manual is for ease.js, version 0.1.0-pre.
 @end ifnottex
 
 @menu
-* About::   About the project
+* About::        About the project
-* License:: Document License
+* Integration::  How to integrate ease.js into your project
+* License::      Document License
 @end menu
 
 @include ./about.texi
 @include ./license.texi
+@include ./integration.texi
 
 @bye