part of issue727

Reviewed and merged. 

I added issue816 for a wider application of this feature, copying Malte's last
comment on possible extensions.

Code and usage look good to me.

Silvan and I implemented the "explicit" sections, and this is ready for review.

It would be good if at minimum some interested parties can have a look at how
this is *used*, which is only 11 lines of very simple code, namely everything in
the pdbs directory in the pull request:

https://bitbucket.org/jendrikseipp/downward/pull-requests/79

If some also wants to review the implementation, of course that's fine, too. :-)
It was very straight-forward because it is very close to the other kinds of
plug-ins we had already. Like the existing code, the new code is not great, but
it is not great in a consistent way. ;-) We think that more general clean-up of
the option parser code is a matter for a different issue.

The explicit sections would also make it easier to add additional functionality
like section descriptions, explicitly influencing the order in which sections
appear, or documentation pages that speak about several different plug-in types
that are related. (Silvan thought of merge strategies and shrink strategies.) We
are not going there here, but maybe we can collect ideas for extensions
somewhere? Not sure how best to do it. Perhaps we don't want to open an issue
unless we have a concrete intention to do something.

Also, there should be a follow-up issue to use the section feature more heavily.
We just have a section for PDB heuristics at the moment so that we can test the
feature.

We discussed this live today and decided to have a go at the "explicit sections".

> I don't think we really need section IDs for now.

I'm not convinced. I think repeating the same text all the time will violate
DRY, and because we have dozens of plugins, it will be quite a violation. (I see
a difference between a "symbol" for a section and a "human-friendly title" for a
section there.) Once we start using sections, we will touch a large fraction of
the plug-ins (in dozens of files), so it would be nice not to have to do touch
all of them twice within a short period.

There are also drawbacks with having "section plug-ins", mainly that it is not
so obvious where they should live in the code.

I suggest discussing this with the interested parties tomorrow.

I added the PDB heuristics to their own section. I don't think we really need 
section IDs for now.

Changed to the old behaviour.

I think we should use the old behaviour.

I fixed the error in the documentation and pushed it to the pull request at
https://bitbucket.org/jendrikseipp/downward/pull-requests/79. But a new error
came up.

Before the fix, the documentation used the 'key' of a plugin if no
document_synopsis is given. Now it uses <missing> if we omit the
document_synopsis. What would be the best way to deal with this?

Correction: the correct version of course says "lmcut_constraints()", not
"lmcut()" as I said in my previous message.

I had a look at bitbucket. No detailed comments. (However, see below.)

To test this properly, we should exercise the new feature. Can you add all PDB
heuristics to a section "Pattern Databases" or similar?

Would it make sense to have each section have an ID and a title, rather than
just one string for both? For example, if I have a section "heuristics based on
saturated cost partitioning", then I think it may violate DRY to some extent to
have each heuristic in this section require this exact long string. It might be
nicer to have a "scp" tag instead. I realize this makes things harder to
implement because sections then need their own "identity" in the code. But that
would have further advantages, e.g. allowing documentation at the section level.
Discuss this further?

To test the code, I produced the docs and compared them to the docs before this
change, and they are broken. For example, instead of

== LM-cut landmark constraints ==
lmcut()

it now says

== LM-cut landmark constraints ==
LM-cut landmark constraints()

So obviously I overlooked something in the review. Could be a shadowing of local
vs. instance variables? I'll leave the search for the error for you, but if you
don't find it easily we can search it together.

I made a pull request at 
https://bitbucket.org/jendrikseipp/downward/pull-requests/79
and will add this to the review queue.

We want to add sections to the wiki documentation pages to group similar plugins.