ModelicaBook
ModelicaBook copied to clipboard
mtiller
Links to Modelica Spec and MSL
It would be nice if there were canonical ways to link to both the Modelica Standard Library and the Modelica Specification. It might be a nice idea for the Modelica Association to setup a system whereby the following links redirected to the correct places:
http://docs.modelica.org/spec?section=12.7&version=3.2 (Section 12.7 of the 32. spec)
http://docs.modelica.org/msl/Modelica/Blocks (Link to the documentation for "Modelica.Blocks")
It would be easy to do and it would make it so easy to reference things.
MSL documentation is online, but not on modelica.org or svn.modelica.org from what I can tell. https://rawgithub.com/modelica/Modelica/release/Modelica%203.2.1/Resources/help/index.html https://build.openmodelica.org/Documentation/Modelica.html
I am sure Dietmar could unzip part of the release and keep it on modelica.org...
As for the specification. It is still in Word format. It really could use some nice text-based book formatting language that can be translated to multiple formats...
Two points. First, I think it is important to host on modelica.org (and keep it maintained). Second, I'm thinking that it would be good to use some redirections here. For example, with the specification it would be really nice if the URL I described redirected to something like:
https://www.modelica.org/documents/ModelicaSpec33.pdf#page=221&zoom=auto,0,191
There is a problem with that. If you disable pdf plugins in your browser or it doesn't support bookmarks like that, you won't have any use for links to a specific page of a pdf (was introduced in Acrobat 7). Having the spec as html would be much nicer because then I could google the specification instead of try to search for text in pdf (which doesn't work as well as one would hope sometimes).
Spec in HTML would be huge (ideally via docbook). But we don't have that and I cannot imagine getting people to agree to that.
If you disable that support in your browser, then we would indeed be stuck. But the user can control that at least.
One other problem I find with the page links appending a link to a PDF is that the whole PDF gets downloaded each time even if the PDF is already present and opened. So having it as HTML would really be better. Since I don't see a near future switch to DocBook or similar we might refresh the discussion by saying that the Spec should not just be published as PDF but also as HTML. I mean Word can export HTML right (even though it would not be a perfect HTML but something that we could work with).
I looked into what LibreOffice+tidy would create: spec 3.3r1 html
It's only sort of readable, but it beats pdf. The images are embedded instead of separate, which is mildly annoying. The anchors would need to be renamed in some post-processing to have user-friendly names like section-1.4. Writing the whole thing in docbook or so would be nicer though (text-based diffs from svn so you can see what changes people made).
The HTML documentation of the Standard library is available here (I think @dietmarw put it online?): https://modelica.github.io/Modelica/ https://github.com/modelica/Modelica
@sjoelund has first rst version of the language specification https://github.com/sjoelund/MLS-rst-spec https://modelica.readthedocs.org/en/latest/
Possibly relevant here, too: http://stackoverflow.com/a/125650/874701 Instead of linking to pdf pages, it is also possible to link to named destinations like section.17.1 if such named destinations are present in the pdf. Currently, the pdfs from modlica.org do not have such named destinations.
There has been considerable discussion about trying to change the way the specification is developed to support this kind of linking. No actually decisions as of yet though.
Long discussion indeed, tried to add my 2 cents to it. I hope the rst or markdwon people win. :-)
Spec in HTML would be huge
It is here: https://specification.modelica.org/v3.4/MLS.html
But only v3.4 is available as HTML, which also would require to update the book to that version, see e.g., #401.
