[PATCH 2/2] doc: restructure Getting Started page

[Lucas De Marchi]

Restructure this pages so it first gives a minimal set of commands to
get the environment setup and then explains the other parts. We
tailor the commands so the user already clones the maintainer-tools
repository in the right place, avoiding additional explanations and
steps.

The paragraphs were reordered and reworded a little bit so it follows
the flow "zero -> contributor -> committer -> maintainer".

Signed-off-by: Lucas De Marchi <lucas.demarchi at intel.com>
---
 getting-started.rst | 68 ++++++++++++++++++++++++++-------------------
 1 file changed, 39 insertions(+), 29 deletions(-)

diff --git a/getting-started.rst b/getting-started.rst
index 5d4ce9c..d6f66f1 100644
--- a/getting-started.rst
+++ b/getting-started.rst
@@ -4,54 +4,63 @@
  Getting Started
 =================
 
-For getting started grab the latest dim (drm-intel-maintainer) script from::
+For getting started grab use the latest dim (drm-intel-maintainer) script to
+setup your environment::
 
-    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dim
+    export DIM_PREFIX=/path/to/setup/the/project
+    cd $DIM_PREFIX
+    git clone https://gitlab.freedesktop.org/drm/maintainer-tools.git
+    ./maintainer-tools/dim setup
 
-There's also a sample config file for ~/.dimrc::
-
-    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
+Internally the script uses the :code:`DIM_PREFIX` environment variable to know
+where to setup all the repositories. You may want to set this in your
+:code:`$HOME/.dimrc`. A sample configuration file is available at
+https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample.
 
 Plus, there's bash completion in the same directory if you feel like using that.
-Run::
+For the commands below we assume the :code:`dim` script is in your
+:code:`$PATH`. Run::
 
     $ dim help
 
-for tons of details about how this thing works. Also see the git repository
-specific pages for details on the patch merging process for each tree. Adjust
-your .dimrc to match your setup and then run::
-
-    $ dim setup
+for tons of details about how this thing works. By cloning the maintainer-tools
+repository inside :code:`$DIM_PREFIX` like above you will keep it in sync
+together with all other repositories whenever you call::
 
-This will also check out the latest maintainer-tools branches, so please replace
-the dim you just downloaded with a symlink after this step. And by the way, if
-you have improvements for dim, see `contributing
-<dim.html#contributing-bug-reports-and-discussion>`_.
+    $ dim update-branches
 
 If you have a freedesktop.org account and plan to push things on one of the
 drm-xxx repos, you should use the ssh://git.freedesktop.org/git/drm-xxx urls
-when adding a remote. Note that dim will ask you to add missing remotes
-automatically, and by default uses the ssh:// url format. To make these urls
-without login names work, you should add a new entry in ~/.ssh/config, if that's
-not yet configured::
+when adding a remote. Note that during the setup process dim will ask you to
+add missing remotes automatically, and by default uses the ssh:// url format.
+To make these urls without login names work, you should add a new entry in
+~/.ssh/config, if that's not yet configured::
 
     $ printf '\nHost git.freedesktop.org\n\tUser <username>' >> ~/.ssh/config
 
 You should now have a main repository for patch application. The directory
-corresponding to this repository is defined by DIM_REPO in your .dimrc.
-You should also have directories called maintainer-tools, drm-tip (for
-rebuilding the tree), and drm-rerere for some dim-internal book-keeping.
+corresponding to this repository is defined by DIM_REPO in your .dimrc and
+default to :code:`src/`. You should also have directories called
+maintainer-tools, drm-tip (for rebuilding the tree), and drm-rerere for some
+dim-internal book-keeping. It's highly recommended that you also call::
+
+    $ dim create-workdir
+
 
-If someone else has pushed patches first resync using::
+.. note::
 
-   $ dim update-branches
+    The drm-tip directory is internal to dim. For development you should rather
+    use the DIM_REPO directory after calling the create-workdir command.
 
-Since dim supports lots of different branches in different repositories you
-first need to check out the right branch using::
+
+It will create separate work directories for each branch. During development
+you should use DIM_REPO and work on top of the drm-tip branch.
+
+To apply a patch on a specific you first need a up-to-date checkout::
 
    $ dim checkout <branch>
 
-Applying patches is done in the main repository with::
+Applying patches is done with::
 
     $ cat patch.mbox | dim apply-branch <branch>
 
@@ -72,6 +81,7 @@ can always use your every day tooling to get things done.
 For example, if a wrong patch was applied or you need to update commit message
 or fix anything else in the git repository, then just use git to do so
 as usual.
-
+ 
 Please subscribe to the https://lists.freedesktop.org/mailman/listinfo/dim-tools
-mailing list if you use dim.
+and if you have improvements for dim, see `contributing
+<dim.html#contributing-bug-reports-and-discussion>`_.
-- 
2.20.1