Deprecate @EndSection and @EndSubsection

[fingolfin]

Let's deprecate @EndSection, and @EndSubsection. Instead, improve the logic which automatically ends chapters/sections/subsections. This is motivated by #157 and @oysteins comments there. To steal from his comment there:

• Make subsections end automatically when encountering a declaration.
• Deprecate the @EndSection, and @EndSubsection commands in the manual; also change them to print warnings
• provide PRs to the handful of packages using them:
  • datastructures
  • LocalNR
  • HeLP
  • ComplexesForCAP
  • NConvex
  • QPA2 (only uses @EndSubsection, but removing that requires a new AutoDoc release, so we can't rush this)
• once all packages using them have been updated (resp. had a release?) we can remove them from the manual (or at least move them into a dedicate "Deprecated features" section)
• Explain in the manual that a subsection and a declaration give headings on the same level (or in other words: a declaration gives a special type of subsection), which means that one cannot use subsections to structure the declarations.
• optionally: consider supporting # Chapter, ## Section and ### Subection syntax, at least in .autodoc files... moved to issue Allow using # Chapter, ## Section and ### Subsection in .autodoc files and doc comments #213

[sebasguts]

I would not like to deprecate them all. @EndChapter might be somehow useless, although it would prevent from putting further method declaration ending in that chapter, but in the auto generated chapter.

However, @EndSection and @EndSubsection can be used to structurize text. When you do a subsection and end it, text inputed afterwards will be in the section, not the subsection. I am not sure if this is of any immediate use, but it reflects the way the HTML is structured.

[fingolfin]

OK, I guess I somewhat see a point for @EndSubsection then. But for @EndSection, I don't -- unless you want to allow for text between sections, which seems like a bad idea, as explained in issue #157.

And I'd argue that even text between subsections is a bad idea (there is a reason why neither MarkDown nor LaTeX support that, I guess). And it is usually impossible for the reader to tell the difference visually anyway. And what would one use this for? What kind of text would not instead also fit into the end of one subsection or the start of the next?

Of course, I am in general sceptical about using subsections at all, so I might be overly negative :-)

[sebasguts]

I see. Well, putting the introductory text at the beginning of a chapter is one of my main reasons.

As you correctly say, latex does not really support this feature anyway. We could (first silently) deprecate them, so we can just make them stop do anything at all. Then drop them at some point.

I am not sure about dropping subsections at all. They are not really a problem, and I sometimes use them, as only two layers of nesting is not enough sometimes. Why should we remove them?

[fingolfin]

I did not mean to suggest that we should drop support for subsections, just that I personally try to avoid them in papers and otherwise. But I think it makes sense that we expose all GAPDoc features. Moreover, people do use them. And even I may sometimes use them.

[sebasguts]

Okay, then I just misinterpreted your comment, I think :).