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

From: Jamey Sharp <jamey@minilop.net>
Date: Sep 16, 2011, 03:40 UTC
Message-ID: <20110916034051.GH3144@oh.minilop.net>
In-Reply-To: <7vaaa5pc8q.fsf_-_@alter.siamese.dyndns.org>

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

Show 15 quoted lines

> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> 
> > On Tue, Jun 7, 2011 at 20:21, Jamey Sharp <jamey@minilop.net> wrote:
> >
> >> 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 <jamey@minilop.net>

Show 48 quoted lines

> 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 <gitster@pobox.com>
> ---
>  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
>