Before drawing a plan for improving the documentation system

[mmatera]

One of the big pending we have in the Mathics project is to improve the documentation system, making it at a time more maintainable and more compatible with the one WMA.

In WMA, the way to obtain inline help is through the Information symbol. Writing ? symbol a short textual description of what the symbol means and does is presented. On the other hand, calling ?? symbol produces an extended version of the symbol description, including its attributes and user definitions.

For example, (in the notebook interface)

In[1]:= ?Plus
Out[1]= x + y + z represents a sum of terms.

while:

In[2]:= ??Plus 
Out[2]= x + y + z represents a sum of terms.

 Attributes[Plus]={Flat, Listable, NumericFunction, OneIdentity, Orderless, Protected}

By default, the first line in both cases shows the ::usage message associated with the symbol. For this reason, if we unprotect the symbol and assign another usage string, ? and ?? are going to show the customized message:

In[3]:= Unprotect[Plus]; Plus::usage="represents the addition of the arguments";
In[4]:= ?? Plus 
Out[4]= represents the addition of the arguments

 Attributes[Plus]={Flat, Listable, NumericFunction, OneIdentity, Orderless, Protected}

The way in which ? and ?? were implemented in different versions of WMA have been changed since v. 5. However, since that version, ? symb and ?? symb have been parsed respectively as
Information[symb, LongForm->False] and Information[symb, LongForm->True]. In older versions, Information used to evaluate to Null after printing the usage string and other information according to the options.
In the current version, Information evaluated to InformationData[Association[...], longformvalue] with the inner association including different kinds of information, and long-form value a boolean value specifying if the information should be shown in its long or short form:

In[5]:= ? Information[Plus] // FullForm
Out[5]= InformationData[Association[Rule["ObjectType", "Symbol"], Rule["Usage", "represents the addition of the arguments"],
        ...,
Rule["FullName", "System`Plus"]], False]

Note: in v12.2, for the command-line interpreter, there is no difference between ? and ??. The difference becomes apparent just in the notebook interface. This is not what happens before (let's say, in v. 10.1, which was the one I used as a model for the initial implementation of Information in Mathics).

Apart from the inline help, there is also very extended and exquisitely organized documentation.

How documentation is organized in Mathics

In Mathics, we have a smart -but old fashioned- way to produce a pdf and an on-demand documentation for the web interface, based on the doc-strings of the builtin classes.
To work properly, the doctrine should have the following format:

"""
    <dl>
       <dt> $a$ + $b$ + $c$
       <dt> 'Plus[$a$, $b$, $c$,...]'
           <dd> represents the sum of $a$, $b$, $c$, ... terms
    </dl>

    text of description with examples and "doctests":
    >> 1 + 2
     = 3

    and more explanations...
"""

There is the first part between HTML definition list tags ( <dl> </dl>) that include a description of a basic syntax (tagged by <dt> and surrounded by single quotes ' ) followed by a short explanation (tagged by <dd>). Symbols names and expressions are surrounded by $$, and strings by double-quotes ($"string"$).
After this, there is a second part with a more detailed explanation and examples. These examples are also used as "doctests".

The class mathics.doc.MathicsMainDocumentation uses this information to produce both the HTML and the PDF help files with the documentation of the project.

Regarding the inline help, there is also a built-in Information symbol, but with a slightly different implementation. In Mathics, Information is not evaluated, but kept as a literal that, when formatted, prints the documentation:

In[1]:= Information[Plus, LongForm->False]
addition of numbers, lists, arrays, or symbolic expressions
Out[1] Null

In[2]:=%
addition of numbers, lists, arrays, or symbolic expressions
Out[2] Null

In[3]:=% //FullForm
Out[3] Information[Plus, Rule[LongForm, False]]

Information is formatted using the method Information.format_definition. To do this, first calls the internal function mathics.atoms.symbols._get_usage_string
which looks for the usage message associated to the symbol. If this message was not set, and the symbol is a builtin symbol, looks into the associated builtin class.
If we asked for a short form, first look for a summary_text property. If this is set, returns the summary text.

Note: with the last changes, this would never happend, because if the class have this property, then the usage message was set when the corresponding Definition was built.

If it was asked for a long form, or the summary was not there, it will try to synthetize the usage message from the docstring of the class. To do this, the class mathics.doc.common_doc.XMLDoc class is used. Using this class, the description list part of the docstring is converted into HTML or into text depending on the value of the parameter htmlout.

Once the usage string is synthetized, it is shown as a print_out message. Then, if the LongForm was asked, the attributes and all the (user defined) rules
associated to the definition are also printed.

Discussion

Apart from some possible cleaning and DRY, and tons of typos and grammar errors, to avoid increasing the messiness, we need to take certain policy definitions to go on with the documentation.

The first one would be if we want all the information in the <dl> section of the docstrings in the usage string. In WMA, it works in this way. If this is the case, we do not need a summary_text field: we can synthesize it from the docstring. Also, we can use the summary_text with other proposals, let's say, for tooltip help, which we could support in the future. According to my experiments, this kind of text could be also synthesized based on the subtype of builtin, the docstring, and certain properties of the class (most of the summary texts in constants are of the form "is the <class name> constant", for colors represents the color <<class name>>, etc).

The second question is whether we want to set the usage string when the definitions are built, or if we want to do that on the fly. The reason to do it on the fly is that we can process HTML. The reason for do not do that is that we can perfectly store the format information for the usage string using WL boxes.

For example, in WMA,

In[1]:= Table::usage //FullForm                                                 

Out[1]//FullForm= "\!\(\*RowBox[{\"Table\", \"[\", RowBox[{StyleBox[\"expr\",\..."

Finally, there are several style aspects that would be nice to state, to make the appearance consistent throughout the documentation:

• <dt> and <dd> should be closed?
• the ' must sourround the full expression or just the symbol in the <dt> entries?
• when use represents / is / gives / returns at the begining of the <dd> entries?

Once we have this, we can use several automatic tools to check the style, the spelling and grammar of all the documentation in an automatic way.

[rocky]

Thanks for starting the discussion and some proposals.

First some questions:

• Where is ::usage documented?
• What is the type of the built-in "usage" for say GeoPosition[], e.g. Head[GeoPosition::usage]?
• In your example in changing ::usage, you assigned a string. Can the assignment be in some sort of markup language? If so which? Is HTML valid?

Next some observations, or maybe more accurately, a rant. This code has a lot of boneheaded features. That is things that are wrong and stubbornly wrong which we have amplified greatly. And there are too many of these that we (or at least I) can't fix all at once. So I have been prioritizing. Execution speed right now is going to be my focus until we have that more under control and hopefully fixed.

The homegrown documentation system, which was always somewhat incomplete and inadequate, didn't have to be custom even from the time that it was written. Yes, it is kind of cool the way it hooks into Django and has autocomplete and searching. But even back when it was written, sphinx, rst, and doctest were around. Those should have been hooked into and used where possible. Unit tests were around too and those should have been used more extensively.

And this is called XML when it kind of isn't because of the missing end tags and lack of a style sheet. (Well, possibly the XML style should might be able to allow missing end tags). Does WL also call this stuff XML?

Unless WL supports HTML or XML in this way, I'd prefer to ditch it than try to limp it along. And if WL supports HTML or XML and calls its Information markup XML (as opposed to HTML), then we should be looking at existing HTML or XML packages already written in Python rather than writing more custom code. So in sum, unless there is some sort of precedent in Mathematica for this garbage, I don't like the idea of writing custom spelling and style checkers for our custom document tagging system.

With respect to how Mathematica/WL has changed over the years, ok, so that's a partial explanation of the mess. I think what we do now though seems to be that we are targeting WL as it is now. So this would mean Information should return something other than None.

Personally I'd like to see compatibility packages as add-ons to support features from prior versions which might accommodate some of the old behavior we seem to have now. But that is more an aspiration than something that is likely to happen in my lifetime. Especially since that it is hard for us to pick a problems and tackle them.

To end with some successes:

• we now support current packages and languages rather than Python 2, Django 1, threejs and Sympy sometime from years ago.
• we have the ability to get out more than one release a year and that the code has been split into separate projects which are worked on more or less independently

I'd like to see more successes, like the inefficiency problem or being able to handle a complex package like Rubi or KnotTheory; (A mini running combinatorica is encouraging).

[rocky]

Just to be clear - although I dislike the homegrown document system and don't think we should be extending that, the documentation content is a different matter. No matter how the documentation is tagged, the descriptions and examples will largely be the same. So filling that out is not a dead end.

[mmatera]

OK, let's go with some of these things:

* Where is `::usage` documented?

Actually, this probably should be documented in Messages and in Information. However, as it is not a symbol, it does not have its own documentation...

* What is the type of the built-in "usage" for say `GeoPosition[]`, e.g. `Head[GeoPosition::usage]`?

The GeoPosition is not even implemented right now. Also, in WMA 12, Information can work over many kind of structures, but what we have implemented just works over symbols. For the case of a symbol, you want to show the usage string, but for other structures, probably you need a specific implementation.
symb::usage = rhs just accepts ar rhs strings. These strings can be "formatted" strings containing escape sequences with block structures (see issue #245). If not set (like in GeoPosition, both in Mathics and WL), symb::usage//Head evaluates to MessageName, just because symb::usage stays unevaluated in that case.

* In your example in changing `::usage`,  you assigned a string. Can the assignment be in some sort of markup language? If so which? Is HTML valid?

Actually, the right thing should be to assign a box structure, as in the example of Information[Table]

Next some observations, or maybe more accurately, a rant. This code has a lot of boneheaded features. That is things that are wrong and stubbornly wrong which we have amplified greatly. And there are too many of these that we (or at least I) can't fix all at once. So I have been prioritizing. Execution speed right now is going to be my focus until we have that more under control and hopefully fixed.

I started with this because is something that shouldn´t interfere with the core refactor. So, the plan here is not to rework all the help system, but just decide if we want to have a summary_text apart from the docstring or not, and what should be the standard format for these attributes.

The homegrown documentation system, which was always somewhat incomplete and inadequate, didn't have to be custom even from the time that it was written. Yes, it is kind of cool the way it hooks into Django and has autocomplete and searching. But even back when it was written, sphinx, rst, and doctest were around. Those should have been hooked into and used where possible. Unit tests were around too and those should have been used more extensively.

In a second round, I could see to translate the current homegrown docstring format to something more standard. The homegrown format is simpler enough to make easy the translation.

And this is called XML when it kind of isn't because of the missing end tags and lack of a style sheet. (Well, possibly the XML style should might be able to allow missing end tags). Does WL also call this stuff XML?

Actually, it is HTML. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl

Unless WL supports HTML or XML in this way, I'd prefer to ditch it than try to limp it along. And if WL supports HTML or XML and calls its Information markup XML (as opposed to HTML), then we should be looking at existing HTML or XML packages already written in Python rather than writing more custom code. So in sum, unless there is some sort of precedent in Mathematica for this garbage, I don't like the idea of writing custom spelling and style checkers for our custom document tagging system.

Yep, we can do that, but after deciding what kind of format is the most suitable for this.

With respect to how Mathematica/WL has changed over the years, ok, so that's a partial explanation of the mess. I think what we do now though seems to be that we are targeting WL as it is now. So this would mean Information should return something other than None.

OK, but the last version of WMA has a lot of features that we do not cover, and hence, there are features that are not so useful. As I mentioned before, Information does not returns Null, but just it keeps unevaluated. What returns Null is MakeBoxes[Information[...],...]

Personally I'd like to see compatibility packages as add-ons to support features from prior versions which might accommodate some of the old behavior we seem to have now. But that is more an aspiration than something that is likely to happen in my lifetime. Especially since that it is hard for us to pick a problems and tackle them.

To do that, we need a more or less stable core, or at least its interface. Otherwise, we make the project still harder to maintain.

To end with some successes:

* we now support current packages and languages rather than Python 2, Django 1, threejs and Sympy sometime from years ago.

* we have the ability to get out more than one release a year and that the code has been split into separate projects which are worked on more or less independently

I'd like to see more successes, like the inefficiency problem or being able to handle a complex package like Rubi or KnotTheory; (A mini running combinatorica is encouraging).

The same as before, complex packages, in general, require built-in-ins that rely on details of the low-level implementation and becomes very fragile against changes in the core.

[rocky]

The GeoPosition is not even implemented right now.

I don't understand. https://reference.wolfram.com/language/ref/GeoPosition.html is listed. But okay how about Part then. the main idea is what happens when there are several forms.

Actually, the right thing should be to assign a box structure, as in the example of Information[Table]

I don't think so. I think the variable value shown is the result of formatting some other data or object. A more sane thing would be to have some sort of Information object creation as is done with TimeObject[].

Yep, we can do that, but after deciding what kind of format is the most suitable for this.

In my view the most suitable form is a InformationObject that has various formatters that the front-end can choose to use.

To do that, we need a more or less stable core ..
The same as before, complex packages,

Ok, then I guess we need to wait on these things.

[mmatera]

The GeoPosition is not even implemented right now.

I don't understand. https://reference.wolfram.com/language/ref/GeoPosition.html is listed. But okay how about Part then. the main idea is what happens when there are several forms.

In Mathics, I meant.

Actually, the right thing should be to assign a box structure, as in the example of Information[Table]

I don't think so. I think the variable value shown is the result of formatting some other data or object. A more sane thing would be to have some sort of Information object creation as is done with TimeObject[].

InformationData is the name for it in WL. In any case, one thing is the return value of Information and a different thing is the value of symb::usage.
In WL, formatted text is stored as (string representations of) box structures (see this entry in WL), so it makes perfect sense to use them in usage strings.
For instance, in WMA, you can do

MySymbol::usage="\!\(\*GridBox[{{\"Q[symb]  \"},{\"\t what MySymbol does\"}}]\)"

then, the expression is shown as

In[10]:= ?? MySymbol                                                                                                                                                                   

Out[10]= MySymbol[symb]  

         	 what Q does

In Mathics we still do not have a complete implementation for strings representing boxes, but it is something to do in the future. The advantage of doing this is that box expressions can be interpreted to build HTML code if you need it in the web interface or as plain text in the command line interface.

Yep, we can do that, but after deciding what kind of format is the most suitable for this.

In my view the most suitable form is a InformationObject that has formatter associated with it that the front-end can choose to use.

Yes, the InformationData should have an associated MakeBoxes definition, but the usage strings should also have a specific formatter.

To do that, we need a more or less stable core ..
The same as before, complex packages,

Ok, then I guess we need to wait on these things.

[mmatera]

In any case, to avoid large changes which require extensive revision work, (if all agree) I am going to complete the work in #223 (locally) by

• changing the default value of all the summary_text symbols to an empty string.
• passing all the remaining summary_text by the spelling checker.
• Using the following style for different classes of builtins:
  • (generic) Builtin: "gives ..."
  • (commands) Builtin: "does ..."
  • (iterators) Builtin : "iterate ..."
  • (numerical constants) Predefined: "`` <> with approximate value <>"
  • _Color : "The color <<color_name>>"

Once I have this, I am going to rebase #223 and start splitting it into smaller PRs (changing 5 files at the time).

[rocky]

Thanks for your patience and understanding.