Re: ghost refs

[Avery Pennarun <apenwarr@gmail.com>]

On Thu, Apr 8, 2010 at 4:42 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

I agree that you bring up a good point here.  I just hope you don't
lose Jeff's (useful and improving) patch during the ensuing discussion
:)

> 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.

The length of the synopsis section doesn't affect me much.  Mentioning
the equivalent config variable next to a command-line option, where
one exists, would probably be nice.

It might be okay to not actually describe in each manpage how the
relevant config options work; just referring people to git-config is
probably okay.  Having them all in git-config is useful in itself.

As for examples, well, people seem to really love examples.  So if
someone sends a patch to add more examples, I'm hoping there's no
reason to turn them down. :)

> 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 almost agree with you, except that nowadays there are *so* many
options that it doesn't really help much to have them all listed up
there.  It might be better to list only the most common ones.

When the same command has multiple modes, I agree that it makes sense
to list multiple synopses.

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

Sure.

> 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).

I actually get mildly annoyed when man pages don't list the options in
alphabetical order, because I naturally start looking for them in that
order.  But I can just as easily do a search for the option, so that's
probably just me being pointless.  In contrast, my pager can't help me
sort out the options by functional group, so that's probably a more
useful way to do it.

That said, I don't think consistency here is much benefit.  It's okay
if for some pages, functional groups aren't needed so alphabetical
order is used as a fallback.

> 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).

I think some pages have a DISCUSSION section right at the bottom,
after the description, options, and examples.  This seems like a good
way to do it.  man pages should have concise stuff so you can find the
information quickly, but there's nothing wrong with having detailed
stuff further down.

> 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.

To be honest, I've often wished that the plumbing pages would also
have such detailed examples. :)

Which reminds me, it would be really great if somehow each command's
manual would describe a) whether it's plumbing or porcelain, and b)
the alternative to look for if what you *need* is plumbing or
porcelain and the command is the wrong one.  But I don't know what a
good format for this information would be.

> 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.

I might be just being silly, but I really like seeing the Author
sections, even though I know they're usually obsolete and/or wrong.
It just makes git seem more human somehow, like real people were
involved in writing it.  I'm sure it results in Linus getting a bit
more credit than he deserves (it seems like the vast majority of man
pages name Linus as the/an author) but it's pleasant and seemingly
harmless.

Have fun,

Avery