Move docs folder to man.

docs/src/depot_tools_tutorial.txt

Index: docs/src/depot_tools_tutorial.txt
diff --git a/docs/src/depot_tools_tutorial.txt b/docs/src/depot_tools_tutorial.txt
deleted file mode 100644
index 6c81e688269e14c6fde2b022ca8847db756f2bd0..0000000000000000000000000000000000000000
--- a/docs/src/depot_tools_tutorial.txt
+++ /dev/null
@@ -1,433 +0,0 @@
-depot_tools_tutorial(7)
-=======================
-
-NAME
-----
-depot_tools_tutorial - A tutorial introduction to the Chromium depot_tools git
-extensions.
-
-DESCRIPTION
------------
-
-The Chromium linkgit:depot_tools[7] suite contains many git workflow-enhancing
-tools which are designed to work together to enable anyone to wrangle the
-Chromium codebase expertly. This tutorial explains how to do development on
-Chromium using these tools. This will cover:
-
-* <<_setting_up,Setting up>>
-* <<_getting_the_code,Getting the code>>
-* <<_tl_dr,TL;DR>>
-* <<_creating_uploading_a_cl,Creating / Uploading a CL>>
-* <<_updating_the_code,Updating the code>>
-* <<_managing_multiple_cls,Managing multiple CLs>>
-* <<_managing_dependent_cls,Managing dependent CLs>>
-* <<_example_walkthrough,Example Walkthrough>>
-
-Please refer to the manpages (or `--help` output) for details about any of the
-commands mentioned in this tutorial.
-
-[NOTE]
-If your platform does not support manpages (or you prefer something a bit more
-expressive than plain text) you can find all documentation in 'html' form in the
-`[DEPOT_TOOLS]/docs/html` folder.
-
-PREREQUISITES
-~~~~~~~~~~~~~
-This tutorial assumes basic familiarity with git terminology and concepts. If you
-need to brush up on these, the following are very good resources:
-
-* link:http://think-like-a-git.net/[Think like (a) Git] - A lighthearted
-  overview of git. If you're sorta-familiar with git, but not 'comfortable' with
-  it, then give this a look.
-* link:http://gitimmersion.com/[Git Immersion Tutorial] - An in-depth git
-  tutorial.
-* link:http://pcottle.github.io/learnGitBranching[pcottle's Visual Git
-  Branching] - An excellent interactive/graphical demo on how git handles
-  commits, branches, and shows the operations git performs on them.
-* link:http://git-scm.com/book[Pro Git book] - ``The'' book for learning git
-  from basics to advanced concepts. A bit dry, but very through.
-
-If you've tried these out and are still having some trouble getting started,
-there are 'many' other resources online which should help. If you're 'really'
-**'really'** stuck, then chat up one of the Chromium infrastructure team
-members for some pointers.
-
-Litmus Test::
-  If you know what `git add`, `git status`, `git commit` do and you know
-  'essentially' what `git rebase` does, then you should know enough to follow
-  along.
-
-SETTING UP
-----------
-
-GET DEPOT TOOLS
-~~~~~~~~~~~~~~~
-
-ifdef::backend-xhtml11[]
-LINUX / MAC
-^^^^^^^^^^^
-endif::backend-xhtml11[]
-Clone the 'depot_tools' repository:
-
-[subs="quotes"]
-----
-[white]**$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools**
-----
-
-Add 'depot_tools' to the 'end' of your PATH and MANPATH (you will probably want
-to put this in your `~/.bashrc` or `~/.zshrc`). Assuming you cloned
-'depot_tools' to `/path/to/depot_tools`:
-
-[postsubs="quotes"]
-----
-[white]**$ export PATH=$PATH:/path/to/depot_tools**
-[white]**$ export MANPATH=$MANPATH:/path/to/depot_tools/docs**  <1>
-----
-<1> Observe that this path is +depot_tools/+**+docs+**.
-
-// No need to show the Windows stuff on the manpage output.
-ifdef::backend-xhtml11[]
-WINDOWS
-^^^^^^^
-Download the 'depot_tools'
-link:https://src.chromium.org/svn/trunk/tools/depot_tools.zip[bundle] and
-extract it somewhere.
-
-[WARNING]
-*DO NOT* use drag-n-drop or copy-n-paste extract from Explorer, this will not
-extract the hidden ``.git'' folder which is necessary for 'depot_tools' to
-autoupdate itself. You can use ``Extract all...'' from the context menu though.
-
-Add 'depot_tools' to the 'end' of your PATH. Assuming you unzipped the
-bundle to `C:\workspace\depot_tools`:
-
-With Administrator access: ::
-  *Control Panel -> System and Security -> System -> Advanced system settings*
-+
-Modify the PATH system variable to include `C:\workspace\depot_tools`.
-
-Without Administrator access: ::
-  *Control Panel -> User Accounts -> User Accounts -> Change my environment variables*
-+
-Add a PATH user variable: `%PATH%;C:\workspace\depot_tools`.
-
-From a `cmd.exe` shell, run the command `gclient` (without arguments). On first
-run, gclient will install all the Windows-specific bits needed to work with the
-code, including msysgit and python.
-
-[NOTE]
-=====
-* If you run gclient from a non-cmd shell (e.g., cygwin, PowerShell), it
-  may appear to run properly, but msysgit, python, and other tools may not get
-  installed correctly.
-* If you see strange errors with the file system on the first run of gclient,
-  you may want to link:http://tortoisesvn.tigris.org/faq.html#cantmove2[disable
-  Windows Indexing].
-* If you are running Windows XP and see errors like ``The system cannot execute
-  the specified program'', try installing the
-  link:http://code.google.com/p/chromium/issues/detail?id=75886[``Microsoft
-  Visual C++ 2008 Redistributable Package''].
-=====
-endif::backend-xhtml11[]
-
-BOOTSTRAPPING CONFIGURATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you have never used git before, you’ll need to set some global git
-configurations; substitute your name and email address in the following
-commands:
-
-[subs="quotes,attributes"]
-----
-[white]**$ git config --global user.name ``John Doe''**
-[white]**$ git config --global user.email ``jdoe@email.com''**
-[white]**$ git config --global core.autocrlf false**
-[white]**$ git config --global core.filemode false**
-[white]**$** # and for fun!
-[white]**$ git config --global color.ui true**
-----
-
-TL;DR
------
-[postsubs="quotes"]
-----
-[white]**$** # get the code
-[white]**$** # In an empty directory:
-[white]**$ fetch {chromium,blink,...}**
-
-[white]**$** # Update third_party repos and run pre-compile hooks
-[white]**$ gclient sync**
-
-[white]**$** # Make a new change and upload it for review
-[white]**$ git new-branch branchname**
-[white]**$** # repeat: [edit, git add, git commit]
-[white]**$ git cl upload**
-
-[white]**$** # After change is reviewed, commit with the CQ
-[white]**$ git cl set_commit**
-[white]**$** # Note that the committed hash which lands will /not/ match the
-[white]**$** # commit hashes of your local branch.
-----
-
-
-GETTING THE CODE
-----------------
-Pick an empty directory and run one of the following:
-
-[subs="quotes"]
-----
-[white]**$ fetch chromium**  # Basic checkout for desktop Chromium
-[white]**$ fetch blink**     # Chromium code with Blink checked out to tip-of-tree
-[white]**$ fetch android**   # Chromium checkout for Android platform
-[white]**$ fetch ios**       # Chromium checkout for iOS platform
-----
-
-When the `fetch` tool completes you should have the following in your working
-directory:
-
-[subs="quotes"]
-----
-[white]**.gclient**   # A configuration file for you source checkout
-[white]**src/**       # Top-level Chromium source checkout.
-----
-
-If you are on linux, then you'll need to run:
-
-[subs="specialcharacters,quotes"]
-----
-[white]**$ cd src && ./build/install-build-deps.sh**
-----
-
-And finally:
-
-[postsubs="quotes"]
-----
-[white]**$ gclient sync**
-----
-
-This will pull all dependencies of the Chromium src checkout. You will need
-to run this any time you update the main src checkout.
-
-
-CREATING / UPLOADING A CL
--------------------------
-NOTE: The remainder of the tutorial assumes that your current working directory
-is the `src/` folder mentioned in <<_getting_the_code,Getting the code>>.
-
-Each CL corresponds exactly with a single branch in git. Any time you want to
-begin a new CL, just:
-
-[subs="specialcharacters,quotes"]
-----
-[white]**$ git new-branch <branch_name>**
-----
-
-This will create and checkout a new branch named `branch_name` which will track
-the default upstream (which is `origin/master`). See linkgit:git-new-branch[1]
-for more features, such as the ability to track 'LKGR'.
-
-Commit as many changes as you like to this branch. When you want to upload it
-for review, run:
-
-[subs="quotes"]
-----
-[white]**$ git cl upload**
-----
-
-This will take the diff of your branch against its upstream (`origin/master`),
-and will post it to the link:https://codereview.chromium.org[Chromium code
-review site].
-
-
-UPDATING THE CODE
------------------
-Inevitably, you'll want to pull in changes from the main Chromium repo. This is
-pretty easy with 'depot_tools':
-
-[subs="quotes"]
-----
-[white]**$ git rebase-update**
-----
-
-This command will update all of your CLs to contain the latest code from their
-upstreams. It will also automatically clean up CLs which have been committed and
-a couple other nice things. See linkgit:git-rebase-update[1] for the full
-scoop.
-
-One thing to look out for are 'merge conflicts'. These happen for exactly the
-same as they do with SVN, but the experience is a little more controllable with
-git. `git rebase-update` will try to rebase all your branches for you, but if it
-encounters a merge conflict in one, it will halt and leave you in a rebase
-conflict state (see linkgit:git-rebase[1]). Resolving `git rebase` merge
-conflicts is beyond the scope of this tutorial, but there are many good sources
-online (see the <<_prerequisites,Prerequisites>> for some).
-
-Sometimes you're pretty certain that you've committed a certain branch, but `git
-rebase-update` isn't able to tell that for sure. This is usually because your
-branch doesn't rebase cleanly. You could just delete the branch with `git branch
--D <branch>`, but you'd like to double check the diff of your branch against its
-upstream before deleting it. If this is the case you can abort the rebase
-started by `git rebase-update`, and then run linkgit:git-squash-branch[1] to
-flatten your branch into a single commit. When you run `git rebase-update`
-again, you'll get a (hopefully) much smaller / saner diff. If it turns out you
-were wrong about your branch being fully committed, you can use
-linkgit:git-reflog[1] to reset your branch back to where it was before. If the
-diff looks inconsequential, you can use `git rebase --skip` to ignore it, and
-then `git rebase-update` will clean it up for you.
-
-Once you're done resolving all of the merge conflict, just run `git
-rebase-update`, and it will pick up where it left off. Once the command has
-finished updating all of your branches, it will return you back to the branch
-you started on.
-
-[NOTE]
-Running `git rebase-update` will update all your branches, but it will not
-automatically run `gclient sync` to update your dependencies.
-
-
-MANAGING MULTIPLE CLS
----------------------
-Sometimes you want to work on more than one CL at once (say, you have a CL
-posted for review and want to work on something else). For each CL that you
-want to work on, just use `git new-branch <branchname>`.
-
-Once you start to have more than one CL at a time, it can be easy to lose your
-bearings. Fortunately, 'depot_tools' has two tools to help you out:
-
-[subs="specialcharacters,quotes,attributes"]
-----
-[white]**$ git map**
-[white blue-background]##*##{zwsp}[blue-background red]** 7dcfe47       ** [green]##(##{zwsp}[aqua]**frozen_changes**{zwsp}[green]##)## [yellow]##2014-03-12## \~ FREEZE.unindexed
-* [red]**4b0c180**        [yellow]##2014-03-12## \~ modfile
-* [red]**59a7cca**        [yellow]##2014-03-12## \~ a deleted file
-* [red]**6bec695**        [green]##(##{zwsp}[red]##origin/master##{zwsp}[green]##)## [yellow]##2014-03-11## \~ Add neat feature    [white]**<(frozen_changes)**
-* [red]**d15a38a**        [yellow]##2014-03-11## \~ Epic README update
-* [red]**d559894**        [green]##(##{zwsp}[lime]**master**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Important upstream change
-[red]##|## * [red]**9c311fd**      [green]##(##{zwsp}[lime]**cool_feature**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Respond to CL comments
-[red]##|## [green]##|## * [red]**2a1eeb2**    [green]##(##{zwsp}[lime]**subfeature**{zwsp}[green]##)## [yellow]##2014-03-11## \~ integrate with CoolService
-[red]##|## [green]##|## * [red]**d777af6**    [yellow]##2014-03-11## \~ slick commenting action
-[red]##|## [green]##|/##
-[red]##|## * [red]**265803a**      [yellow]##2014-03-11## \~ another improvement    [white]**<(subfeature)**
-[red]##|## * [red]**6d831ac**      [green]##(##{zwsp}[fuchsia]**spleen_tag**{zwsp}[green]##)## [yellow]##2014-03-11## \~ Refactor spleen
-[red]##|## * [red]**82e74ab**      [yellow]##2014-03-11## \~ Add widget
-[red]##|/##
-* [red]**d08c5b3**        [green]##(##{zwsp}[lime]**bogus_noparent**{zwsp}[green]##)## [yellow]##2014-03-11## ~ Wonderful beginnings    [white]**<(cool_feature)**
-----
-Note that this example repo is in dire need of a linkgit:git-rebase-update[1]!
-
-[subs="quotes"]
-----
-[white]**$ git map-branches**
-[red]#origin/master#
-  [green]#cool_feature#
-    [green]#subfeature#
-  [aqua]#frozen_changes *#
-  [green]#master#
-----
-
-linkgit:git-map[1]::
-  This tool shows you the history of all of your branches in a pseudo-graphical
-  format. In particular, it will show you which commits all of your branches
-  are on, which commit you currently have checked out, and more. Check out the
-  doc for the full details.
-
-linkgit:git-map-branches[1]::
-  This tool just shows you which branches you have in your repo, and thier
-  upstream relationship to each other (as well as which branch you have checked
-  out at the moment).
-
-Additionally, sometimes you need to switch between branches, but you've got work
-in progress. You could use linkgit:git-stash[1], but that can be tricky to
-manage because you need to remember which branches you stashed what changes on.
-Helpfully 'depot_tools' includes two tools which can greatly assist in case:
-
-linkgit:git-freeze[1] allows you to put the current branch in \'suspended
-animation' by committing your changes to a specially-named commit on the top of
-your current branch. When you come back to your branch later, you can just run
-linkgit:git-thaw[1] to get your work-in-progress changes back to what they were.
-
-Another useful tool is linkgit:git-rename-branch[1]. Unlike `git branch -m <old>
-<new>`, this tool will correctly preserve the upstream relationships of your
-branch compared to its downstreams.
-
-Finally, take a look at linkgit:git-upstream-diff[1]. This will show you the
-combined diff for all the commits on your branch against the upstream tracking
-branch. This is 'exactly' what `git cl upload` will push up to code review.
-Additionally, consider trying the `--wordwise` argument to get a colorized
-per-word diff (instead of a per-line diff).
-
-MANAGING DEPENDENT CLS
-----------------------
-Now that you know how to manage 'independent' CLs, we'll see how to manage
-'dependent' CLs. Dependent CLs are useful when your second (or third or fourth
-or ...) CL depends on the changes in one of your other CLs (such as: CL 2 won't
-compile without CL 1, but you want to submit them as two separate reviews).
-
-Like all of the other CLs we've created, we use linkgit:git-new-branch[1], but
-this time with an extra argument. First, `git checkout` the branch
-you want to base the new one on (i.e. CL 1), and then run:
-
-[subs="specialcharacters,quotes"]
-----
-[white]**$ git new-branch --upstream_current <branch_name>**
-----
-
-This will make a new branch which tracks the 'current' branch as its upstream
-(as opposed to 'origin/master'). All changes you commit to this branch will be
-in addition to the previous branch, but when you `git cl upload`, you will only
-upload the diff for the dependent (child) branch. You may have as many branches
-nested in this fashion as you like.
-
-linkgit:git-map[1] and linkgit:git-map-branches[1] are particularly helpful when
-you have dependent branches. In addition, there are two helper commands which
-let you traverse your working copy up and down this tree of branches:
-linkgit:git-nav-upstream[1] and linkgit:git-nav-downstream[1].
-
-Sometimes when dealing with dependent CLs, it turns out that you accidentally
-based a branch on the wrong upstream, but since then you've committed changes to
-it, or even based 'another' branch off of that one. Or you discover that you
-have two independent CLs that would actually be much better off as dependent
-CLs. In instances like these, you can check out the offending branch and use
-linkgit:git-reparent-branch[1] to move it to track a different parent. Note that
-this can also be used to move a branch from tracking `origin/master` to `lkgr`
-or vice versa.
-
-
-EXAMPLE WALKTHROUGH
--------------------
-This section will demo what a typical workflow looks like when writing,
-updating, and committing multiple CLs.
-
-demo:walkthrough[]
-
-So there you have the basic flow. Note that you don't 'have' to do chromium
-development using these tools. Any git workflow is compatible, as long as
-`git cl upload` is able to upload good patches.
-
-
-CONCLUSION
-----------
-Hopefully that gives you a good starting overview on Chromium development using
-'depot_tools'. If you have questions which weren't answered by this tutorial or
-the man pages for the tools (see the index of all tools here:
-linkgit:depot_tools[7]), please feel free to ask.
-
-
-GLOSSARY
---------
-
-CL::
-  A 'change-list'. This is a diff which you would like to commit to the
-  codebase.
-
-DEPS::
-  A file in the chromium checkout which `gclient sync` uses to determine what
-  dependencies to pull in. This file also contains 'hooks'.
-
-LKGR::
-  Last Known Good Revision. This is a linkgit:git-tag[1] which tracks the last
-  version of `origin/master` which has passed the full set of testing on the
-  link:http://build.chromium.org[main Chromium waterfall].
-
-include::_footer.txt[]
-
-// vim: ft=asciidoc: