Warn if section after appendix not marked up as appendix
ronaldtse opened this issue · comments
In draft-asciirfc-minimal, all sections occurring after a section tagged [appendix] becomes an appendix.
They are, but this has no implications for isodoc.
In RFC XML, both clauses and appendixes are marked up as section; the only difference between the two is whether their ancestor is middle or back. The current asciidoctor-rfc code differentiates middle and back positionally: once it sees one section that is a bibliography or appendix, it assumes that everything following also goes to back. It does not require appendixes to be styled as appendixes, because that styling does not change anything: the clause is still called section, and still ends up under back.
In the case of Asciidoctor-ISO, clauses and appendixes are marked up differently, as clause vs annex, and that information is sourced from the style attribute [appendix].
We could be more forgiving, like Asciidoctor-RFC is, and work out that once an appendix is seen, any following section (that is not a bibliography) should also be an appendix, and move them around accordingly. I don't think we should. Forcing tagging discipline on authors is the point of the validating schema to begin with. I could manipulate the asciidoctor input in metanorma to add those [appendix] attributes, but I'm uncomfortable doing much in metanorma that isn't done in asciidoctor itself: it makes the toolchain fragile, for little real benefit.
Asciidoctor-RFC happens to be more relaxed about Asciidoctor markup requirements on appendixes than Asciidoctor-ISO is, because of how RFC XML marks up appendixes. But the expected correct behaviour in Asciidoctor is to mark up Appendixes explicitly. (If you use native Asciidoctor, the crossreferences to unmarked appendixes will come out wrong.) And I do not agree that we should dilute proper Asciidoctor markup practice.
I agree with the need of explicit tagging, and the question becomes whether we can make asciidoctor-rfc require this tag on all appendix sections? All Metanorma formats should behave according to the same principles.
Yes, we should at least issue a warning when a trailing section is neither an appendix nor a bibliography. asciidoctor-iso already has warnings for that kind of thing in place.
Question: instead of a warning, should we just place that section before the tagged [appendix]es?
(in addition to a warning)
That violates principle of least surprise. A section after an appendix is much likelier to have been intended as an appendix than as a displaced clause.
That's true, but we need to ensure this "least surprise" behavior also applies to all other metanorma flavors such as asciidoctor-iso. Right?
Right. So, no sections should be moved after an appendix or bibliography section into the main body of text (and none are). And warnings should be issued consistently whenever a section is not tagged. (metanorma/metanorma-iso#185)