Merge pull request #53 from amber-smalltalk/how-to-libraries

Great!

1-getting-started.md

@@ -28,7 +28,7 @@ To get Amber running, you will need
 
 {% highlight sh %}
 # Install the CLI tools
-sudo npm install -g amber-cli
+npm install -g amber-cli
 
 # Create the project structure
 mkdir example-project

3-how-to.md

@@ -0,0 +1,8 @@
+---
+title: How-to's
+layout: default
+permalink: "how-tos.html"
+next: "how-to-amber-libaries.html"
+---
+
+The Amber How-To guides are going to show you how to do many common and useful tasks.

README.md

@@ -1,5 +1,25 @@
 amber-documentation
 ===================
 
-Amber documentation website
+[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/amber-smalltalk/amber-documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+This is the repository of the [Amber documentation website](http://docs.amber-lang.net).
+
+The site is developed using [Jekyll](http://jekyllrb.com/).
+
+## How to add a page to this amber-documentation site?
+
+1. Meet requirements. You need Jekyll in your system: `gem install jekyll`.
+2. Fork github.com:amber-smalltalk/amber-documentation.git
+2. Clone your forked repo with `git clone git@github.com:yourgithubusername/amber-documentation.git`.
+3. `git checkout -b my-edit-or-contribution`
+4. Run Jekyll with `jekyll serve` (it will detect and rebuild the site after any file gets saved).
+5. Visit `http://localhost:4000` to see the current state of the documentation.
+6. Edit until you are satisfied.
+7. Commit, push and open a pull request
+
+Thanks! Your contribution makes the world a better place to program!
+
+The Amber Team
+=======
 http://docs.amber-lang.net

faq.md

@@ -5,69 +5,88 @@ permalink: "faq.html"
 parent: Overview
 ---
 
-### Q: How do I get back the Helios IDE after I have closed it
+#### How do I start a new Amber project?
+
+You can see the steps [described here](/getting-started.html) which are basically:
+
+1. `npm install -g amber-cli`
+2. `mkdir newProjectDir`
+3. `cd newProjectDir`
+4. `amber init`
+5. `amber serve`
+
+And visit [http://localhost:4000](http://localhost:4000)
+
+Here is also a terminal screencast doing just that:
+
+<iframe src="http://showterm.io/457dc8b24df38d67e421d#fast" width="640" height="480"></iframe>
+
+
+#### How do I get back the Helios IDE after I have closed it?
 
 Press this sequence of keys: Shift, Shift, Ctrl, Shift.
 A dialog should appear with "Legacy IDE" and "Helios IDE" buttons. 
 
 In case the above did not work, evaluate the following in the JavaScript console:
 
-    require('amber/helpers').popupHelios()
+`require('amber/helpers').popupHelios()`
 
     
-### Q: What version is the amber website running?
+#### What version is the Amber website running?
 
-1.    Open IDE at http://amber-lang.net/.
-2.    Go to Workspace tab.
-3.    Print-it ``Smalltalk version``.
-4.    
+1.    Open IDE at [http://amber-lang.net/](http://amber-lang.net/).
+2.    Go to the Workspace tab.
+3.    Print or inspect the expression ``Smalltalk version``.
 
-### How do I install the latest Amber version?
+#### How do I install the latest Amber version?
 
-'Latest' often means the 'latest stable'. If this is the case go for
+For the **latest stable**, go for
 
-      npm -g install amber-cli
+`npm -g install amber-cli`
 
-If you mean really the prereleases, 
+If you want the **latest prerelease**, go for
 
-      npm -g install amber-cli@bleedingedge 
+`npm -g install amber-cli@bleedingedge`
 
-should install the last prerelease (but not the stable version even if it is newer).
+Note that bleedingedge will *not* install the stable version even if it is newer.
 
-Use `npm info amber-cli` to find out which version is latest and which one is bleedingedge, if you are unsure.
+If you want to be sure which version is latest and which one is bleedingedge use:
+`npm info amber-cli` and you will find them in the `dist-tags` section.
 
+#### How do I update Amber?
 
-### How do I update Amber?
+1. ``npm install -g amber-cli``  will get it fixed for all new projects and 
 
--  ``npm install -g amber-cli``  will get it fixed for all new projects and 
+2.  ``npm update amber-dev`` in every project dir will fix it for current projects
 
--  ``npm update amber-dev`` in every project dir will fix it for current projects
+3. `bower install` in every project dir will fix it for current projects
 
 
-### How do I get the text value of an input field?
+#### How do I get the text value of an input field?
 
-Assuming I have a field with an id of #field1, how do I get the text value of it?
+If you have `<input id="field1" ...`, the way to get its value is `'#field1' asJQuery val`.
 
-Answer:
+#### How can I 'call' JavaScript functions from my Amber code? 
 
-   '#field1' asJQuery val
+To allow you to use JavaScript from your Amber code, Amber uses a proxy that will route Smalltalk messages as JavaScript calls as transparent as possible. For example, _all_ JavaScript methods in jQuery are available to you this way:
 
-Note:
+**Without arguments**: 
 
-All Javascript methods in jQuery are available to you this way.
+`'#element-id' asJQuery hide`
+`'#element-id' asJQuery show`
 
-Multi parameter functions are then mapped like:
+**With one argument**: 
 
-    aQuery.sampleFunc (a,b,c);
+`'#element-id' asJQuery attr: 'data' put: 'some-value'`
 
-    aQuery sampleFunc: a and: b and: c.
+**With many arguments**:
 
-The ``and:`` can be whatever. The only thing that matters is the first part of the keyword selector which has to match the function name.
+`aQuery.sampleFunc(a,b,c);` translates to `aQuery sampleFunc: a andThis: b andThat: c.`
 
+In the previous examples, the `put:` and the ``andThis:andThat:`` part of the Smalltalk selector can be named any way you want. For JavaScript functions the names in that part of the keyword are ignored. Amber  needs only the first part of the selector matching the JavaScript function name.
 
+#### Where can I find more questions and answers?
 
-### More questions and answers 
+You can try the [wiki](https://github.com/amber-smalltalk/amber/wiki/FAQ) or join the Amber's chat group [here](https://gitter.im/amber-smalltalk/amber).
 
-On the wiki
-https://github.com/amber-smalltalk/amber/wiki/FAQ
 

how-tos/1-how-to-amber-lbraries.md

@@ -0,0 +1,88 @@
+---
+title: How to create, publish and use Amber libraries
+layout: default
+parent: How-to's
+permalink: "how-to-amber-libaries.html"
+next: "how-to-next.html"
+---
+
+People can visit [bower](http://bower.io/search/) and find JavaScript libraries to solve the most diverse problems and empower their applications with lots of cool things. 
+
+Amber Smalltalk allows easy integration of these libraries. But besides using third party JavaScript libraries, your Amber application can use your own Amber libraries.
+
+In this guide you'll see how to create, publish and use Amber libraries.
+
+### How to create an Amber library?
+
+1. Run `amber init` in an empty directory; same as to start a new Amber project.
+answer the questions to get your project scaffolded (see tips about naming your library below)
+2. Run `git init` to make the directory a git repository.
+3. Add `config.js` and `the.js` into `.gitignore` because a library has no need to commit them in your git repo.
+4. Evaluate `amber serve`.
+5. Point your browser to hit Amber's endpoint which would be [http://localhost:4000](http://localhost:4000) unless you had specified a different one.
+6. Start developing your library using Amber and the IDE as with any normal Amber code
+commit your packages from the IDE.
+7. Version your project with: `git commit -am "I've made this Amber library and this version rocks!"`.
+
+### Tips about naming your Amber library
+
+When you create a new Amber project, one of the things you need to answer is the name of the project. In this case you will be deciding about the name of your new library. Also, you define the namespace of the library. This namespace is important because it is used by requirejs to locate and properly load the code in your project. 
+
+After the library is published, the namespace can not be changed anymore since it would break other people's code. Therefore, it is e essential to come up with a good name at library creation time. Keep in mind that the namespace you define has to be the same as the one in the  “paths” section of the `local.amd.json` file in the root of your project. 
+
+### How to publish your Amber library?
+
+1. Once your library is ready for consumption by a wider audience, push your repository to a publicly accessible git repository e.g. GitHub, Bitbucket, GitLab or any other public git repository.
+2. Choose the version you will publish. To make it public, bower requires that you use valid Semantic Versioning. For example, version `0.x.y` for pre-production stages and `x.y.z` with `x>=1` when that library is used in production and cares about backwards compatibility. For more about semantic versioning read here: [http://semver.org/](http://semver.org/).
+3. Then, either go with next three steps:
+- Edit the bower.json file and make sure you are defining the version number you want to publish. e.g.: "version": "0.9.2".
+- Commit those changes.
+- Tag that commit with the semver version you want to publish. For example, if you want to tag your last master commit as 0.9.2 then you do `git tag 0.9.2` in your master branch.
+4. Or, do the aforementioned three steps in one convenient command by using  `bower version 0.9.2 -m “Release 0.9.2”`. See [here](http://bower.io/docs/api/#version) for more details about that.
+5. Finally, push the tag to the public repository to make the new version available to the world. Following our example here, if you want to publish that 0.9.2 commit on your local master after tagging it, you just push it with `git push origin 0.9.2`.
+
+And here comes the best part. Because you did all that with your Amber library, anyone can install it quite easily using one single command thanks to the bower.io package management system.
+
+This is the command to register your library in bower:
+
+`bower register [lib-name] [git endpoint]`
+
+e.g.:
+
+`bower register amber-awesome-trick git@github.com/amberguy/amber-awesome-trick.git`
+
+###A couple of tips about publishing in bower
+
+- The registration is a one-time operation. If you registered your library already, you just tag and push the new version.
+- Regarding the naming of your Amber libraries: as long as the name is not taken in the bower repository, you can name your Amber library however you want. It is advisable to prefix it with `amber-`. For example, if you write a D3 wrapper you can publish it as `amber-d3`. If you create code to use three.js, your library will be easier to find if it is named `amber-threejs` and so on.
+- The `bower.json` file has a section named `keywords`, for Amber libraries, we suggest that you tag it like this `"keywords": [ "Amber","Smalltalk","AnyAdditionalTagYouWant" ]`, when you do that, it gets listed when people search for [http://bower.io/search/?q=amber](http://bower.io/search/?q=amber) or [http://bower.io/search/?q=smalltalk](http://bower.io/search/?q=smalltalk).
+
+### How to use your Amber library in Amber projects?
+
+You have published your library in bower, great! Congratulations! Now, how do you use it in other Amber projects? This is the easy part:
+
+1. You bring the library into the directory tree of the project with bower.
+2. Configure `deploy.json` and `devel.json` so your app knows what to load.
+3. Use grunt to prepare the code you need for using it.
+4. Start using it!
+
+Here are the commands:
+
+1. To install the library in your app you do: `bower install lib-name --save`.
+2. Edit `deploy.js` to setup the list of packages from the library that your app needs, for example: `amber-d3/AmberD3-View` and `amber-d3/AmberD3-Core` and any other package that your app might be using from that library.
+3. Rebuild the development infrastructure by running: `grunt devel`.
+4. Reload your app. All the classes from the packages you listed in point 2 can now load as expected and are present and accessible from your IDE.
+
+### Conclusion
+
+That's how you do Amber libraries, publish them for reuse and load them into other Amber apps. 
+
+The bower repository is extremely popular these days and a source of great libraries for many people building application frontends or html5-based applications.
+
+Additionally, getting your Amber-based software there will make fellow Amber programmers able to do even more powerful things with their software. 
+
+Have you made some Amber libraries?
+
+Please announce the libraries you publish on the Amber mailing list so that people know it was added to our growing catalogue of Amber libraries.
+
+And see what others Amber users have published [here](http://bower.io/search/?q=amber).

index.md

@@ -5,21 +5,16 @@ hide: true
 next: getting-started.html
 ---
 
-<p class="warning">
-This documentation is a work in progress. 
-</p>
+### Welcome 
+
+This is the Amber documentation website. The purpose of this documentation is to guide you step by step from learning <a href="/installing.html">how to install Amber</a> to being an advanced Amber developer.
 
-Welcome to the Amber documentation website!
+Currently we covered the firsts steps of <a href="/installing-amber.html">installing</a> and <a href="/getting-started.html">getting started</a> with a new Amber project.
 
 <p class="note">
-This documentation and guides are a community effort, you can
-<a href="https://github.com/amber-smalltalk/amber-documentation">contribute</a> your
-own guide!
+This documentation and guides are a community effort. You figured out how to do something useful or cool? Great! Share it with us! <a href="https://github.com/amber-smalltalk/amber-documentation">Contribute</a> with your own guide here!
 </p>
 
-The purpose of this documentation is to guide you step by step from
-learning how to install Amber to being an advanced Amber developer.
-
 ### What is Amber?
 
 Amber is a language and development environment made for the web. The
@@ -39,7 +34,7 @@ debugger.
 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
+and semantically. It is a pure Object Oriented language, with objects all the way
 down.
 
 - Also, having a true live & incremental development environment where
@@ -54,3 +49,5 @@ object.
 
 Evaluating JavaScript object methods is transparent and makes using
 libraries a breeze.
+
+<a href="/installing-amber.html">Installing Amber</a>.

js-glossary.md → javascript-glossary.md

@@ -1,20 +1,23 @@
 ---
-title: JS ecosystem glossary
+title: JavaScript ecosystem glossary
 layout: default
-permalink: "js-glossary.html"
+permalink: "javascript-glossary.html"
 parent: Overview
 ---
 
+
 ### What is `bower`?
 
 Bower is a dependency management tool for client-side web packages. Each package can specify its production dependencies and its development-only dependencies by name and semver version expression. Package dependencies are specified in a `bower.json` file. Bower, when asked to install dependencies, looks for dependencies of the project and for dependencies of dependencies all the way down, unifies version constraints and then installs all dependencies from all levels of the hierarchy in flat manner (side-by-side) into directory `bower_components`.
 
+
 ### Where is `bower` used in Amber?
 
 Amber itself is a client-side web package, so Amber itself is a bower package and uses bower to manage its own client-side dependencies (jQuery and others).
 
 An Amber web project (a client-side web project that uses Amber) is encouraged to use bower to manage its dependencies as well, listing Amber itself as one of them. Default projects (the ones created by `amber init`) do just that.
 
+
 ### What is `grunt`?
 
 Grunt is a build system for the JavaScript ecosystem. In the root directory of the project, grunt looks for a file called `Gruntfile.js`. This defines tasks to be done and binds them together, similarly to what a `Makefile` does for the `make` build system in UNIX. Grunt is installed through the npm package manager and must be installed in three parts:
@@ -22,10 +25,12 @@ Grunt is a build system for the JavaScript ecosystem. In the root directory of t
 - `grunt-xxx-yyy` - modules with reusable tasks, also as development dependency of the project, and
 - `grunt-cli`, the CLI command that drives the runtime using `Gruntfile.js`, which should be installed globally.
 
+
 ### Where is `grunt` used in Amber?
 
 Amber itself and default Amber projects (the ones created by `amber init`) both contain `Gruntfile.js` and they include `grunt` and accompanying grunt task modules as development dependencies. In an Amber project, grunt is used to recompile Smalltalk source to JavaScript files from the command line (CLI), as well as running the tests from CLI. In Amber itself, grunt is used for the same, plus a few bookkeeping tasks.
 
+
 ### What is `grunt-init`?
 
 Grunt-init is a create-project-from-a-template tool, spawned from `grunt` to be a standalone tool. It defines an API. The templates themselves are created as isolated `npm` packages, which the `grunt-init` CLI command can use. In template modules, you define the skeleton of the project, a set of questions to ask when the project is created and the way they are included in the skeleton. The result is, by running `grunt-init` with a specific template, you answer a few questions, and a project is created for you base on the answers.

overview/1-installing-amber.md

@@ -52,20 +52,12 @@ Once nodejs and npm are installed, evaluate:
 npm install -g amber-cli
 {% endhighlight %}
 
-Ubuntu users will have to evaluate it with `sudo`:
-
-{% highlight sh %}
-sudo npm install -g amber-cli
-{% endhighlight %}
-
-
 ### 2. The bower component
 
 <p class="note">
 The following section explains how to manually setup Amber using Bower. The <code>amber init</code> command provided by the npm package automates it. Unless you want to (a) understand how it works or (b) setup Amber differently, you can refer to the <a href="/getting-started.html">getting started</a> page.
 </p>
 
-
 The npm package doesn't provide the JavaScript files required to load
 Amber in a page. This is instead provided by the bower package.
 
@@ -74,15 +66,14 @@ easy to manage dependencies in your application including
 Amber. Unlike npm, Bower components are meant to be used inside the
 web browser.
 
-If not already present, Bower is installed using npm: `npm install -g bower`,
-on some OSes (Linux, FreeBSD) `sudo npm install -g bower`.
+If not already present, Bower is installed using npm: `npm install -g bower`
 
 In the root directory of the project,
 Amber bower component can be installed either by
 
-```sh
+{% highlight sh %}
 bower install amber --save
-```
+{% endhighlight %}
 
 or by adding a `bower.json` file like the following:
 
@@ -96,11 +87,10 @@ or by adding a `bower.json` file like the following:
 {% endhighlight %}
 
 and evaluating
-```sh
+{% highlight sh %}
 bower install
-```
+{% endhighlight %}
 
 In both cases, Amber will be installed in a directory named `bower_components`.
 
-
 We will see in the next section how to setup a project using bower.

overview/3-creating-packages.md

@@ -1,47 +1,10 @@
 ---
-title: Creating & Saving Packages
+title: Creating Packages
 layout: default
 permalink: "creating-packages.html"
 parent: Overview
 ---
 
-This sections presents an overview of package management with Helios.
-
 <p class="warning">
-This page is a work in progress.
+This page is waiting for you to write it.
 </p>
-
-#### Creating packages
-
-Amber packages are created using the package template of Helios.
-
-![Package template in Helios](../images/package-template.png)
-
-First go to the package pane in Helios, then change the template
-contents to create a new package.  The `namespace:` value of the
-`AmdPackageTransport` defines the AMD module bound to the
-package. Several packages can use the same AMD namespace.
-
-A namespace represents a module (AMD) name, used by `requirejs` to
-load the package in the HTML page (see below). Given that a package
-uses an AMD module to be loaded/saved to disk (which is the default),
-Helios will use the module path to save the package to disk.
-
-
-#### Saving packages to disk
-
-The AMD namespace of a package is used by Helios to determine where the
-package should be committed to disk.
-
-<p class="note"> If the namespace of a package is not known by Helios,
-it will prompt for the path when you will try to save the package for
-the first time.  </p>
-
-![Setting the commit path of new namespaces](../images/setting-commit-path.png)
-
-#### Loading packages
-
-In order to have our extra packages loaded by default in the page, we
-have to tell Amber to load the packages. In our `index.html` page we
-only load the `amber-devel` module, which contains all core Amber
-packages.