magit/magit — pull request #1049 by tarsius (2013-11-17 20:17:57+00:00)
Title: refactor section creation api (part 1)

The api now consists of only four macros `magit-with-section`, `magit-cmd-insert-section`, `magit-git-insert-section`, and `magit-insert-line-section`. The last one is an addition; "header lines" are now real sections. (But we are not taking advantage of that yet. This will allow implementing e.g. #1044). The middle two replace the functions `magit-insert-section` and `magit-git-section`. The first is the only one that survived the refactoring. The new api macros all have a similar interface.

All other "section creation" functions and macros have been removed. Most of the logic previously implemented in the removed and replaced functions has made its way into `magit-with-section`, which as of now is a bit long and complicated. That isn't necessarily a bad thing, it certainly made refactoring easier. And when the refactoring is all done, I might do something about it, but for now this is okay.

Concentrating all the power in one place means that it can be passed on to the other api functions. Previously there were various ways of creating a section and each way of doing it came with its own unique features oddly missing from the other ways.

Some users of the api had special needs that the old api did not cover, leading to hacky code elsewhere. Most of these features are now covered by the new api. That not only means that the code is now cleaner, it also means that these features can now be used elsewhere too. In many cases it turned out that these features were only useful in one particular situation. We are not making full use the new features yet, but there is a lot of potential here.

I have not written proper doc-strings for the new api macros yet. There are still many changes to come, and any documentation written now, would later have to be thrown away. Documenting the section api is very important and I will do so once this is all done. While there are no doc-strings yet, I have written quiet verbose commit messages, so if you need to know all the details *now*, you should read those. Or just wait a little longer. (By the way this commit series reaches its climax in [aee8c46 sufficiently dynamic scope is indistinguishable from magic](https://github.com/tarsius/magit/commit/aee8c46d84ab08231229848e6b19aea9a4cfa644).

I am merging this now because it has become a burden not to. I hope I won't get hung for not having written the documentation yet, and before having fine tuned the api. (E.g. the argument order is *certain* to change). Also I would like to start benefit from the improvements now, instead having to write code that is obsolete on arrival because the new api hasn't made it into `master` yet. (I also cannot just drop working on anything else until I have rewritten the section code completely).

There is one change that is actually likely to be noticed by users: [621c5a magit-insert-section: make trailing newline part of section](https://github.com/tarsius/magit/commit/aee8c46d84ab08231229848e6b19aea9a4cfa644). I realize this might be disliked by some users. If you do dislike please keep in mind that others will *like* it and that I cannot make this customizable until I have some changes to the code for section *movement*.