Flavor reference structure specification

This describes a flavor. Reference for a flavor should (for now) reside under reference_docs/<flavor_name>.yaml,

Document attributes, currently of most importance, should reside under document_attributes property within flavor reference file.

Flavor reference spec, expressed as TypeScript interfaces:

interface FlavorSpec {
  version: string // E.g., "v1.2.3"
  inherits_from?: {
    flavor: string // E.g., "standoc"
    version: string // E.g., "v3.4.5"
  }
  document_attributes: {
    [attributeIdentifier: string]: DocumentAttribute
  }
}

interface DocumentAttribute {
  tags: string[]
  title: string // Cannot contain markup.
  description: string // Can contain inline and block AsciiDoc markup.

  value_spec: string // Freeform description of attribute value specification. If omitted, attribute won’t have a value

  // Default value. A string showing literal value for this attribute, without quotes.
  value_default?: string

  // Should we, instead of “required”, just look if there’s a default value
  // and if not consider the attribute “required”? Is that how it works
  // across flavors?
  // Tina: "required" describes if the attribute is needed to create a well-formed document.
  required: boolean

  // Not sure about this. It’s useful, but it can be auto-inferred.
  // The problems with auto inference, however:
  // 1. It may get a bit involved. The renderer would
  // flip back through repository history and compare this attribute
  // contents with the current version; when a commit reached
  // where this attribute spec was different or didn’t exist, it’ll
  // check flavor version at that point and auto append
  // “added in X” or “changed in X”.
  // 2. Auto inference can be triggered by minor clarifications,
  // so it might say “changed in version X” even though a typo was fixed.
  added_in_version: string

  // Should be pure AsciiDoc.
  // Will be rendered as is inside an example block.
  example?: string

  //more information is used to provide related links, such as a blog article that discusses background info
  more_information?: string
}

For an example: https://github.com/metanorma/metanorma.org/blob/staging/reference_docs/standoc.yaml