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

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

[Daniel Shahaf]

[-- Attachment #1: Type: text/plain, Size: 1057 bytes --]

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).

[-- Attachment #2: 0001-vcs_info-docs-Document-patch-format-and-add-stubs-fo.patch --]
[-- Type: text/x-patch, Size: 3432 bytes --]

>From db87641b8a526534235d9c19a9ef4ac9c6828f36 Mon Sep 17 00:00:00 2001
From: Daniel Shahaf <d.s@daniel.shahaf.name>
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

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

[Frank Terbeck]

Hey,

Daniel Shahaf wrote:
> 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.

I'll hold off on this, basically because I don't know what the general
consensus about "TODO"s is in zsh reference documentation. Maybe I'll
fill in the blanks sometime tomorrow. Then it won't matter.


Regards, Frank

[PATCH] vcs_info: Documentation update

[Frank Terbeck]

From: Daniel Shahaf <d.s@daniel.shahaf.name>

This adds documentation for more hooks and styles available in
vcs_info:

  - patch-format
  - nopatch-format
  - get-unapplied
  - pre-addon-quilt
  - set-patch-format
---
 Doc/Zsh/contrib.yo | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 4 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 80a7997..120efa2 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -948,6 +948,21 @@ 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))(
+This boolean style controls whether a backend should attempt to gather a list
+of unapplied patches (for example with Mercurial Queue patches).
+
+Used by the tt(quilt) and tt(hg) backends.
+)
 enditem()
 
 The default values for these styles in all contexts are:
@@ -979,6 +994,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
@@ -1000,11 +1018,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:
 
@@ -1384,6 +1417,30 @@ 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))(
+This hook is used when tt(vcs_info)'s quilt functionality is active in "addon"
+mode (quilt used on top of a real version control system). It is activated
+right before any quilt specific action is taken.
+
+Setting the `tt(ret)' variable in this hook to a non-zero value avoids the
+quilt specific to be run at all.
+)
+item(tt(set-patch-format))(
+This hook is used to control some of the possible expansions in
+tt(patch-format) and tt(nopatch-format) styles with patch queue systems such as
+quilt, mqueue and the like.
+
+This hook is used in the tt(git), tt(hg) and tt(quilt) backends.
+
+The hook allows the control of the tt(%p) (tt(${hook_com[applied]})) and tt(%u)
+(tt(${hook_com[unapplied]})) expansion in all backends that use the hook. With
+the mercurial backend, the tt(%g) (tt(${hook_com[guards]})) expansion is
+controllable in addition to that.
+
+If tt(ret) is set to non-zero, the string in tt(${hook_com[patch-replace]})
+will be used unchanged instead of an expanded format from tt(patch-format) or
+tt(nopatch-format).
+)
 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
-- 
2.1.4

Re: [PATCH] vcs_info: Documentation update

[Daniel Shahaf]

Frank Terbeck wrote on Sun, Jan 25, 2015 at 15:20:49 +0100:
> +item(tt(pre-addon-quilt))(
> +This hook is used when tt(vcs_info)'s quilt functionality is active in "addon"
> +mode (quilt used on top of a real version control system). It is activated
> +right before any quilt specific action is taken.
> +
> +Setting the `tt(ret)' variable in this hook to a non-zero value avoids the
> +quilt specific to be run at all.

Is a word missing here?
"quilt specific" → "quilt-specific action"

> From: Daniel Shahaf <d.s@daniel.shahaf.name>
> 
> This adds documentation for more hooks and styles available in
> vcs_info:
> 
>   - patch-format
>   - nopatch-format
>   - get-unapplied
>   - pre-addon-quilt
>   - set-patch-format
> ---

Thanks for finishing what I'd started, and for applying my patches so swiftly!

Daniel

P.S. Regarding the "TODO placeholders in documentation" issue: I didn't
intend to suggest using using the manual as a todo list.  I was only saying
that if we don't document the semantics of something, then documenting its
existence is better than not documenting it at all.  Sorry for not making
myself clear.

[PATCH] vcs_info documentation: Fix wording

[Frank Terbeck]

As suggested by Daniel Shahaf.
---
 Doc/Zsh/contrib.yo | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 120efa2..4f6c437 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -1422,8 +1422,8 @@ This hook is used when tt(vcs_info)'s quilt functionality is active in "addon"
 mode (quilt used on top of a real version control system). It is activated
 right before any quilt specific action is taken.
 
-Setting the `tt(ret)' variable in this hook to a non-zero value avoids the
-quilt specific to be run at all.
+Setting the `tt(ret)' variable in this hook to a non-zero value avoids any
+quilt specific actions from being run at all.
 )
 item(tt(set-patch-format))(
 This hook is used to control some of the possible expansions in
-- 
2.1.4