format of yaml for concept lists #96

Opening a new issue here, this has some overlap with existing issues, but discussion there is a bit unfocused, and in older ones distracted with possible changes to the intent syntax. Hopefully now as we approach CR the intent syntax is fixed.

Following @dginev 's presentation of the YAML currently used (or planned) by the open concept list editor under development I compared with the existing yaml for the core list. It's not essential we end up with the same yaml format for both lists but that's probably a good thing to aim for.

Some thoughts on the current differences.

• Language entries

  currently these are top level under concept: so

    - concept: closed-interval
      arity: 2
      property: function
      en: closed interval between $1 and $2
      fr: intervalle fermé entre $1 et $2

  There was a suggestion to have a single entry speech and move the languages to a list under that. This seems fine and just marking here to record that it should be done...

• Argument Names

  The current yaml uses "meta" syntax $1, $2 for the positional arguments (and uses literal syntax $a1 and $a2 in any examples)

  The agreed plan is to move to using named arguments here such as $lower, $upper but then the arity field needs to change to give their order

  so either

  arguments: ["lower","upper"] or intent: "closed-interval($lower,$upper)"

  Either seems fine, but whatever we decide need to cope with n-ary functions such as the current

   - concept: list
      arity: ">=0"
      en: "list of $1, ..."

• Short Form display of concepts for common notations

  Currently we display many simple cases in a short form with just the symbol and concept name

  https://w3c.github.io/mathml-docs/intent-core-concepts/#core-concept-default-fixity-properties

  This is achieved by structuring the yaml in a similar way, specifically

  defaultfixity:
  - fixity: function
    concepts:
      - concept: curl
        characters: [∇]
      - concept: divergence
        characters: [∇]
      - concept: gradient
        characters: [∇]
      - concept: laplacian
        characters: [∆]

  This format might(?) be hard to control for submissions to open list so an alternative encoding would be to have "full" entries for these but with (say) a boolean include-in-notation-list:true or some such, then the current compressed display can be constructed at rendering time by sorting and filtering on this field.

  Or we drop these compressed lists?

• Concepts as top level yaml entries

  I (think) the editor currently uses yaml with the top level being a list of concept:

  In order to accommodate the short form list the current core.yml moves that list under a concepts: entry following the compressed lists.

  whether or not we keep the compressed lists it might be worth structuring this way which allows for future expansion by adding different top level entries.

• Subject Area

  On the call we discussed a area: or subject-area: field for concept entries.

  The current core list inverts that and has lists for each area with the concept lists below that so for example calculus is structured as:

  - title: calculus
    intents:
    - concept: definite-integral
      arity: 1
      property: ???
      en: "integral over $1"
      comments:
      - "integral sign is not an argument"
  
    - concept: definite-integral
      arity: 2
      property: ???
      en: "integral from $1 to $2"
      comments:
      - "integral sign is not an argument"

  This again might not work so well for submissions and it is probably(?) better to invert this and drop the sections in the yaml and instead have a subject-area: calculus entry in each if these concept:.

  The current display organsised by subject area could again (in principle) be generated in the html view by filtering the yaml appropriately.

• Comments
  Currently the core list accepts lists of comments eg

      comments:
      - "This can be spoken in many ways. See other entry for infix speech."
      - "There are several notations that are used and their order of appearance differs:

• URL
  The core list doesn't have a urls: field but the open.yml does as does the proposed editor format, doesn't seem any problem to allow this in core.

• Notations

  Currently the core list has a mathml: field under concept: the editor yaml suggests generalizing this, pushing it below a notations: entry and adding an optional tex: field alongside, which seems fine.

• Aliases
  the core yaml doesn't have alias: fields.

  I think that's OK, if we were moving something from open to core I think we'd pick one name for core and leave the others in open, so this could be part fo the same shared yaml format even if not actually used in the core list.