Disallow admon nesting

[ghost]

Problem Description

This is currently legal:

<note>
  <tip> ... </tip>
</note>

Expected Behaviour

It should be invalid because this is weird, likely confusing for readers and a colorful atrocity. (SES 6 docs are currently using this construct.)

[tomschr]

Thanks. That's actually a well-known issue in DocBook 5. With the current RNG schema alone, you can't really restrict admons the way you want.

That's why the DocBook people created these Schematron rule(s) (see /usr/share/xml/docbook/schema/sch/5.1/docbook{,xi}.sch). There you can see additional rules related to all admonitions.

The solution to this issue would be to validate with the Schematron schema.

[ghost]

Shouldn't you be able to do that in Geekodoc even though it can't be done in DocBook?

I'd imagine DocBook's biggest trouble is because of constructs like this that are not legal GeekoDoc anyway:

<note>
  <para>
    <important>...</important>
  </para>
</note>

However, for us, we could start by restricting this relatively simple case:

<note>
  <important>...</important>
</note>

If we, in addition add special versions of itemizedlist/orderedlist that do not allow this:

<note>
  <orderedlist>
     <listitem>
       <important>...</important>
     </listitem>
  </orderedlist>
</note>

... we should probably be good. No?

[tomschr]

Shouldn't you be able to do that in Geekodoc even though it can't be done in DocBook?

I see you point. However, you try to bend RNG. :wink: It's not a DocBook or Geekodoc issue, it's the way how DocBook is structured plus some issue with RNG. RNG has good support for parent-child relationships. However, it is not ideal when you have nested structures where descendants are burried in a deep tree structure. That's why Schematron exists.

I'm also not a big fan of two schema files and tools that maybe support only a half of the features. On the other side, my biggest concern is maintenance and ease of development. I always tried to make Geekodoc "simple". Some of them could potentially be implemented (the note/important case), others are realistically not feasible in RNG (your last case).

If the DocBook developers thought it would be easy, they would have done it. The pure existence of a Schematron schema proves, that it is not that easy. :wink: That's why they moved all the "complicated" stuff into this Schematron schema.

At the moment, I see these solutions:

• Add more patterns to Geekodoc to support our use cases.
• Investigate in a Schematron schema and let daps embrace it somehow.
• Accept that we cannot validate all crazy structures; maybe add a XSLT stylesheet which tackles all this "edge cases" and is called after Geekodoc validation.

I know, all of the above has their pros and cons. It's just a collection of ideas. Maybe we can find together an idea which avoids the drawbacks? I guess, we should discuss that in person.

[tomschr]

Some more food for thoughts. I've tried to change the first case (note/important):

The original note element is defined like this (I removed the Schematron trules for the sake of simplicity):

db.all.blocks =
  (db.nopara.blocks | db.para.blocks | db.extension.blocks)
  | db.annotation | db.xi.include
db.admonition.contentmodel = db._info.title.only, db.all.blocks+
db.note =
   ## A message set off from the text
   element note { db.note.attlist, db.admonition.contentmodel }

The db.nonpara.blocks pattern points to the db.adminition.blocks. As we don't want admons in other admons, we need to change that. So let's introduce some new patterns:

db.nonpara.admin.blocks = 
  # all blocks without admonitions
  db.list.blocks | db.formal.blocks | db.informal.blocks
   | db.publishing.blocks  | db.graphic.blocks
   | db.technical.blocks  | db.verbatim.blocks
   | db.bridgehead  | db.remark
   | db.revhistory | db.indexterm
   | db.synopsis.blocks
db.all.admon.blocks =
  (db.nopara.admin.blocks | db.para.blocks | db.extension.blocks)
  | db.annotation | db.xi.include
db.admonition.contentmodel = db._info.title.only, db.all.admon.blocks+
db.note =
   ## A message set off from the text
   element note { db.note.attlist, db.admonition.contentmodel }

That disallows structures like note/important. However, it doesn't disallow it all the time. If you open a list, you introduce an admon not as a first child, but as a descendent. That would be allowed (although unwanted).

This last part is what I think is not really feasible. You would need to redefine too many patterns.

[tomschr]

Closing it as this is a non-topic for the time being. We can reopen it if this is really needed.