Rewrite of technical.md and starting xml-for-om tutorial #44

lars-hellstrom · 2017-09-28T16:58:39Z

One thing left untouched here is the example of a CD symbol definition
(transc1#log). That needs more attention, because the implication given
is wrong (see issue OpenMath/CDs#15), and also it seems to be based on
an older version of the CD (but the error is also in the present CD).

In addition, I've included some OMS URIs such as
http://www.openmath.org/cd/nums1#rational
which currently fail with messages such as
The requested URL /var/www/www.openmath.org/www/nums1.xhtml
was not found on this server.
I think that is a misconfiguration on (the old) www.openmath.org however,
so it probably shouldn't call for a change here.

Also: Urgh, the github help files were not good at explaining what to do. RTF(sugary)M is too much sugar.

One thing left untouched here is the example of a CD symbol definition (transc1#log). That needs more attention, because the implication given is wrong (see issue OpenMath/CDs#15), and also it seems to be based on an older version of the CD (but the error is also in the present CD). In addition, I've included some OMS URIs such as http://www.openmath.org/cd/nums1#rational which currently fail with messages such as The requested URL /var/www/www.openmath.org/www/nums1.xhtml was not found on this server. I think that is a misconfiguration on (the old) www.openmath.org however, so it probably shouldn't call for a change here.

davidcarlisle

looks good thanks, I added some comments inline but I'd not object to accepting the pull request and then doing further edits on the om site if you'd prefer to do it that way.

davidcarlisle · 2017-09-28T19:29:26Z

technical.md

+
+The XML encoding of `OMI`s and `OMF`s can be in hexadecimal as well as decimal, if one wishes to avoid a radix conversion. The binary encoding is base-2 (well, perhaps rather base-256) only. In the case of integers, hexadecimal is signalled with an `x` before the first digit (but after the minus sign, if there is one). White space is ignored, so digits may be grouped. In the case of floating-point numbers, the value is given as an attribute `dec` or `hex` of the `OMF` tag, and the name of the attribute determines which format is used. A `hex` value consists of the 16 hexdigits needed to encode the 8 bytes of a 64-bit IEEE floating-point number (colloquially known as a "double"), whereas a `dec` value is an ordinary decimal fraction with optional exponent part, e.g. `-3.743e4`.
+
+Strings are encoded as explicit characters in the XML encoding (the `<`, `>`, and `&` characters need to be expressed using character entities, since they have special roles in XML syntax), whereas in the binary encoding they are encoded using UTF-8. Bytearrays are raw bytes in the binary encoding, whereas in the XML encoding they are encoded using base64 (so 3 bytes of data are encoded into 4 ASCII characters).


davidcarlisle · 2017-09-28T19:31:16Z

technical.md


-Content Dictionaries (or CDs for short) are the most important, and the most interesting, aspect of OpenMath because they define the meaning of the objects being transmitted. A CD is a collection of related symbols and their definitions, encoded in an XML format. Defining the meaning of a symbol is not a trivial task, and even referring to well-known references can be fraught with pitfalls Formal definitions and properties can be very useful but time-consuming to produce and verbose, not to mention difficult to get right. A symbol definition in an OpenMath CD consists of the following pieces of information:
+In practice, what one typically gets if entering a symbol URI into a web browser is not the formal document that constitutes the content dictionary, but an HTML rendering of it, scrolled to the symbol of interest. (This is because of content negotiation in the communication protocol: the web browser says it prefers to get the resource as HTML, so that is what the server delivers, if it can. More low-level user agents might ask for the information in another form.) Formal content dictionary documents are rather designed to be machine-readable (for example so that they could be used to generate on-line help in an integrated development environment); the concept is abstract, but the standard only codifies an XML encoding for content dictionaries.


we lost content negotiation as the price of moving to github pages if you want the om-xml form you have to use the explicit url ending in .ocd it is no longer available at the "extensionless url"

davidcarlisle · 2017-09-28T19:33:45Z

technical.md


-represents the error which might be generated when an application sees a symbol it doesn't recognise from a CD it thought it knew about.
+Historically there also was an encoding called _prefix_ or _functional_, with a syntax based on LISP. This was never codified in the standard, but the content dictionary pages on the OpenMath website still offers showing OpenMath objects in prefix notation.


Drop this paragraph, the prefix form is something I invented to make a human readable/writable encoding to go into the html presentation (the rendered mathml possibility came later) the original lisp encoding was different and was really lisp so (sin theta) not sin(theta) as in the prefix rendering.

davidcarlisle · 2017-09-28T20:19:42Z

https://openmath.github.io/cd/nums1#rational

works so the URL you mentioned at the start, http://www.openmath.org/cd/nums1#rational , should work once the DNS is configured to use the new site.

Also fixed some markup, added some links, and tweaked some wording.

davidcarlisle reviewed Sep 28, 2017

View reviewed changes

Modified as per @davidcarlisle's comments.

ea9f0fe

Also fixed some markup, added some links, and tweaked some wording.

kohlhase merged commit f040ebe into OpenMath:master Oct 9, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite of technical.md and starting xml-for-om tutorial #44

Rewrite of technical.md and starting xml-for-om tutorial #44

lars-hellstrom commented Sep 28, 2017

davidcarlisle left a comment

davidcarlisle Sep 28, 2017

davidcarlisle Sep 28, 2017

davidcarlisle Sep 28, 2017 •

edited

Loading

davidcarlisle commented Sep 28, 2017


		The XML encoding of `OMI`s and `OMF`s can be in hexadecimal as well as decimal, if one wishes to avoid a radix conversion. The binary encoding is base-2 (well, perhaps rather base-256) only. In the case of integers, hexadecimal is signalled with an `x` before the first digit (but after the minus sign, if there is one). White space is ignored, so digits may be grouped. In the case of floating-point numbers, the value is given as an attribute `dec` or `hex` of the `OMF` tag, and the name of the attribute determines which format is used. A `hex` value consists of the 16 hexdigits needed to encode the 8 bytes of a 64-bit IEEE floating-point number (colloquially known as a "double"), whereas a `dec` value is an ordinary decimal fraction with optional exponent part, e.g. `-3.743e4`.

		Strings are encoded as explicit characters in the XML encoding (the `<`, `>`, and `&` characters need to be expressed using character entities, since they have special roles in XML syntax), whereas in the binary encoding they are encoded using UTF-8. Bytearrays are raw bytes in the binary encoding, whereas in the XML encoding they are encoded using base64 (so 3 bytes of data are encoded into 4 ASCII characters).


		Content Dictionaries (or CDs for short) are the most important, and the most interesting, aspect of OpenMath because they define the meaning of the objects being transmitted. A CD is a collection of related symbols and their definitions, encoded in an XML format. Defining the meaning of a symbol is not a trivial task, and even referring to well-known references can be fraught with pitfalls Formal definitions and properties can be very useful but time-consuming to produce and verbose, not to mention difficult to get right. A symbol definition in an OpenMath CD consists of the following pieces of information:
		In practice, what one typically gets if entering a symbol URI into a web browser is not the formal document that constitutes the content dictionary, but an HTML rendering of it, scrolled to the symbol of interest. (This is because of content negotiation in the communication protocol: the web browser says it prefers to get the resource as HTML, so that is what the server delivers, if it can. More low-level user agents might ask for the information in another form.) Formal content dictionary documents are rather designed to be machine-readable (for example so that they could be used to generate on-line help in an integrated development environment); the concept is abstract, but the standard only codifies an XML encoding for content dictionaries.


		represents the error which might be generated when an application sees a symbol it doesn't recognise from a CD it thought it knew about.
		Historically there also was an encoding called _prefix_ or _functional_, with a syntax based on LISP. This was never codified in the standard, but the content dictionary pages on the OpenMath website still offers showing OpenMath objects in prefix notation.

Rewrite of technical.md and starting xml-for-om tutorial #44

Rewrite of technical.md and starting xml-for-om tutorial #44

Conversation

lars-hellstrom commented Sep 28, 2017

davidcarlisle left a comment

Choose a reason for hiding this comment

davidcarlisle Sep 28, 2017

Choose a reason for hiding this comment

davidcarlisle Sep 28, 2017

Choose a reason for hiding this comment

davidcarlisle Sep 28, 2017 • edited Loading

Choose a reason for hiding this comment

davidcarlisle commented Sep 28, 2017

davidcarlisle Sep 28, 2017 •

edited

Loading