We need a separate website (or at least different section in this existing website)
which describes the format; and also e.g. for "Bool" describes the
different versions, and in which profile/Oscar/Magma/... versions
it changed...
To be concrete, I think there should be a front page for the website, titled perhaps "The MaRDI File Format: A FAIR File Format for Mathematical Software"
The front page would have some brief general explain what this is about, 1-2 paragraphs. It would then have links to two sub pages: The specification, and the rosetta stone.
At the bottom a disclaimer with some notes, e.g. perhaps "supported by MaRDI https://www.mardi4nfdi.de , supported by DFG SFB/TRR-195 https://www.computeralgebra.de/sfb/, etc."
The current index page would become the entry point to the rosetta stone (with a link added back to the new front page). And a new page would be added for the specification.
The specification stuff would live in a new subdirectory "spec".
The specification ought to define how the JSON format overall works; here the
paper at https://doi.org/10.48550/arXiv.2309.00465 (sources in paper/icms.tex)
can be used as basis/reference.
The specification then would also describe some specific data types and how they are serialized, e.g. int/string/vectors/dicts/... Perhaps also more advanced ones (basically anything we have examples for???), with links between the specification, and examples (in both directions). But the focus would be on getting common stuff clarified; for advanced stuff we want (for now) to keep it a bit more loose... the idea is to work with "profiles" there (to be discussed in another issue)
The spec should also fix some terminology (like... I just used "data types", is that what we want to call then? If so, make sure to stick to it, and also state it explicitly. A bit like RFCs do)
I'll ask Codex to make a first stab at this
We need a separate website (or at least different section in this existing website)
which describes the format; and also e.g. for "Bool" describes the
different versions, and in which profile/Oscar/Magma/... versions
it changed...
To be concrete, I think there should be a front page for the website, titled perhaps "The MaRDI File Format: A FAIR File Format for Mathematical Software"
The front page would have some brief general explain what this is about, 1-2 paragraphs. It would then have links to two sub pages: The specification, and the rosetta stone.
At the bottom a disclaimer with some notes, e.g. perhaps "supported by MaRDI https://www.mardi4nfdi.de , supported by DFG SFB/TRR-195 https://www.computeralgebra.de/sfb/, etc."
The current index page would become the entry point to the rosetta stone (with a link added back to the new front page). And a new page would be added for the specification.
The specification stuff would live in a new subdirectory "spec".
The specification ought to define how the JSON format overall works; here the
paper at https://doi.org/10.48550/arXiv.2309.00465 (sources in
paper/icms.tex)can be used as basis/reference.
The specification then would also describe some specific data types and how they are serialized, e.g. int/string/vectors/dicts/... Perhaps also more advanced ones (basically anything we have examples for???), with links between the specification, and examples (in both directions). But the focus would be on getting common stuff clarified; for advanced stuff we want (for now) to keep it a bit more loose... the idea is to work with "profiles" there (to be discussed in another issue)
The spec should also fix some terminology (like... I just used "data types", is that what we want to call then? If so, make sure to stick to it, and also state it explicitly. A bit like RFCs do)
I'll ask Codex to make a first stab at this