[PATCH 6/6] doc: getting started revamp

[Jani Nikula]

Be more helpful, reflect current status.

Signed-off-by: Jani Nikula <jani.nikula at intel.com>

---

The boundary between what's updated and what's old is a bit strong
still...
---
 getting-started.rst | 91 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 76 insertions(+), 15 deletions(-)

diff --git a/getting-started.rst b/getting-started.rst
index 5d4ce9c1991e..670aadf162df 100644
--- a/getting-started.rst
+++ b/getting-started.rst
@@ -4,29 +4,90 @@
  Getting Started
 =================
 
-For getting started grab the latest dim (drm-intel-maintainer) script from::
+Prerequisites
+-------------
 
-    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dim
+First, you'll need to decide where you store the repositories dim needs. We'll
+call this directory the ``DIM_PREFIX``. It may be an existing directory you use
+for sources, or a dedicated directory for dim use, for example ``$HOME/src`` or
+``$HOME/linux``.
 
-There's also a sample config file for ~/.dimrc::
+Your maintainer kernel repository [*]_ needs to be placed there too. We'll call
+this the ``DIM_REPO``. You can have dim create it as a fresh clone of Linus'
+upstream, or you can set it up yourself. It's recommended to keep your
+development repository separate, sandboxed if you will, from the maintainer
+repository.
 
-    https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
+``dim`` assumes the following directories are placed in ``DIM_PREFIX``:
 
-Plus, there's bash completion in the same directory if you feel like using that.
-Run::
+ * ``DIM_REPO``
+ * maintainer-tools
+ * drm-tip
+ * drm-rerere
 
-    $ dim help
+.. [*] Maintainer repository is used for brevity throughout; it should be
+       understood as either maintainer or committer repository.
 
-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::
+Installation
+------------
 
-    $ dim setup
+Create a dim configuration file ``$HOME/.dimrc`` and set it up according to your
+preferences, for example::
 
-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_PREFIX=$HOME/linux
+  DIM_REPO=$HOME/src
+
+See the `dimrc.sample`_ for details.
+
+.. _dimrc.sample: https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
+
+For the remainder of this text we'll assume the above variables are set, to make
+the text generic. You can actually do that by sourcing ``$HOME/.dimrc`` to your
+shell, or you can just replace the variables as you see them.
+
+Set up ``DIM_PREFIX``::
+
+  $ mkdir -p $DIM_PREFIX
+
+Clone maintainer-tools::
+
+  $ cd $DIM_PREFIX
+  $ git clone https://gitlab.freedesktop.org/drm/maintainer-tools.git
+
+You'll probably want to either add ``$DIM_PREFIX/maintainer-tools`` to ``PATH``,
+or, for example, add a link ``ln -s $DIM_PREFIX/maintainer-tools/dim
+$HOME/bin/dim`` assuming ``$HOME/bin`` is in ``PATH``.
+
+If you have an existing ``DIM_REPO`` you want to use, or want to set it up
+yourself, do that now. Or you can let dim clone Linus' upstream for you as the
+starting point, effectively::
+
+  $ cd $DIM_PREFIX
+  $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git $DIM_REPO
+
+Finish the setup, and have dim create drm-tip and drm-rerere, as well as
+``DIM_REPO``::
+
+  $ dim setup
+
+If you like, you can also set up bash completion for dim by adding something
+like this to your ``.bashrc``::
+
+  # dim completion
+  if [ -f $DIM_PREFIX/maintainer-tools/bash_completion ] && ! shopt -oq posix; then
+          . $DIM_PREFIX/maintainer-tools/bash_completion
+  fi
+
+Running dim without arguments will give you brief usage::
+
+  dim
+
+and the reference man page is available via::
+
+  dim help
+
+usage
+-----
 
 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
-- 
2.20.1