Re* [PATCH 4/4] Add documentation for ref namespaces

Ævar Arnfjörð Bjarmason [off-list ref] writes:

On Tue, Jun 7, 2011 at 20:21, Jamey Sharp [off-list ref] wrote:

quoted

Document the namespace mechanism in a new gitnamespaces(7) page.
Reference it from receive-pack and upload-pack.

This breaks the build on older asciidoc versions, the fix is to do
what I did in f5008f56d5aba06598e1c6272f4f55b4ee4bb016.

Earlier I sent out a tongue-in-cheek "like this" that had a completely
bogus SYNOPSIS section that is unusable in a released version of Git,
hoping that somebody who _care_ more about the feature that the page
describes would give us a better wording, but unfortunately it never
happened.

So here is a more realistic replacement, so that we won't have to suffer
by complaints from people with older AsciiDoc saying "the release does not
build". If we were to include this in 1.7.7 final, we now need to make
sure we won't to have to hear from people with newer AsciiDoc saying "why
do we have nonsense in SYNOPSIS section", so your help is needed here.

I explicitly avoided saying:

	[verse]
	export GIT_NAMESPACE=<namespace>

as nothing other than the selected transports seems to pay attention to
this environment variable.

-- >8 --
Subject: [PATCH] Documentation/gitnamespaces.txt: cater to older asciidoc

Older asciidoc (e.g. 8.2.5 on Centos 5.5) is unhappy if a manpage does not
have a SYNOPSIS section. Show a sample (and a possibly bogus) command line
of running two commands that pay attention to this environment variable
with a customized value.

Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/gitnamespaces.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt
index ed8924e..c6713cf 100644
--- a/Documentation/gitnamespaces.txt
+++ b/Documentation/gitnamespaces.txt

@@ -5,6 +5,13 @@ NAME
 ----
 gitnamespaces - Git namespaces
 
+SYNOPSIS
+--------
+[verse]
+GIT_NAMESPACE=<namespace> 'git upload-pack'
+GIT_NAMESPACE=<namespace> 'git receive-pack'
+
+
 DESCRIPTION
 -----------
 

-- 
1.7.7.rc1.3.g559357

On Thu, Sep 15, 2011 at 05:22:29PM -0700, Junio C Hamano wrote:

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

On Tue, Jun 7, 2011 at 20:21, Jamey Sharp [off-list ref] wrote:

quoted

Document the namespace mechanism in a new gitnamespaces(7) page.
Reference it from receive-pack and upload-pack.

This breaks the build on older asciidoc versions, the fix is to do
what I did in f5008f56d5aba06598e1c6272f4f55b4ee4bb016.

Earlier I sent out a tongue-in-cheek "like this" that had a completely
bogus SYNOPSIS section that is unusable in a released version of Git,
hoping that somebody who _care_ more about the feature that the page
describes would give us a better wording, but unfortunately it never
happened.

I'm afraid your wit was too subtle for me, as I believed your proposal
was serious and would be applied as-is. I assumed AsciiDoc was going to
magically omit the bogus synopsis, somehow. Perhaps it should detect
when people are making fun of it, and ignore them then?

Your rationale for giving a more specific synopsis is sound, although:
1) git http-backend also supports the environment variable because it's
inherited by the underlying upload-pack and receive-pack; and 2) the
environment variable is an alternative to a general git command-line
option. How much detail do you want in a synopsis?

Assuming that you're happy with this level of detail, and that the
AsciiDoc syntax is correct (I'm not familiar enough with it), I'm happy
with the patch you propose---

Reviewed-by: Jamey Sharp <redacted>