Re: [PATCH v3 1/3] Documentation: alias: rework notes into points

[Junio C Hamano <gitster@pobox.com>]

Ian Wienand <iwienand@redhat.com> writes:

> There are a number of caveats when using aliases.  Rather than
> stuffing them all together in a paragraph, let's separate them out
> into individual points to make it clearer what's going on.

Nicely explained.

> diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt
> index 01df96fab3..40851ef429 100644
> --- a/Documentation/config/alias.txt
> +++ b/Documentation/config/alias.txt
> @@ -21,8 +21,9 @@ If the alias expansion is prefixed with an exclamation point,
>  it will be treated as a shell command.  For example, defining
>  `alias.new = !gitk --all --not ORIG_HEAD`, the invocation
>  `git new` is equivalent to running the shell command
> +`gitk --all --not ORIG_HEAD`.  Note:
> ++
> +* Shell commands will be executed from the top-level directory of a
> +  repository, which may not necessarily be the current directory.
> +* `GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix`
> +  from the original current directory. See linkgit:git-rev-parse[1].

Looking for '[NOTE]' in the Documentation/ files finds sections
marked up like this (this one is from Documentation/git-blame.txt):

    ...
    parser (which should be quite natural for most scripting languages).
    +
    [NOTE]
    For people who do parsing: to make it more robust, just ignore any
    lines between the first and last one ("<sha1>" and "filename" lines)
    ...

and its rendition looks like this:

https://git.github.io/htmldocs/git-blame.html#:~:text=most%20scripting%20languages).-,Note,-For%20people%20who

I am undecided if it gives a better presentation, especially when we
are giving bulletted list, so let's take the patch as-is and leave
it to interested folks to explore the use of [NOTE] _after_ this set
of patches lands as #leftoverbit follow-up topic.

Thanks.