Add documentation for git-map-branches, git-map, git-nav-downstream,

Add documentation for git-map-branches, git-map, git-nav-downstream,
git-nav-upstream, as well as introduce a generic 'depot_tools' manpage with a
listing of the other tools.

This change also fully colorizes the EXAMPLE sections for the git-* commands to
reflect their actual appearance on the console (html only, manpage has bolding
hints).

R=agable@chromium.org, szager@chromium.org
BUG=261738
Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=259338

[iannucci, 2014-03-14 21:56:42]

PTAL

[agable, 2014-03-18 02:00:27]

Why are html docs inside /git_docs/htmlout (despite also including depot_tools),
while the man pages are in /man1. I'd put the man pages inside /git_docs as
well.

https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-map-branch...
File git_docs/_git-map-branches_desc.helper.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-map-branch...
git_docs/_git-map-branches_desc.helper.txt:4: // vim: ft=asciidoc noexpandtab:
Some of these have vim hints, but not all. Be consistent.

https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-thaw_desc....
File git_docs/_git-thaw_desc.helper.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-thaw_desc....
git_docs/_git-thaw_desc.helper.txt:2: 
Blank line.

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
File git_docs/git-map-branches.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
git_docs/git-map-branches.txt:19: * Current branch is [aqua]#cyan#.
heliotrope

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
git_docs/git-map-branches.txt:26: should be assigned a parent by checking out
the branch and running git branch
80 chars

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt
File git_docs/git-map.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt#new...
git_docs/git-map.txt:31: Extra parameters to pass to the internal
linkgit:git-log[1] invocation. This
80 chars

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt#new...
git_docs/git-map.txt:43: ~~~~~~~~~~~~~~~~~~~~~
tilde underline?

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-downstr...
File git_docs/git-nav-downstream.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-downstr...
git_docs/git-nav-downstream.txt:19: the command will check that out. If there\'s
more than one downstream branch, the
80 chars

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-upstrea...
File git_docs/git-nav-upstream.txt (right):

https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-upstrea...
git_docs/git-nav-upstream.txt:17: 'git-nav-upstream' takes the current branch,
finds it\'s upstream branch, and
its

[iannucci, 2014-03-18 07:31:30]

On 2014/03/18 02:00:27, agable wrote:
> Why are html docs inside /git_docs/htmlout (despite also including
depot_tools),
> while the man pages are in /man1. I'd put the man pages inside /git_docs as
> well.
> 

[Will respond to the rest later]

git_docs should be renamed. I'd prefer to do it in another CL.

htmlout is just because I have no better place to put them at the moment.

man1 is so that you can add depot_tools to MANPATH. Otherwise you'd have to add
depot_tools/git_docs to MANPATH, which would be pretty weird/hard to remember.

Maybe if git_docs -> documentation, then documentation/manX/* would make sense,
but even so, it would be an extra thing to remember when 'adding depot_tools to
the path'.

>
https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-map-branch...
> File git_docs/_git-map-branches_desc.helper.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-map-branch...
> git_docs/_git-map-branches_desc.helper.txt:4: // vim: ft=asciidoc noexpandtab:
> Some of these have vim hints, but not all. Be consistent.
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-thaw_desc....
> File git_docs/_git-thaw_desc.helper.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/_git-thaw_desc....
> git_docs/_git-thaw_desc.helper.txt:2: 
> Blank line.
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
> File git_docs/git-map-branches.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
> git_docs/git-map-branches.txt:19: * Current branch is [aqua]#cyan#.
> heliotrope
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map-branche...
> git_docs/git-map-branches.txt:26: should be assigned a parent by checking out
> the branch and running git branch
> 80 chars
> 
> https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt
> File git_docs/git-map.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt#new...
> git_docs/git-map.txt:31: Extra parameters to pass to the internal
> linkgit:git-log[1] invocation. This
> 80 chars
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt#new...
> git_docs/git-map.txt:43: ~~~~~~~~~~~~~~~~~~~~~
> tilde underline?
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-downstr...
> File git_docs/git-nav-downstream.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-downstr...
> git_docs/git-nav-downstream.txt:19: the command will check that out. If
there\'s
> more than one downstream branch, the
> 80 chars
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-upstrea...
> File git_docs/git-nav-upstream.txt (right):
> 
>
https://codereview.chromium.org/200903002/diff/20001/git_docs/git-nav-upstrea...
> git_docs/git-nav-upstream.txt:17: 'git-nav-upstream' takes the current branch,
> finds it\'s upstream branch, and
> its

[agable, 2014-03-18 15:28:38]

I think "add depot_tools to path and depot_tools/documentation to manpath"
is completely reasonable, and we should keep docs (especially autogenerated
docs) out of the top level of the repo.
On Mar 18, 2014 12:31 AM, <iannucci@chromium.org> wrote:

> On 2014/03/18 02:00:27, agable wrote:
>
>> Why are html docs inside /git_docs/htmlout (despite also including
>>
> depot_tools),
>
>> while the man pages are in /man1. I'd put the man pages inside /git_docs
>> as
>> well.
>>
>
>
> [Will respond to the rest later]
>
> git_docs should be renamed. I'd prefer to do it in another CL.
>
> htmlout is just because I have no better place to put them at the moment.
>
> man1 is so that you can add depot_tools to MANPATH. Otherwise you'd have
> to add
> depot_tools/git_docs to MANPATH, which would be pretty weird/hard to
> remember.
>
> Maybe if git_docs -> documentation, then documentation/manX/* would make
> sense,
> but even so, it would be an extra thing to remember when 'adding
> depot_tools to
> the path'.
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/_git-map-branches_desc.helper.txt
>
>> File git_docs/_git-map-branches_desc.helper.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/_git-map-branches_desc.helper.txt#newcode4
>
>> git_docs/_git-map-branches_desc.helper.txt:4: // vim: ft=asciidoc
>> noexpandtab:
>> Some of these have vim hints, but not all. Be consistent.
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/_git-thaw_desc.helper.txt
>
>> File git_docs/_git-thaw_desc.helper.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/_git-thaw_desc.helper.txt#newcode2
>
>> git_docs/_git-thaw_desc.helper.txt:2:
>> Blank line.
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-map-branches.txt
>
>> File git_docs/git-map-branches.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-map-branches.txt#newcode19
>
>> git_docs/git-map-branches.txt:19: * Current branch is [aqua]#cyan#.
>> heliotrope
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-map-branches.txt#newcode26
>
>> git_docs/git-map-branches.txt:26: should be assigned a parent by
>> checking out
>> the branch and running git branch
>> 80 chars
>>
>
>  https://codereview.chromium.org/200903002/diff/20001/git_docs/git-map.txt
>> File git_docs/git-map.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-map.txt#newcode31
>
>> git_docs/git-map.txt:31: Extra parameters to pass to the internal
>> linkgit:git-log[1] invocation. This
>> 80 chars
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-map.txt#newcode43
>
>> git_docs/git-map.txt:43: ~~~~~~~~~~~~~~~~~~~~~
>> tilde underline?
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-nav-downstream.txt
>
>> File git_docs/git-nav-downstream.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-nav-downstream.txt#newcode19
>
>> git_docs/git-nav-downstream.txt:19: the command will check that out. If
>>
> there\'s
>
>> more than one downstream branch, the
>> 80 chars
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-nav-upstream.txt
>
>> File git_docs/git-nav-upstream.txt (right):
>>
>
>
> https://codereview.chromium.org/200903002/diff/20001/git_
> docs/git-nav-upstream.txt#newcode17
>
>> git_docs/git-nav-upstream.txt:17: 'git-nav-upstream' takes the current
>> branch,
>> finds it\'s upstream branch, and
>> its
>>
>
>
>
> https://codereview.chromium.org/200903002/
>

To unsubscribe from this group and stop receiving emails from it, send an email
to chromium-reviews+unsubscribe@chromium.org.

[iannucci, 2014-03-22 20:02:51]

Renamed. New hierarchy is
  * docs/src      -- source of docs + tools
  * docs/manX  -- manpages
  * docs/html    -- rendered html

Now you'd add depot_tools/docs to manpath.

[iannucci, 2014-03-22 20:03:09]

Also: can i haz lgtm pls? :D

[agable, 2014-03-25 17:38:12]

On 2014/03/22 20:03:09, iannucci wrote:
> Also: can i haz lgtm pls? :D

Rietveld is still showing modified files in /git_docs/blah and /man1. I assume
that's just rietveld being dumb? LGTM anyway.

[iannucci, 2014-03-25 21:27:20]

The CQ bit was checked by iannucci@chromium.org

[commit-bot: I haz the power, 2014-03-25 21:27:21]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/iannucci@chromium.org/200903002/70001

[iannucci, 2014-03-25 21:28:12]

On 2014/03/25 17:38:12, agable wrote:
> On 2014/03/22 20:03:09, iannucci wrote:
> > Also: can i haz lgtm pls? :D
> 
> Rietveld is still showing modified files in /git_docs/blah and /man1. I assume
> that's just rietveld being dumb? LGTM anyway.

(yes, that's just Rietveld being dumb)

[commit-bot: I haz the power, 2014-03-25 21:30:38]

Change committed as 259338