Possibly switch Modelica documentation from HTML to Markdown #3122
Comments
christiankral
added
enhancement
|
It would be very easy to swap the libraries to markdown since markdown allows you to mix html and markdown (as long as tags are closed, etc) |
|
In don't think this is a question for the library but first of all of tool support. Should tools support be in place then I'm all for it. We had something similar regarding MathJax support. Which is no problem in OM for example but not in other tools. |
|
One way to go could be to have something like a Modelica Markdown editor and viewer (plugin or whatever) which can be used by all tool vendors. This Modelica Markdown editor/viewer should then be open source and the initial version may even be paid work financed by the Modelica Association. From such an initial version of this editor/viewer the tool vendors could improve and maintain the editor/viewer source code. The advantage of a common code basis were that the particular (Modelica specific) Markdown flavor does not have to be re-coded by every tool vendor. |
|
One could argue that we planned ahead for this by having
I don't see that as a good idea for several reasons: different tools have different plugin-capabilities, and tools also want the documentation editor to have the same look-and-feel as the rest of the GUI that will require substantial configuration possibilities in the plugin, which makes it a lot more complicated project to manage. And if we go for markdown we need to decide on which one, and I would prefer that we go for a standard one instead of inventing an Modelica-specific one. (Since it seems to be less work than reinventing the wheel, and it would be good to break out of mindset of MA-specific solutions.) And in that case I don't see a need for developing a new plugin within MA, since it seems likely that there already exists plugin(s) for that. |
|
This feels related to our ongoing work with the prototype for predefined plots. As we will show at the upcoming design meeting, our current prototype doesn't make use of HTML for several reasons, which I'm sure lead to discussions giving us the chance to explain in more detail next week in Lund. |
It would be incredibly helpful if we could validate the HTML in a CI job. |
This is the case since quite some time. |
|
Probably interesting to note that Dymola 2023 now supports Markdown and LaTeX (via MathJax) out of the box. Only thing that one has to do is to switch the rendering mode to Markdown. What is also interesting is that the LaTeX rendering also works in HTML mode (though not documented, @HansOlsson ? ) |
The creating of HTML documentation in any Modelica library is very fault prone (e.g. 5ae8073) as most documentation is created manually. Therefore, we continuously run into wrong or missing tags. Writing documentation in Markdown format is lot easier, faster and less fault prone.
So in the long run it may make sense to switch from HTML to Markdown in the Modelica documentation as suggested in #2867 (comment). This is an idea I wanted to share as some others may already have thought about it.
The text was updated successfully, but these errors were encountered: