0

The official documentation's 1.1. Understanding Content Models is very terse, and I'm having trouble understanding the content models of more complex elements. It brings the epigraph element as an example:

A validator uses the content models to determine if a given document is valid. In order for a document to be valid, the content of every element in the document must match the content model for that element.

In practical terms, match means that it must be possible to expand the content model until it exactly matches the sequence of elements in the document.

For example, consider the content model of the epigraph:

epigraph ::= (info?db.titleforbidden.info, attribution?,(literallayout | Paragraph elements)+)

epigraph is a fairly simple element, and it is straightforward to convert its content model from documentation page (see below) to the more compact form in 1.1. Understanding Content Models (see above).

epigraph ::= × ⏵

  • Sequence of:
    • info? (db.titleforbidden.info)
    • attribution? + One or more of:
      • literallayout
      • Paragraph elements

I found the compact notation easier to interpret as the the long-form version in the documentation pages uses lists, and the longer they get, the harder it is to keep track of the "matching branches". For example, I was trying to figure out whether I could omit the title element when using preface, but didn't find it an easy task (its content model is 154 lines, see at the bottom).

Now, I could try to convert the model on the doc pages into the more compact form, but it would take considerable amount of time, especially if I have to go through this process with each element one by on. This could be automated, but another problem I have is that I'm not sure about some of the terms, such as "Interleave of": does it mean an unordered list with duplicate elements allowed? ("Sequence of" is clear: "take these elements or groups of elements in the following order".)

Tried to look up preface's definition in the docbook/docbook repo, but it turns out that I'm not proficient enough to understand Relax NG and Schematron schemas yet... In the end, my original question got answered by finding a snippet in the docbook/defguide repo; it helps comparing it with its long-form content model, but there must be an easier way to reason about it. (Plus, it can be hard to find specific DocBook examples online.)

<preface>
  <info>
    <title>Preface to the DocBook V5.1 Edition</title>
  </info>
  <para>This edition of ...</para>
</preface>

preface ::= × ⏵ ⏷

  • Sequence of:
    • One of:
      • Sequence of:
        • Interleave of:
          • title
          • titleabbrev?
          • subtitle?
        • info? (db.titleforbidden.info)
      • info (db.titlereq.info)
    • Optional sequence of:
      • Zero or more of:
        • bibliography
        • glossary
        • index
        • toc
      • One of:
        • Sequence of:
          • One or more of:
            • annotation
            • bridgehead
            • formalgroup
            • remark
            • revhistory
            • Indexing inlines ⏵ ⏷
            • Admonition elements ⏵ ⏷
            • Formal elements ⏵ ⏷
            • Graphic elements ⏵ ⏷
            • Informal elements ⏵ ⏷
            • List elements ⏵ ⏷
            • Paragraph elements ⏵ ⏷
            • Publishing elements ⏵ ⏷
            • Synopsis elements ⏵ ⏷
            • Technical elements ⏵ ⏷
            • Verbatim elements ⏵ ⏷
          • Optionally one of:
            • Sequence of:
              • One or more of:
                • section
              • Zero or more of:
                • simplesect
            • One or more of:
              • simplesect
            • Sequence of:
              • One or more of:
                • sect1
              • Zero or more of:
                • simplesect
            • One or more of:
              • refentry
        • Sequence of:
          • One or more of:
            • section
          • Zero or more of:
            • simplesect
        • One or more of:
          • simplesect
        • Sequence of:
          • One or more of:
            • sect1
          • Zero or more of:
            • simplesect
        • One or more of:
          • refentry
      • Zero or more of:
        • bibliography
        • glossary
        • index
        • toc
toraritte
  • 6,300
  • 3
  • 46
  • 67
  • Please recheck the question as the layout / indentation in the quoted parts if extremely important here and e.g. `attribution? + One or more of: ` on one line is not correct and should be on 2 lines! – albert Feb 11 '23 at 17:22
  • @albert Thanks! It is now fixed, but just to copy paste the content model section takes up quite some time - which is kind of the point of the whole question. – toraritte Feb 11 '23 at 19:20
  • 1
    @toraritte: I'm not sure I understand the question. The way you interpret it is the way you interpret anything vaguely complex: one step at a time, taking each piece in turn. Are you expecting people to give you an algorithm that converts the long-form content into short form? What kind of answer are you expecting from this question? – Nicol Bolas Feb 11 '23 at 19:30
  • "*I was trying to figure out whether I could omit the title element when using preface, but didn't find it an easy task (its content model is 154 lines, see at the bottom).*" But only the first 8 lines involve things that would represent the title of a `preface`. – Nicol Bolas Feb 11 '23 at 19:35

0 Answers0