Re: [PATCH 2/2] Documentation: make git-sh-setup docs less scary

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 20, 2011, 19:20 UTC
Message-ID: <7v1urzkq2i.fsf@alter.siamese.dyndns.org>
In-Reply-To: <c8867738c264a76f9662080b64e00615ec1aa28f.1324378986.git.trast@student.ethz.ch>

Thomas Rast <trast@student.ethz.ch> writes:

> At least one IRC user was scared away by the introductory "This is not
> a command the end user would want to run.  Ever." to the point of not
> reading on.

You would need to say what that IRC user needed to find out. Depending on that, letting the user know that there is no point reading on early and not waste his or her time may be a good thing. That was what the paragraph was designed for. IOW, it is not to "scare" away, but to allow the users to decide if they are intended audiences.

The reworded version does avoid sounding scary, but loses the "this document is for people who want to write new or understand existing Porcelain scripts", which is a documentation regression.

Show 35 quoted lines

> Reword it in a more matter-of-fact way that does not intentionally try
> to scare the user away.  Since 46bac90 (Do not install shell libraries
> executable, 2010-01-31) it is not executable anyway, so the end user
> would get
>
>   $ git sh-setup
>   fatal: cannot exec 'git-sh-setup': Permission denied
>
> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
> ---
>  Documentation/git-sh-setup.txt |   11 ++++-------
>  1 files changed, 4 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
> index bbfefca..612fb50 100644
> --- a/Documentation/git-sh-setup.txt
> +++ b/Documentation/git-sh-setup.txt
> @@ -13,13 +13,10 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
>  
> -This is not a command the end user would want to run.  Ever.
> -This documentation is meant for people who are studying the
> -Porcelain-ish scripts and/or are writing new ones.
> -
> -The 'git sh-setup' scriptlet is designed to be sourced (using
> -`.`) by other shell scripts to set up some variables pointing at
> -the normal git directories and a few helper shell functions.
> +This command cannot be run by the end user.  Shell scripts can
> +source it (using `.` as indicated above) to set up some variables
> +pointing at the normal git directories and a few helper shell
> +functions.
>  
>  Before sourcing it, your script should set up a few variables;
>  `USAGE` (and `LONG_USAGE`, if any) is used to define message