Meeting Notes Week of April 11, 2022

[rowanc1]

Renaming

• are these now mystTargets ♻️ REFACTOR: target -> mystTarget, comment -> mystComment #40
• these are now mystComments ♻️ REFACTOR: target -> mystTarget, comment -> mystComment #40
• ✨ NEW: Add fields enumerated and enumerator to containers, math, headings #36
  • enumerated, enumerator
  • Then good to go!

mystTargets should not be parsed with identifiers

These can come into the picture on a propagateTargets transformation.

• These no longer have identifiers, targets must be propagated to define what the identifier actually is.

• mystTarget removal is an option of the transform

• Regarding Link Referencing: https://github.com/executablebooks/myst-spec/pull/28/files#r842494008

  • Find definitions, delete them, get identifiers, turns them into link etc.
  • This is an early transform

• Add a stage enum to the test? There are a few levels of testing. (parse, transform, post, html)

@fwkoch merges:

• ♻️ REFACTOR: mystDirective/mystRole kind -> name #35

References

From here

• Target (this matches the identifier) of the target
• Explicit (has children, and possibly an enumerator)
• domain (std, math, prf, or any string)
• crossReference kind #24 has other thoughts on this as well!

Apr. 12 Decisions:

• rename crossReference identifier --> target (this is clearer!); this is explicitly different than MDAST
  • The thinking is that the linkReference in MDAST and other MDAST pieces get removed early in the parsing, and the crossReference will be long-lived all the way to render time.
• Add domain to the crossReference (std, math, prf, or any string) (allow for arbitrary strings!)
• For kind: expand to strings

For example, math: eq role becomes: domain: math, kind: numref

TODO:

• Write down some of the expected behaviours around references, and how we could possibly simplify ref/numref/eq choices for users.

April 14:

References

• Links []() syntax
  • HTML, mailto, ref, -> any
• References that are for a page
  • Then there are references that can be cross page.
  • Sphinx refs, every key needs to be unique across documents.
  • Sphinx doesn't tell you which reference, there isn't warnings on this.

Syntax discussions / Thinking:

• [](http(s?) or mailto) - these are external links, done

• [](#target) - this is any reference on this page (ref role, i.e. no eq (at the moment))

• [](doc.md) - this is a document link, it must have the extension in it.

• [](doc.md#target) - this is a target specifically on on another page (ref role, i.e. no eq (at the moment))

  • possible extension to this is recognize targets that start with certain characters, use this domain.

• [](any) - this is a fallback to look up anything in the project

• {py:func}`myFunciton` -- use roles to reference into specific domains

• Chris to move on this in the python implementation!

  • Write up a small thing on target resolution / order for a kick start at MEP.

• Franlin to improve myst-spec (small, decided upon issues!)

  • Table: rowspan/colspan
  • Check out: https://docutils.sourceforge.io/docs/ref/doctree.html#table

• Abbreviation: (explanation or title) unified-myst#17

  • Move to title!
  • @rowanc1 to do this!

• On implementing an extension:

  • Suggestion for an core-parse/extensions PR? unified-myst#16
  • ListTable
    • Would look to markdown-it-docutils
    • nestedParse, then look at the AST and do some testing