remove doc-strings of section creation functions

Remove the doc-strings of `magit-new-section', `magit-cancel-section',
`magit-with-section', `magit-insert-section', `magit-git-section',
`magit-create-buffer-sections', and `magit-propertize-section'.  Of
these only `magit-with-section' will survive the subsequent refactoring.

New doc-strings will be added once the current refactoring is over.

Keeping these doc-strings, which in some cases are insufficient, would
make refactoring harder than it need be: changes would have to be
written trice: once in Lisp and twice in English.
remove introductory comment about sections

It's a noble goal to provide some documentation for those using the
source, but since this was the only such comment and because it was
also not informative enough, it did not really do any good.

I am all for literate programming, but that has to wait until after
the cleanup is over and after the next release.  And even then we
might not do it.
magit-with-section: group non-BODY arguments as ARGLIST
magit-with-section: switch order inside ARGLIST
magit-new-section: change argument order
magit-set-section: change argument order
don't try to be smart about not highlighting sections

A major problem with the section implementation is that there is next to
no consistency regarding the meaning of the slots TITLE, TYPE, and INFO.
In different contexts and for different "kinds" (let's not use "type" to
avoid confusion :-) of sections are used to "identify" (what that means
also isn't consistent) sections.

As a result that code written with one use-case in mind cannot be used
elsewhere, leading to duplication and a growing number of inconsistencies.

One anomaly with likely is not only the result of this confusion but
probably the cause of many of these inconsistencies is that "a section
not having a title" is the (only) way of creating a section that is
never highlighted.

Instead add new slot HIGHLIGHT with defaults to t.
give calls to magit-git-section a uniform appearance

As much as possible format all calls to `magit-git-section' the same.

If possible put the TYPE and BUFFER-TITLE arguments on the same line
as `magit-git-section'.  When BUFFER-TITLE is calculated "inside" the
call to `magit-git-section' and that takes more than one line or a very
long line then put it on separate line(s).  Always put WASHER on its own
line; if it is a symbol quote with #' not just ', providing semantic
information to the reader.

I am doing this now because it helps looking for inconsistencies that go
beyond appearance.
identify branch-manager sections using symbols

In `magit-refresh-branch-manager' use the symbol `branchbuf' instead
of the string "branches" as the TYPE of the inserted top section.

In `magit-wash-branches' use the symbol `local' as the TYPE and so
called TITLE of the respective section.  Previously the string "local"
was used as TYPE and nil was used as TITLE.
identify all buffer sections
identify all buffer sections, using symbol ending in `buf'

In `magit-refresh-reflog-buffer use `reflogbuf' instead of `reflog' as
the TYPE of the inserted top section. In `magit-refresh-wazzup-buffer'
use `wazzupbuf' instead of `wazzup'.

Now all such top-level buffer sections have a symbol as TYPE and the
symbol names of all of them end with "buf" (with no separating dash,
mostly for historic reasons).

Actually this is not quiet true.  The `logbuf' and `reflogbuf' section
are wrapped in an additional, otherwise empty, and unnecessary `log'
section.  But I noticed that to late to fix it in this commit.
magit-with-section: locally bind section to named variable

This prepares for the eventual removal of the troublesome variable
`magit-top-section'.  Three of the difficulties resulting from the
use of that variable are hinted at here, but there are more.

Add a new argument SECTION to the ARGLIST of `magit-with-section'.
It has to be a symbol and it is bound to the section being created
by `magit-with-section'.

Something similar is done in `magit-section-{action,case}'.

Do not actually make us of the new binding yet.  Except in one case
where not doing so would result in a surprising breakage (diffs can
no longer be expanded).  The main change in this commit is related,
but one would not expect this to break `magit-wash-raw-diff' - but
being predictable is not exactly a property of `magit-top-section'.

It might seem that there are not many uses of `magit-with-section'
that could actually make use of SECTION, because there are not many
that currently use `magit-top-section'.  That however is an illusion
- there are many sections that use it indirectly by calling functions
such as `magit-set-section-info' which do manipulate the section
stored in `magit-top-section', when their optional SECTION argument
is nil (which it always is).  These functions were presumably
created in the first place because having uses of `magit-top-section'
appear everywhere was troubling (or at least noisy) and someone
wanted to hide that fact (effectively obscuring `magit-top-section'
even more).
magit-set-section-info: remove function

Remove `magit-set-section-info' and the obfuscation it caused; and
instead use `setf' with the "current section"s INFO slot as PLACE.
Since the previous commit, that section is commonly available as the
value of a known symbol (with limited dynamic scope).

In some other cases where the call to `magit-set-section-info' was not
lexically within a call to `magit-with-section' the section now has to
be passed using a function argument (from the function which uses the
`magit-with-section' macro, to the function which wants to manipulate
the sections INFO slot).  That's a good thing.
magit-set-section-needs-refresh-on-show: remove function

See previous commit for motivation.
magit-make-commit-button: absorb magit-set-section

Extend `magit-make-commit-button' so that it not only turns a text area
into a button but at the same time turns it into a magit section.  The
second task was previously performed by `magit-set-section'.  The latter
is removed in this commit.  And so is the noisy code that was previously
required around the calls to these functions - they only ever appeared
in combination.

Now `magit-make-commit-button' is much more useful because it does
everything related to creating a commit button, and could therefor
potentially be used elsewhere.  Actually we should consider whether the
"button as a section" concept could be used for other things besides
commits.

Regarding the removed `magit-set-section' I have to say this: It is a
colosal failure if a function is advertised as universally useful (here
by its name and placement) even though it is not, AND only has a single
caller (`magit-wash-commit'), FOR WHICH it is COMPLETELY inappropriate,
because it only serves to COMPLICATE that one caller (for which it
presumably was written), AND there already is an existing abstraction
(`magit-make-commit-button') which only has to be modified SLIGHTLY to
ACTUALLY make it easier for the caller.
magit-wash-commit: avoid inserting unnecessary whitespace

... when inserting commit buttons.
magit-insert-commit-navigation-button: new function

Add new function `magit-insert-commit-navigation-button' to avoid some
code duplication (some of which is yet to come, luckily not actually in
form of duplication).

The symbol name contains "-navigation-" because this function is not a
variation of `magit-make-commit-button', though in practice it behaves
similarly.
magit-create-log-buffer-sections: remove macro

Remove macro `magit-create-log-buffer-sections'.  Dong so leads to a
tiny bit of code duplication.  Actually because it was only used twice
this commit adds exactly as many lines as it removes.  It used to be
used more often but even then the existence of this macro was not
justified.

This macro is related to (and uses) `magit-create-buffer-sections'.  In
addition to what the latter does it also prepares for something else to
count how many log items were inserted and then inserts the "there are
more commits" button.  That is not really closely enough related to
the task of `magit-create-buffer-sections' (dealing with the failing
`magit-top-section'/magit-old-top-section' abstraction) that one could
easily guess what the removed macro does in addition to what the other
does.  So let's just put the code where one would expect it.
magit-insert-section: absorb magit-cancel-section

It's not used anywhere else and by providing this functionality as a
separate function we encourage its use, which we shouldn't do because
using it would likely be due to failure to understand the section api.
There is already enough abuse of that, let's make it harder for
contributors to shot themselves (and us) in the foot.
magit-insert-section: don't remove empty buffer sections

Don't remove empty buffer sections, but keep doing it for other
sections, e.g. for "Staged changes" when there are not actually any
staged changes.  But do not remove empty buffer sections.  They are
not actually empty, but usually contain the header, which provides
information that is relevant when a user tries to determine why git
did not produce any input.  Previously the section was removed and
replaced with one that just said "(empty)", which is not helpful at
all.  E.g. "Changes in HEAD..HEAD\n(empty)" is much more useful than
"(empty)"; it could help the user realize that he did not actually
type "HEAD~.." as intended but "HEAD..".

Move all the code related to this into `magit-insert-section',
previously some of it was inside `magit-create-buffer-section'.