[PATCH] vcs_info docs: Document patch-format and more

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Patch that adds all styles/hooks used by vcs_info to its documentation.

Two notes about this patch:

1. I didn't actually document all of them, for some I only added
placeholders.  I think that would be better than not documenting them at
all, but obviously it would be nice if the documentation were actually
written.  I don't use most of that myself (e.g., I don't use the quilt
support at all), so I think the docs would be better if someone who
actually uses the features documented them — for example, because they
would be better placed to notice edge case bugs, instead of documenting
them as features.

2. The endsitem()/startitem() hack is because otherwise the man page
version rendered badly.  It seems to render ok everywhere I check, but
it's inelegant.  Maybe the list should be converted entirely from sitem
to item?  I amn't familiar with the yodl stuff enough to say.

Daniel

P.S. All patches I sent today should be mutually non-conflicting, though
some of them touch the same files as each other so offsets are expected
(but no fuzz).

From db87641b8a526534235d9c19a9ef4ac9c6828f36 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>
Date: Sat, 24 Jan 2015 10:30:49 +0000
Subject: [PATCH] vcs_info docs: Document patch-format and more

---
 Doc/Zsh/contrib.yo | 46 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 00ede52..c625cbd 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -944,6 +944,20 @@ item(tt(hooks))(
 A list style that defines hook-function names. See bf(Hooks in vcs_info)
 below for details.
 )
+kindex(patch-format)
+kindex(nopatch-format)
+xitem(tt(patch-format))
+item(tt(nopatch-format))(
+This pair of styles format the patch information used by the tt(%m) expando in
+formats and actionformats for the tt(git) and tt(hg) backends.  The value is
+subject to certain tt(%)-expansions described below.
+)
+kindex(get-unapplied)
+item(tt(get-unapplied))(
+TODO: undocumented.
+
+Used by the tt(quilt) and tt(hg) backends.
+)
 enditem()
 
 The default values for these styles in all contexts are:
@@ -975,6 +989,9 @@ sitem(tt(use-quilt))(false)
 sitem(tt(quilt-standalone))(false)
 sitem(tt(quilt-patch-dir))(empty - use tt($QUILT_PATCHES))
 sitem(tt(quiltcommand))(quilt)
+sitem(tt(patch-format))(var(backend dependent))
+sitem(tt(nopatch-format))(var(backend dependent))
+sitem(tt(get-unapplied))(false)
 endsitem()
 
 In normal tt(formats) and tt(actionformats) the following replacements are
@@ -996,11 +1013,26 @@ sitem(tt(%r))(The repository name. If tt(%R) is tt(/foo/bar/repoXY), tt(%r)
 is tt(repoXY).)
 sitem(tt(%S))(A subdirectory within a repository. If tt($PWD) is
 tt(/foo/bar/repoXY/beer/tasty), tt(%S) is tt(beer/tasty).)
-sitem(tt(%m))(A "misc" replacement. It is at the discretion of the backend to
-decide what this replacement expands to. It is currently used by the tt(hg)
-and tt(git) backends to display patch information from the tt(mq) and
-tt(stgit) extensions.)
 endsitem()
+startitem()
+item(tt(%m))(
+A "misc" replacement. It is at the discretion of the backend to
+decide what this replacement expands to.
+
+The tt(hg) and tt(git) backends use this expando to display patch information.
+tt(hg) sources patch information from the tt(mq) extensions; tt(git) from the
+tt(rebase) command and from the and tt(stgit) extension.  The tt(patch-format)
+and tt(nopatch-format) styles control the generated string.  The former is used
+when at least one patch from the patch queue has been applied, and the latter
+otherwise.
+
+The tt(hg) backend displays bookmark information in this expando (in addition
+to tt(mq) information).  See the tt(get-mq) and tt(get-bookmarks) styles.  Both
+of these styles may be enabled at the same time.  If both are enabled, both
+resulting strings will be shown separated by a semicolon (that cannot currently
+be customized).
+)
+enditem()
 
 In tt(branchformat) these replacements are done:
 
@@ -1377,6 +1409,12 @@ If tt(ret) is set to non-zero, the string in
 tt(${hook_com[rev-replace]}) will be used unchanged as the
 `tt(%i)' replacement in the variables set by tt(vcs_info).
 )
+item(tt(pre-addon-quilt))(
+TODO: undocumented
+)
+item(tt(set-patch-format))(
+TODO: undocumented
+)
 item(tt(set-message))(
 Called each time before a `tt(vcs_info_msg_N_)' message is set.
 It takes two arguments; the first being the `N' in the message
-- 
1.9.1