[PATCH] doc: extract getting started document from dim man page
Jani Nikula
jani.nikula at intel.com
Thu Apr 26 13:05:46 UTC 2018
Keep the dim man page more of a reference. The getting started document
should be more accessible without dim installed anyway. Only do the bare
minimum changes for now.
Signed-off-by: Jani Nikula <jani.nikula at intel.com>
---
dim.rst | 82 +++++------------------------------------------------
drm-misc.rst | 3 +-
getting-started.rst | 75 ++++++++++++++++++++++++++++++++++++++++++++++++
index.rst | 1 +
4 files changed, 84 insertions(+), 77 deletions(-)
create mode 100644 getting-started.rst
diff --git a/dim.rst b/dim.rst
index 9793bde1416c..f7ca4ebdf0eb 100644
--- a/dim.rst
+++ b/dim.rst
@@ -23,86 +23,18 @@ SYNOPSIS
DESCRIPTION
===========
-drm maintainer script.
+**dim** is the Linux kernel drm subsystem maintainer script, used to maintain
+the drm-intel_ and drm-misc_ git repositories.
-Used to maintain drm-intel_ and drm-misc_ git repositories.
+This man page is a command-line reference for the tool only; for more
+comprehensive documentation, including a getting started guide, see
+https://01.org/linuxgraphics/gfx-docs/maintainer-tools/index.html, or the same
+in source form in the maintainer-tools branch of the drm-tip repository at
+https://cgit.freedesktop.org/drm/drm-tip/log/?h=maintainer-tools.
.. _drm-intel: drm-intel.html
.. _drm-misc: drm-misc.html
-QUICKSTART
-==========
-
-For getting started grab the latest dim (drm-intel-maintainer) script from::
-
- http://cgit.freedesktop.org/drm-tip/tree/dim?h=maintainer-tools
-
-There's also a sample config file for ~/.dimrc::
-
- http://cgit.freedesktop.org/drm-tip/tree/dimrc.sample?h=maintainer-tools
-
-Plus, there's bash completion in the same directory if you feel like using that.
-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
-
-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, BUG REPORTS AND DISCUSSION`_
-below.
-
-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 and, if it's not already done, you should add a new entry in
-~/.ssh/config::
-
- $ 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.
-
-If someone else has pushed patches first resync using::
-
- $ dim update-branches
-
-Since dim supports lots of different branches in different repositories you
-first need to check out the right branch using::
-
- $ dim checkout <branch>
-
-Applying patches is done in the main repository with::
-
- $ cat patch.mbox | dim apply-branch <branch>
-
-This works like a glorified version of git apply-mbox and does basic patch
-checking and adds stuff like patchwork links of the merged patch. It is
-preferred to use the patch email file instead of the original patch file since
-it contains some interesting headers like the message ID. When you're happy
-(remember that with a shared tree any mistake is permanent and there's no
-rebasing) push out the new tree with::
-
- $ dim push-branch <branch>
-
-This will also rebuild a new drm-tip integration tree. For historical reasons
-there's shortcut for the drm-intel specific branches for most of these commands.
-
-Please note that if there is no specific command available from dim then you
-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.
-
OPTIONS
=======
diff --git a/drm-misc.rst b/drm-misc.rst
index 187a4df07ad4..a884e023048e 100644
--- a/drm-misc.rst
+++ b/drm-misc.rst
@@ -25,8 +25,7 @@ Getting Started
First you need a `freedesktop.org account with the drm-misc group permission
<https://www.freedesktop.org/wiki/AccountRequests/>`_. Then you need to setup the
-branches and tooling, see the `getting started with dim <dim.html#quickstart>`_
-guide.
+branches and tooling, see :ref:`getting-started`.
Branches
========
diff --git a/getting-started.rst b/getting-started.rst
new file mode 100644
index 000000000000..10c3a1125e4d
--- /dev/null
+++ b/getting-started.rst
@@ -0,0 +1,75 @@
+.. _getting-started:
+
+=================
+ Getting Started
+=================
+
+For getting started grab the latest dim (drm-intel-maintainer) script from::
+
+ http://cgit.freedesktop.org/drm-tip/tree/dim?h=maintainer-tools
+
+There's also a sample config file for ~/.dimrc::
+
+ http://cgit.freedesktop.org/drm-tip/tree/dimrc.sample?h=maintainer-tools
+
+Plus, there's bash completion in the same directory if you feel like using that.
+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
+
+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>`_.
+
+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 and, if it's not already done, you should add a new entry in
+~/.ssh/config::
+
+ $ 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.
+
+If someone else has pushed patches first resync using::
+
+ $ dim update-branches
+
+Since dim supports lots of different branches in different repositories you
+first need to check out the right branch using::
+
+ $ dim checkout <branch>
+
+Applying patches is done in the main repository with::
+
+ $ cat patch.mbox | dim apply-branch <branch>
+
+This works like a glorified version of git apply-mbox and does basic patch
+checking and adds stuff like patchwork links of the merged patch. It is
+preferred to use the patch email file instead of the original patch file since
+it contains some interesting headers like the message ID. When you're happy
+(remember that with a shared tree any mistake is permanent and there's no
+rebasing) push out the new tree with::
+
+ $ dim push-branch <branch>
+
+This will also rebuild a new drm-tip integration tree. For historical reasons
+there's shortcut for the drm-intel specific branches for most of these commands.
+
+Please note that if there is no specific command available from dim then you
+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.
diff --git a/index.rst b/index.rst
index d2142a7898f8..3afece2ba817 100644
--- a/index.rst
+++ b/index.rst
@@ -25,6 +25,7 @@ Contents:
repositories
drm-misc
drm-intel
+ getting-started
dim
qf
TODO
--
2.11.0
More information about the dim-tools
mailing list