Merge pull request #40 from amber-smalltalk/remove-sudo-npm

Remove sudo npm

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

README.md

@@ -1,5 +1,22 @@
 amber-documentation
 ===================
 
-Amber documentation website
+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 requierements. You need Jekyll in your system: `gem install jekyll`.
+2. Clone this repo with `git clone git@github.com:amber-smalltalk/amber-documentation.git`.
+3. `git checkout -b my-edit-or-new-doc-page`
+4. Run Jekyll with `jekyll serve` (it will rebuild the site after any file gets saved).
+5. Visit `http://localhost:4000` to see the current state.
+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,7 +5,26 @@ permalink: "faq.html"
 parent: Overview
 ---
 
-### Q: How do I get back the Helios IDE after I have closed it
+#### Q: How do I start a new Amber project?
+
+A: You can see the steps [described here](/getting-started.html) which are basically:
+
+{% highlight sh %}
+npm install -g amber-cli
+mkdir newProjectDir
+cd newProjectDir
+amber init
+amber serve
+{% endhighlight %}
+
+And visit `http://localhost:4000`
+
+Here is also an terminal screencast doing just that:
+
+<iframe src="http://showterm.io/457dc8b24df38d67e421d#fast" width="640" height="480"></iframe>
+
+
+#### Q: How do I get back the Helios IDE after I have closed it?
 
 A: Evaluate the following in the JavaScript console:
 

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

@@ -5,16 +5,19 @@ permalink: "js-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.