Attempt to consolidate admon content model #60

[tomschr]

This PR fixes #60 and contains the following changes:

• Disallow formalpara
• Reduce content model of admonitions in general
  => allow remark, para, lists, screen, and xi:include.
• Add testcase

[ghost]

This seems a bit too restrictive. My main tenet was that admons should not have formalpara as their first element (after title). Maybe go for something more like allowing:

title?,
remark*,
para,
(para | formalpara | all_manner_of_lists | verbatim_stuff | remark | ... )*

[tomschr]

Oh, I see! I thought, you wanted to get rid of formalpara altogether. Will adapt it accordingly.

[tomschr]

@sknorr better? 😉

[taroth21]

I would agree that we should keep formalpara within admonitions but not as first element.

[ghost]

Thanks! Looks much better. I'd suggest to allow informal elements as well, though:

(via TDG 5.1)

informalequation
informalexample
informalfigure
informaltable (db.cals.informaltable)
informaltable (db.html.informaltable)

[tomschr]

Thanks! Looks much better. I'd suggest to allow informal elements as well, though:

Good. 👍 I was unsure about the informal elements, but I can add them too.

However, do we really need a table inside admonitions?
@taroth21 Do you have any use case for tables inside admonitions?
(Just curious)

informaltable (db.cals.informaltable)
informaltable (db.html.informaltable)

We don't support HTML tables, only CALS.

informalequation

We don't support that too. 😉

[taroth21]

However, do we really need a table inside admonitions?
@taroth21 Do you have any use case for tables inside admonitions?
(Just curious)

I vote against informaltables in admonitions, they tend to blow up the admonitions. :;

informaltable (db.cals.informaltable)
informaltable (db.html.informaltable)

[ghost]

Please just allow all informal elements that we support. I don't really see tables as "blowing up" admons -- whatever that means in particular.

I do admit that admon/informaltable is probably a very niche use case but it might be useful, e.g for a <note/> that contains a small comparative feature table etc.

I don't think there is much potential for "abuse" by writers, especially given the complexities of table markup.

[tomschr]

admon/informaltable is probably a very niche use case but it might be useful, e.g for a that contains a small comparative feature table etc.

My point on this:

• I haven't seen a use case in our docs so far. Although this isn't argument per se against it, it is IMHO a strong indicator that we don't need that (at least not now).
• Tables inside admons make layout problems. Usually admons can be indented when used in list. An admon with tables makes it even more harder, especially on mobile devices (EPUB or HTML).
• From my perspective, ideally an admon should contain only some text, not feature tables. These should go outside of the admon. However, that is my personal opinion/taste and others may not agree with that.

I don't think there is much potential for "abuse" by writers, especially given the complexities of table markup.

Maybe not "abuse", but we also should guide our writers what we think is appropriate in our documentation and what is not.

What about the following idea: we try to work without informaltables in admons first. If we find out, that it is too restrictive, I will happily add them. Deal? 😉