search

mtiller / ModelicaBook

Source for my new Modelica Book
https://mbe.modelica.university
Other
97 stars 71 forks source link

Links to Modelica Spec and MSL #26

Open xogeny opened 10 years ago

xogeny commented 10 years ago

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.

sjoelund commented 10 years ago

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...

xogeny commented 10 years ago

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

sjoelund commented 10 years ago

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).

xogeny commented 10 years ago

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.

dietmarw commented 10 years ago

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).

sjoelund commented 10 years ago

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).

thorade commented 9 years ago

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/

thorade commented 9 years ago

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.

xogeny commented 9 years ago

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.

thorade commented 9 years ago

Long discussion indeed, tried to add my 2 cents to it. I hope the rst or markdwon people win. :-)

beutlich commented 4 years ago

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.