From f90dc635928f367f9078f814488c7e385ebc4e2e Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Fri, 20 May 2011 17:31:07 -0400
Subject: [PATCH] Documentation.

---
 docs/00_overview.mkd |   95 ++++++++++++++++++++++++++++++++---------------
 1 files changed, 64 insertions(+), 31 deletions(-)

diff --git a/docs/00_overview.mkd b/docs/00_overview.mkd
index 7e286c5..6fdc0a1 100644
--- a/docs/00_overview.mkd
+++ b/docs/00_overview.mkd
@@ -1,53 +1,78 @@
 ## Overview
-Git:Blit is an open-source, integrated pure-Java stack for managing, viewing, and serving [Git](http://git-scm.com) repositories.
-Its designed primarily as a tool for small workgroups who want to host [Git](http://git-scm.com) repositories on a Windows machine.
+Git:Blit is an open-source, integrated pure Java stack for managing, viewing, and serving [Git][git] repositories.
+Its designed primarily as a tool for small workgroups who want to host [Git][git] repositories on a Windows machine.
 
-Of course, since its pure-Java it should run with any JVM on any platform, but there are already [many compelling Git solutions](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools) for non-Windows environments.
+Of course, since its pure Java it should run with any JVM on any platform, but there are already [many compelling Git solutions](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools) for non-Windows environments.
  
 ### Current Version
 
-[{0}](http://gitblit.com/{1}) based on [{2}](http://eclipse.org/jgit) &nbsp; (*{3}*)
+[{0}](http://gitblit.com/{1}) based on [{2}][jgit] &nbsp; (*{3}*)
+
+sources @ [Github][gitbltsrc]
+
+### Design Principles
+1. [KISS](http://en.wikipedia.org/wiki/KISS_principle)
+2. Offer useful features for serving Git repositories.  If feature is complex, refer to #1.
+3. All dependencies must be retrievable from a publicly accessible Maven repository.<br/>This is to ensure authenticity of dependencies and to keep the Git:Blit distribution svelte.  
 
 ### Features
 - Out-of-the-box integrated stack requiring minimal configuration
 - JGit SmartHTTP servlet
 - Browser and git client authentication
-- Four repository access control configurations
-    - *Anonymous View, Clone & Push*
-    - *Authenticated Push*
-    - *Authenticated Clone & Push*
-    - *Authenticated View, Clone & Push*    
-- Repositories may also be frozen (deny push) temporarily or permanently
+- Four repository access control configurations and a Read-Only flag
+    <ul class='noBullets'>
+    <li>![anonymous](blank.png) *Anonymous View, Clone & Push*</li>
+    <li>![push](lock_go_16x16.png) *Authenticated Push*</li>
+    <li>![clone](lock_pull_16x16.png) *Authenticated Clone & Push*</li>
+    <li>![view](shield_16x16.png) *Authenticated View, Clone & Push*</li>
+    <li>![freeze](cold_16x16.png) Freeze repository (i.e. deny push, make read-only)
+    </ul>
 - Gitweb inspired UI
 - Administrators may create, edit, rename, or delete repositories through the web UI
 - Administrators may create, edit, rename, or delete users through the web UI
 - Repository Owners may edit repositories through the web UI
 - Automatically generates a self-signed certificate for https communications
-- Dates can optionally be displayed using browser's reported timezone
+- Dates can optionally be displayed using the browser''s reported timezone
 - Author and Committer email address display can be controlled
+- Markdown view support
 - Syntax highlighting
 - Customizable regular expression handling for commit messages
 - Single text file for server configuration
 - Single text file for users configuration
-- Simple repository stats
-- Optional read-only Docs page which enumerates all Markdown files within a repository
-- Optional read-only Ticgit Ticket pages *(based on last MIT release bf57b032 2009-01-27)*
+- Simple repository stats and activity graph (uses Google Charts)
+- Optional utility pages
+    <ul class='noBullets'>
+    <li>![docs](book_16x16.png) Docs page which enumerates all Markdown files within a repository</li>
+    <li>![tickets](bug_16x16.png) Ticgit ticket pages *(based on last MIT release bf57b032 2009-01-27)*</li>
+    </ul>
 
 ### Limitations
 - HTTP/HTTPS are the only supported protocols
 - Access controls are not path-based, they are repository-based
 - Only Administrators can create, rename or delete repositories
-- Git:Blit is a full-stack solution, its not just a webapp so at this time there is no WAR build
+- Git:Blit is an integrated, full-stack solution.  There is no WAR build at this time.
 
 ### Todo List
+- Manual certificate generation with BouncyCastle
+- User list with edit and delete links
 - Review spots where Git:Blit can cache data instead of abusing the disk
+    - stats
+    - users.properties access
+    - available repositories
+    - etc
+- Download zip feature
+- Site documentation
+- Code documentation
 - Unit testing
+
+### Idea List
 - Ticgit activity/timeline
 - Ticgit query feature with paging support
 - Ticgit ticket change history
-- Implement Markdown editing
 - View images on Blob page
 - View other binary files on Blob page
+- Markdown editing feature
+- Blame feature (waiting for the [JGit][jgit] team to do the hard part)
 
 ### License
 TBD
@@ -61,29 +86,33 @@
 ![block diagram](architecture.png "Git Blit Architecture")
 
 ### Bundled Dependencies
-The following dependencies are bundled with the Git:Blit zip file.
+The following dependencies are bundled with the Git:Blit zip distribution file.
 
-- [google-code-prettify](http://code.google.com/p/google-code-prettify)
-- [JavaService](http://forge.ow2.org/projects/javaservice)
-- icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons)
+- [google-code-prettify](http://code.google.com/p/google-code-prettify) (Apache 2.0)
+- [JavaService](http://forge.ow2.org/projects/javaservice) (BSD and LGPL)
+- icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) (Creative Commons CC-BY)
+- magnifying glass search icon courtesy of [Gnome](http://gnome.org) (Creative Commons CC-BY)
 
 ### Downloaded Dependencies
 The following dependencies are automatically downloaded from the Apache Maven repository and from the Eclipse Maven repository when Git:Blit is launched for the first time.
 
-- [JGit](http://eclipse.org/jgit)
-- [Wicket](http://wicket.apache.org)
-- [WicketStuff GoogleCharts](https://github.com/wicketstuff/core/wiki/GoogleCharts)
-- [MarkdownPapers](http://markdown.tautua.org)
-- [Jetty](http://eclipse.org/jetty)
-- [SLF4J](http://www.slf4j.org)
-- [Log4j](http://logging.apache.org/log4j)
-- [JCommander](http://jcommander.org)
-- [BouncyCastle](http://www.bouncycastle.org)
+- [JGit][jgit] (EDL 1.0)
+- [Wicket](http://wicket.apache.org) (Apache 2.0)
+- [WicketStuff GoogleCharts](https://github.com/wicketstuff/core/wiki/GoogleCharts) (Apache 2.0)
+- [MarkdownPapers](http://markdown.tautua.org) (Apache 2.0)
+- [Jetty](http://eclipse.org/jetty) (Apache 2.0, EPL 1.0)
+- [SLF4J](http://www.slf4j.org) (MIT/X11)
+- [Log4j](http://logging.apache.org/log4j) (Apache 2.0) 
+- [JCommander](http://jcommander.org) (Apache 2.0)
+- [BouncyCastle](http://www.bouncycastle.org) (MIT/X11)
+
+### Other Build Dependencies
+- [Fancybox image viewer](http://fancybox.net) (MIT and GPL dual-licensed)
 
 ## Building
 [Eclipse](http://eclipse.org) is recommended for development as the project settings are preconfigured.
 
-1. Clone the git repository from here.
+1. Clone the git repository from [Github][gitbltsrc].
 2. Import the gitblit project into your Eclipse workspace.<br/>
 *There will be lots of build errors.*
 3. Using Ant, execute the `build.xml` script in the project root.<br/>
@@ -91,4 +120,8 @@
 4. Select your gitblit project root and **Refresh** the project, this should correct all build problems.
 5. Review the settings in `gitblit.properties` in your project root.<br/>
 Make sure you set an appropriate value for *git.repositoriesFolder*. 
-6. Execute the *com.gitblit.Launcher* class to start Git:Blit.
\ No newline at end of file
+6. Execute the *com.gitblit.Launcher* class to start Git:Blit.
+
+[jgit]: http://eclipse.org/jgit "Eclipse JGit Site"
+[git]: http://git-scm.com "Official Git Site"
+[gitbltsrc]: http://somewhere.com "gitblit git repository"
\ No newline at end of file

--
Gitblit v1.9.1