Simple document schema

sdoc.rnc

datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"

namespace sdoc = "https://eoga.dev/sdoc"
default namespace = "https://eoga.dev/sdoc"

# Helper to allow any markup in specific areas.
# For instance, could be used to embed SVG or other formats.
any-markup = (text | element * - sdoc:* { attribute * { text }*, any-markup* })*

start = sdoc-element-topic

# Topics are the building blocks of documents.
sdoc-element-topic = element topic {
  # Optional attribute, should occur only in on topic.
  attribute root { xsd:boolean } ? &
  
  # Labels are the default label to use when linking to a topic.
  # If label is title, it should default to the title text.
  element label { text } ? &

  # The title of the page, normally used for the <title> element of an
  # HTML page.
  element title { text } &

  # Could be used to describe the topic by a search engine.
  # This description allows block content but should be kept succinct.
  # When generating HTML, it is used to add a meta-description for
  # search engines by stripping the markup and using just the text.
  element description { sdoc-block-element } &

  # Author full name. SDoc processors may try to determine an author
  # if this is missing (likely default to the author of the root
  # topic).
  element author { text } ? &

  # Main content of the page. This is optional since the topic may
  # just be a "hub" topic with links to other pages, etc.
  element body { sdoc-block-element * } ? &

  # These can be defined to link to other pages.
  # The topic stylesheet should do something with these.
  sdoc-element-collection *  &

  # Links to related resources, most likely external sites.
  sdoc-element-link * &

  # These can be defined to add a license to the content of the topic.
  sdoc-element-license *
}

# A collection of references to other topics.
# Used to build navigation links.
sdoc-element-collection = element collection {
  attribute key { xsd:NMTOKEN } &
  attribute title { text } &
  sdoc-inline-ref *
}

sdoc-element-link = element link {
  attribute rel { "cannonical" | "reference" } &
  attribute href { xsd:anyURI } &
  attribute title { text }
}

sdoc-element-license = element license {
  attribute key { xsd:NMTOKEN },
  sdoc-block-element *
}

# Block elements as a controlled subset of XHTML elements,
# plus any SDoc specific elements.
sdoc-block-element =
  sdoc-block-p |
  sdoc-block-ul |
  sdoc-block-nav

# Inline elements as a controlled subset of XHTML elements,
# plus any SDoc specific elements.
sdoc-inline-element = 
  sdoc-inline-ref |
  sdoc-inline-a |
  sdoc-inline-img

sdoc-block-p = element p {
  attribute title { text } ?,
  (text | sdoc-inline-element) *
}

sdoc-block-ul = element ul {
  attribute title { text } ?,
  sdoc-block-li *
}

# A collection reference is a placeholder for a SDoc processor to
# render a list of links to the elements of that collection.
sdoc-block-nav = element nav {
  attribute collectionref { xsd:NMTOKEN }
}

sdoc-block-li = element li {
  (text | sdoc-inline-element) *
}

# A ref normalizes the text of the label to find a reference to a
# topic.  For instance: <ref>My Topic</ref> will be a reference to the
# topic "/topics/my-topic.topic", with label "my topic". When the
# topic and the label need to be different, the reference key can be
# provided explicitely. For instance <ref key="spotted-racoon">animal</ref>
# refers to the topic "/topics/spotted-racoon.topic".
sdoc-inline-ref = element ref {
  attribute topic { text } ?,
  text
}

sdoc-inline-a = element a {
  attribute href { text } &
  attribute rel { text } ? &
  (text | sdoc-inline-element) *
}

sdoc-inline-img = element img {
  attribute src { text } &
  attribute alt { text } ?
}