Moved the documentation here from the main repository

documentation.html

@@ -31,7 +31,7 @@
 	<img class="left" src="images/amber_small.png"/> 
 	<div class="left">
 	  <h1>Amber Smalltalk - documentation</h1>
-	  <h2>Version 0.9.1</h2>
+	  <h2>Version 0.10</h2>
 	</div>
 	<div class="clear"></div>
       <ul id="tabs"> 
@@ -42,7 +42,7 @@
       
       <div class="clear"></div> 
     </div>
-    <script type='text/javascript'> loadAmber({files: ['Documentation.js']}) </script> 
+      <script type='text/javascript'> loadAmber({packageHome: '../documentation/', packages: ['Documentation']}) </script> 
     
   </body> 
 </html> 

documentation/st/Documentation.st

@@ -0,0 +1,606 @@
+Smalltalk current createPackage: 'Documentation' properties: #{}!
+Object subclass: #ChapterSelectionAnnouncement
+	instanceVariableNames: 'id'
+	package: 'Documentation'!
+
+!ChapterSelectionAnnouncement methodsFor: 'accessing'!
+
+id
+	^id
+!
+
+id: aString
+	id := aString
+! !
+
+Object subclass: #ClassSelectionAnnouncement
+	instanceVariableNames: 'theClass'
+	package: 'Documentation'!
+
+!ClassSelectionAnnouncement methodsFor: 'accessing'!
+
+theClass
+	^theClass
+!
+
+theClass: aClass
+	theClass := aClass
+! !
+
+!ClassSelectionAnnouncement class methodsFor: 'instance creation'!
+
+on: aClass
+	^self new
+		theClass: aClass;
+		yourself
+! !
+
+Widget subclass: #DocChapter
+	instanceVariableNames: 'title contents parent level'
+	package: 'Documentation'!
+
+!DocChapter methodsFor: 'accessing'!
+
+announcer
+	^DocumentationBuilder current announcer
+!
+
+chapters
+	"A doc chapter can contain sub chapters"
+	^#()
+!
+
+contents
+	^contents ifNil: ['']
+!
+
+contents: aString
+	contents := aString
+!
+
+cssClass
+	^'doc_chapter'
+!
+
+htmlContents
+	^(Showdown at: #converter) new makeHtml: self contents
+!
+
+id
+	"The id is used in url fragments. 
+	It must be unique amoung all chapters"
+	^self title replace: ' ' with: '-'
+!
+
+level
+	^self parent ifNil: [1] ifNotNil: [self parent level +1]
+!
+
+level: anInteger
+	level := anInteger
+!
+
+parent
+	^parent
+!
+
+parent: aChapter
+	parent := aChapter
+!
+
+title
+	^title ifNil: ['']
+!
+
+title: aString
+	title := aString
+! !
+
+!DocChapter methodsFor: 'actions'!
+
+displayChapter: aChapter
+	DocumentationBuilder current widget displayChapter: aChapter
+!
+
+selectChapter: aChapter
+	document location hash: aChapter id
+!
+
+selectClass: aClass
+	DocumentationBuilder current announcer announce: (ClassSelectionAnnouncement on: aClass)
+! !
+
+!DocChapter methodsFor: 'initialization'!
+
+initialize
+	super initialize.
+	self subscribe
+! !
+
+!DocChapter methodsFor: 'rendering'!
+
+renderDocOn: html
+	| div |
+	html h1 with: self title.
+	self renderNavigationOn: html.
+	div := html div class: 'contents'.
+	div asJQuery html: self htmlContents
+!
+
+renderLinksOn: html
+	html ul 
+		class: 'links';
+		with: [
+			self chapters do: [:each |
+				html li with: [
+					html a
+						with: each title;
+						onClick: [self selectChapter: each]]]]
+!
+
+renderNavigationOn: html
+	self parent ifNotNil: [
+		html div 
+			class: 'navigation'; with: [
+				html a
+					with: '← back to ', self parent title;
+					onClick: [self selectChapter: self parent]]]
+!
+
+renderOn: html
+	html div 
+		class: self cssClass;
+		with: [
+			self renderDocOn: html.
+			self renderLinksOn: html]
+! !
+
+!DocChapter methodsFor: 'subscriptions'!
+
+subscribe
+	self announcer on: ChapterSelectionAnnouncement do: [:ann |
+		ann id = self id ifTrue: [self displayChapter: self]]
+! !
+
+DocChapter subclass: #ClassDocChapter
+	instanceVariableNames: 'theClass'
+	package: 'Documentation'!
+
+!ClassDocChapter methodsFor: 'accessing'!
+
+contents
+	^self theClass comment isEmpty
+		ifTrue: [self theClass name, ' is not documented yet.']
+		ifFalse: [self theClass comment]
+!
+
+cssClass
+	^'doc_class ', super cssClass
+!
+
+initializeWithClass: aClass
+	theClass := aClass
+!
+
+theClass
+	^theClass
+!
+
+title
+	^self theClass name
+! !
+
+!ClassDocChapter methodsFor: 'rendering'!
+
+renderLinksOn: html
+	html ul 
+		class: 'links';
+		with: [
+			html li with: [html a
+				with: 'Browse this class';
+				onClick: [Browser openOn: self theClass]]]
+! !
+
+!ClassDocChapter methodsFor: 'subscriptions'!
+
+subscribe
+	super subscribe.
+	self announcer 
+		on: ClassSelectionAnnouncement do: [:ann |
+			ann theClass = self theClass ifTrue: [
+				self selectChapter: self]]
+! !
+
+!ClassDocChapter class methodsFor: 'accessing'!
+
+on: aClass
+	^self basicNew
+		initializeWithClass: aClass;
+		initialize;
+		yourself
+! !
+
+DocChapter subclass: #ClassesIndexChapter
+	instanceVariableNames: ''
+	package: 'Documentation'!
+
+!ClassesIndexChapter methodsFor: 'accessing'!
+
+alphabet
+	^'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+!
+
+cssClass
+	^'index_doc ', super cssClass
+!
+
+title
+	^'Smalltalk classes by index'
+! !
+
+!ClassesIndexChapter methodsFor: 'rendering'!
+
+renderDocOn: html
+	html h1 with: self title.
+	self alphabet do: [:letter || classes |
+		classes := Smalltalk current classes select: [:each | each name first = letter].
+		classes ifNotEmpty: [html h2 with: letter].
+		html ul with: [
+			(classes sorted: [:a :b | a name < b name]) 
+				do: [:each |
+					html li with: [html a 
+						with: each name;
+						onClick: [self selectClass: each]]]]]
+! !
+
+DocChapter subclass: #PackageDocChapter
+	instanceVariableNames: 'package chapters'
+	package: 'Documentation'!
+
+!PackageDocChapter methodsFor: 'accessing'!
+
+chapters
+	^chapters
+!
+
+contents
+	^'Classes in package ', self package name, ':'
+!
+
+package
+	^package
+!
+
+title
+	^'Package ', self package name
+! !
+
+!PackageDocChapter methodsFor: 'initialization'!
+
+initializeWithPackage: aPackage
+	package := aPackage.
+	chapters := (aPackage classes sorted: [:a :b | a name < b name]) collect: [:each |
+		(ClassDocChapter on: each)
+			parent: self;
+			yourself]
+! !
+
+!PackageDocChapter class methodsFor: 'instance creation'!
+
+on: aPackage
+	^self basicNew
+		initializeWithPackage: aPackage;
+		initialize;
+		yourself
+! !
+
+DocChapter subclass: #TutorialsChapter
+	instanceVariableNames: ''
+	package: 'Documentation'!
+
+!TutorialsChapter methodsFor: 'accessing'!
+
+contents
+	^'You can find a list of [Tutorials](https://github.com/amber-smalltalk/amber/wiki/Tutorials) on the [Github wiki](https://github.com/amber-smalltalk/amber/wiki). If you are new to Smalltalk, you can also learn Amber online with [ProfStef](http://www.amber-lang.net/learn.html).'
+!
+
+title
+	^'Tutorials'
+! !
+
+Object subclass: #DocumentationBuilder
+	instanceVariableNames: 'chapters announcer widget'
+	package: 'Documentation'!
+
+!DocumentationBuilder methodsFor: 'accessing'!
+
+announcer
+	^announcer ifNil: [announcer := Announcer new]
+!
+
+chapters
+	^chapters ifNil: [chapters := self buildChapters]
+!
+
+widget
+	^widget ifNil: [widget := DocumentationWidget on: self]
+! !
+
+!DocumentationBuilder methodsFor: 'building'!
+
+build
+	self buildOnJQuery: ('body' asJQuery)
+!
+
+buildChapters
+	^((self class methodDictionary values sorted: [:a :b | a selector < b selector])
+		select: [:each | each category = 'chapters'])
+		collect: [:each | self perform: each selector]
+!
+
+buildOn: aCanvas
+	aCanvas with: self widget.
+	self 
+		checkHashChange;
+		checkHash
+!
+
+buildOnJQuery: aJQuery
+	self buildOn: (HTMLCanvas onJQuery: aJQuery)
+! !
+
+!DocumentationBuilder methodsFor: 'chapters'!
+
+ch1introduction
+	^DocChapter new
+		title: 'Introduction';
+		contents: '
+
+##Amber Smalltalk in a nutshell
+
+Amber is an implementation of the Smalltalk-80 language. It is designed to make client-side web development **faster, easier and more fun** as it allows developers to write HTML5 applications in a live Smalltalk environment!!
+
+Amber is written in itself, including the IDE and the compiler and it runs **directly inside your browser**. The IDE is fairly complete with a class browser, workspace, transcript, unit test runner, object inspectors, cross reference tools and even a debugger.
+
+Noteworthy features:
+
+- Amber is semantically and syntactically very close to [Pharo Smalltalk](http://www.pharo-project.org). Pharo is considered the reference implementation.
+- Amber **seamlessly interacts with JavaScript** and can use its full eco system of libraries without any glue code needed.
+- Amber **has no dependencies** and can be used in any JavaScript runtime, not only inside browsers. An important example is [Node.js](http://nodejs.org).
+- Amber is a live Smalltalk that **compiles incrementally into efficient JavaScript** often mapping one-to-one with JavaScript equivalents.
+- Amber has a **Seaside influenced canvas library** to dynamically generate HTML.
+
+## Why Amber?
+
+- JavaScript is quite a broken language with lots of traps and odd quirks. It is the assembler of the Internet which is cool, but we don''t want to write in it.
+- Amber is a language and environment built for the web. With Amber, client-side web development finally gets the power and productivity that exists in other Smalltalk dialects.
+- Smalltalk has a simple class model with a lightweight syntax for closures, it is in many ways a perfect match for the Good Parts of JavaScript. 
+  Smalltalk stands head and shoulders above most other languages for clarity, conciseness, and human-friendliness.
+  As a language, it is immensely clean and mature, both syntactically and semantically. It is a pure OO language, with objects all the way down.
+- Having a true live & incremental development environment where you can build your application interactively in the browser is unbeatable.
+
+## Disclaimer
+
+This documentation doesn''t aim to teach Smalltalk. 
+Knowledge of Smalltalk is needed to understand the topics covered in this documentation. 
+If you want to learn the Smalltalk language, you can read the excellent [Pharo By Example](http://www.pharobyexample.org) book.
+'
+!
+
+ch2differencesWithOtherSmalltalks
+	^DocChapter new
+		title: 'Differences with other Smalltalks';
+		contents: '
+Amber has some differences with other Smalltalk implementations. This makes porting code a non-trivial thing, but still quite manageable.
+Because it maps Smalltalk constructs one-to-one with the JavaScript equivalent, including Smalltalk classes to JavaScript constructors, the core class library is simplified compared to Pharo Smalltalk.
+And since we want Amber to be useful in building lean browser apps we can''t let it bloat too much.
+
+But apart from missing things other Smalltalks may have, there are also things that are plain different:
+
+- The collection class hierarchy is much simpler compared to most Smalltalk implementations. In part this is because we want to map reasonably well with JavaScript counter parts.
+- As of today, there is no SortedCollection. The size of arrays is dynamic, and they behave like an ordered collection. They can also be sorted with the `#sort*` methods.
+- The `Date` class behaves like the `Date` and `TimeStamp` classes in Pharo Smalltalk. Therefore both `Date today` and `Date now` are valid in Amber.
+- Amber does not have class Character, but `String` does implement some of Character behavior so a single character String can work as a Character.
+- Amber does support **class instance variables**, but not class variables.
+- Amber only has global classes and packages, but not arbitrary objects. Use classes instead like `Smalltalk current` instead of `Smalltalk` etc.
+- Amber does not support pool dictionaries.
+- Amber uses **< ...javascript code... >** to inline JavaScript code and does not have pragmas.
+- Amber does not have class categories. The left side in the browser lists real Packages, but they feel much the same.
+'
+!
+
+ch3GettingStarted
+	^DocChapter new
+		title: 'Getting started';
+		contents: '
+To get started hacking in Amber you can basically take three routes, independent of your platform:
+
+1. Just **try it out directly** at [www.amber-lang.net](http://www.amber-lang.net) - click the **Class browser** button there. But you will **not be able to save any code you write**!! 
+    Still, it works fine for looking at the IDE and playing around. Just **don''t press F5/reload** - it will lose any code you have written.
+2. Download an Amber zip-ball, install [Nodejs](http://www.nodejs.org), fire up the Amber server and then open Amber from localhost - then you **can save code**. Detailed instructions are below!!
+3. Same as above but install git first and get a proper clone from [http://github.com/NicolasPetton/amber](http://github.com/NicolasPetton/amber) instead of a zip/tar-ball. 
+    If you want to **contribute to Amber itself** this is really what you want to do. In fact, in most cases this is what you want to do. It requires installing git first, but it is quite simple - although we leave this bit as an "exercise to the reader" :)
+
+
+## Downloading Amber
+Currently you can download in zip or tar-ball format, either cutting edge or a release. [Downloads are available here](https://github.com/NicolasPetton/amber/archives/amber). 
+
+Unpack wherever you like, but I would rename the directory that is unpacked to something slightly shorter - like say "amber". :)
+And yes, at this point you can double click the index.html file in the amber directory to get the IDE up, but again, **you will not be able to save code**. So please continue below :)
+
+## Installing Node.js
+[Node](http://www.nodejs.org) (for short) is simply the V8 Javascript VM from Google (used in Chrome) hooked together with some hard core C-libraries for doing "evented I/O".
+Basically it''s JavaScript for the server - on asynch steroids. Amber runs fine in Node and we use it for several Amber tools, like amberc (the command line Amber compiler) or the Amber server (see below). 
+There are also several Amber-Node examples to look at if you want to play with running Amber programs server side. **In short - you really want to install Nodejs. :)**
+
+- Installing Node on Linux can be done using your package tool of choice (`apt-get install nodejs` for example) or any other way described at [the download page](http://nodejs.org/#download).
+- Installing Node on MacOS or Windows is probably done best by using the [installers available at Nodejs.org](http://nodejs.org/#download).
+
+## Starting Amber server
+Nicolas has written a minimal webDAV server that is the easiest way to get up and running Amber with the ability to save code. This little server is written in... Amber!! 
+And it runs on top of Node. So to start it up serving your brand new directory tree of sweet Amber you do:
+
+	cd amber	(or whatever you called the directory you unpackaged)
+	./bin/server	(in windows you type `node server\server.js` instead)
+
+It should say it is listening on port 4000. If it does, hooray!! That means both Node and Amber are good. In Windows you might get a question about opening that port in the local firewall - yep, do it!!
+
+## Firing up Amber
+The Amber IDE is written in... Amber. It uses [jQuery](http://jquery.com) and runs right in your browser as a ... well, a web page. 
+We could open it up just using a file url - but the reason we performed the previous steps is so that we can load the IDE web page from a server that can handle PUTs (webDAV) of source code. 
+According to web security Amber can only do PUT back to the same server it was loaded from. Thus we instead want to open it [through our little server now listening on port 4000](http://localhost:4000/index.html).
+Clicking that link and then pressing the **Class browser** should get your Amber IDE running with the ability to commit modified packages locally.
+
+To verify that you can indeed commit now - just select a Package in the browser, like say "Examples" and press the **Commit** button below. **If all goes well nothing happens :)**. 
+So in order to really know if it worked we can check the modified date on the files **amber/st/Examples.st**, **amber/js/Examples.js** and **amber/js/Examples.deploy.js** - they should be brand new.
+
+NOTE: We can use any webDAV server and Apache2 has been used earlier and works fine. But the Amber server is smaller and simpler to start.
+'
+!
+
+ch4Tutorials
+	^TutorialsChapter new
+!
+
+ch5Index
+	^ClassesIndexChapter new
+!
+
+ch6KernelObjects
+	^PackageDocChapter on: (Package named: 'Kernel-Objects')
+!
+
+ch7KernelClasses
+	^PackageDocChapter on: (Package named: 'Kernel-Classes')
+!
+
+ch8KernelCollection
+	^PackageDocChapter on: (Package named: 'Kernel-Collections')
+!
+
+ch9KernelMethods
+	^PackageDocChapter on: (Package named: 'Kernel-Methods')
+! !
+
+!DocumentationBuilder methodsFor: 'routing'!
+
+checkHash
+	| hash presentation |
+	hash := document location hash  replace: '^#' with: ''.
+	self announcer announce: (ChapterSelectionAnnouncement new 
+		id: hash; 
+		yourself)
+!
+
+checkHashChange
+	(window jQuery: window) bind: 'hashchange' do: [self checkHash]
+! !
+
+!DocumentationBuilder methodsFor: 'updating'!
+
+update
+	chapters := nil.
+	announcer := nil.
+	widget := nil.
+	(window jQuery: '.documentation') remove.
+	self build
+! !
+
+DocumentationBuilder class instanceVariableNames: 'current'!
+
+!DocumentationBuilder class methodsFor: 'accessing'!
+
+current
+	^current ifNil: [current := self new]
+! !
+
+!DocumentationBuilder class methodsFor: 'initialization'!
+
+initialize
+	self current build
+! !
+
+Widget subclass: #DocumentationWidget
+	instanceVariableNames: 'builder selectedChapter chapterDiv'
+	package: 'Documentation'!
+
+!DocumentationWidget methodsFor: 'accessing'!
+
+builder
+	^builder
+!
+
+builder: aDocumentationBuilder
+	builder := aDocumentationBuilder
+!
+
+chapters
+	^self builder chapters
+!
+
+selectedChapter
+	^selectedChapter ifNil: [selectedChapter := self chapters first]
+!
+
+selectedChapter: aChapter
+	^selectedChapter := aChapter
+! !
+
+!DocumentationWidget methodsFor: 'actions'!
+
+displayChapter: aChapter
+	self selectedChapter: aChapter.
+	self updateChapterDiv
+!
+
+selectChapter: aChapter
+	document location hash: aChapter id
+! !
+
+!DocumentationWidget methodsFor: 'rendering'!
+
+renderChapterMenu: aChapter on: html
+	html a
+		with: aChapter title;
+		onClick: [
+			self selectChapter: aChapter].
+	html ol with: [
+			aChapter chapters do: [:each |
+				html li with: [
+					self renderChapterMenu: each on: html]]]
+!
+
+renderMenuOn: html
+	html div 
+		class: 'menu';
+		with: [
+			html ol with: [
+				self chapters do: [:each |
+					html li with: [
+						self renderChapterMenu: each on: html]]]]
+!
+
+renderOn: html
+	html div 
+		class: 'documentation';
+		with: [
+			self renderMenuOn: html.
+			chapterDiv := html div.
+			self updateChapterDiv]
+! !
+
+!DocumentationWidget methodsFor: 'updating'!
+
+updateChapterDiv
+	chapterDiv contents: [:html |
+		html with: self selectedChapter]
+! !
+
+!DocumentationWidget class methodsFor: 'instance creation'!
+
+on: aBuilder
+	^self new
+		builder: aBuilder;
+		yourself
+! !
+