Proposal: allow markdown in 'notes' instead of XHTML

[luciansmith]

The 'notes' child of SBase in SBML is used to store human-readable descriptions of the element in question. Originally, it seemed good to make this be XHTML, so it could be rendered nicely when displayed to users.

However, nowadays people write documentation in markdown a lot, and there are a wider variety of text-based interfaces to SBML. As such, it would be nice to allow people to store notes in markdown form, instead of requiring XHTML.

Some details need to be nailed down if we think this is a good idea, like 'how do we let the user know they have markdown or HTML?'

[draeger]

SBML has always been designed as a machine-readable format, not something intended to be written or edited directly by humans. This means that the primary concern should be how software processes and presents SBML content rather than how it is stored internally.

Since Markdown can be automatically translated into XHTML, software tools could allow users to input notes in Markdown while ensuring that the SBML file continues storing the notes in the required XHTML format. This would provide the usability benefits of Markdown without requiring changes to the SBML specification.

Introducing a new Markdown-based format directly into SBML would necessitate defining a separate namespace to distinguish between Markdown and XHTML content. However, this would introduce several complications:
1. Interoperability Issues – Current SBML-compliant tools expect notes to be in XHTML and may not be able to handle Markdown correctly. Adding a new format would require widespread software libraries and tools updates, potentially breaking existing implementations.
2. Standardization Challenges – XHTML is a well-defined standard, whereas Markdown has multiple variations (CommonMark, GitHub-flavored Markdown, etc.). Choosing a specific Markdown variant and ensuring consistent rendering across different implementations would require significant effort.
3. Increased Complexity – Supporting multiple formats in SBML means additional validation rules, increased parsing complexity, and ambiguity in how different software tools interpret the content. This could lead to inconsistencies in how notes are displayed or processed.

Given these considerations, a more practical solution is to keep SBML’s internal format as XHTML while allowing software tools to accept user input in Markdown and convert it automatically. This preserves compatibility with existing SBML infrastructure while providing Markdown's usability improvements where needed.