Jeff King <peff@peff.net> writes:

quoted text
> Maybe:
>
> -- >8 --
> Subject: [PATCH] docs: clarify "branch -l"
>
> This option is mostly useless these days because we turn on
> reflogs by default in non-bare repos.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-branch.txt |    2 ++
>  1 files changed, 2 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 903a690..d78f4c7 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -72,6 +72,8 @@ OPTIONS
>  	Create the branch's reflog.  This activates recording of
>  	all changes made to the branch ref, enabling use of date
>  	based sha1 expressions such as "<branchname>@\{yesterday}".
> +	Note that in non-bare repositories, reflogs are usually
> +	enabled by default by the `core.logallrefupdates` config option.
>  
>  -f::
>  --force::

That certainly is an improvement, but I've been wondering if it makes
sense to also have a section in each commands the configuration variables
that affects the behaviour of the command.  core.logallrefupdates surely
is not the only variable that affects how "git branch" behaves.

We might want to have a general concensus on what we want to have in the
documentation.  As you noted, some have too sparse SYNOPSIS, while others
have full list of options.  Some mention configuration variables, while
others don't.  Some have extensive examples, while others lack any.
Once we know the general direction in which we are going, we can hand off
the actual documentation updates to the crowd ;-)

I'll list my preference off the top of my head as a firestarter.

NAME::

The name followed by what it is used for

SYNOPSIS::

I prefer to have (almost) complete set of options in SYNOPSIS, rather than
"command [<options>] <args>..." which is next to useless.  This is
especially true for commands whose one set of options is incompatible with
other set of options and arguments (e.g. there is no place for "-b" to
"checkout" that checks out paths out of the index or a tree-ish).

I also prefer not to list "purely for backward compatibility" options in
SYNOPSIS section.

DESCRIPTION::

The description section should first state what the command is used for,
iow, in which situation the user might want to use that command.

OPTIONS::

List of full options.  Some existing pages list them alphabetically, while
others list them in functional groups.  I prefer the latter which tends to
make the page more concise, and is more suited for people who got used to
the system (and remember, nobody stays to be a newbie forever, and people
who stay to be newbies forever are not our primary audience).

Detailed discussion of concepts::

Some manual pages need to have discussion of basic concepts that would not
be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in
"checkout" manual).  I am not sure if this kind of material is better
given in OPTIONS section close to the functional group (e.g. "History
Siimplification" heading in "log" manual).


EXAMPLES::

I prefer to make it mandatory for Porcelain command manual pages to have a
list of often used patterns that a reasonably intelligent person can guess
how to tweak to match the particular situation s/he is in.


AUTHOR/DOCUMENTAITON::

These sections in most pages are not kept up to date, and I prefer to
remove them altogether.  They do not help end users who never clone
git.git, and those who clone git.git will have shortlog to give them more
accurate information.



--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html