Replies: 3 comments 4 replies
-
Thanks for starting the discussion and some proposals. First some questions:
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:
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). |
Beta Was this translation helpful? Give feedback.
-
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.
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
In my view the most suitable form is a InformationObject that has various formatters that the front-end can choose to use.
Ok, then I guess we need to wait on these things. |
Beta Was this translation helpful? Give feedback.
-
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
Once I have this, I am going to rebase #223 and start splitting it into smaller PRs (changing 5 files at the time). |
Beta Was this translation helpful? Give feedback.
-
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)
while:
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: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 asInformation[symb, LongForm->False]
andInformation[symb, LongForm->True]
. In older versions,Information
used to evaluate toNull
after printing the usage string and other information according to the options.In the current version,
Information
evaluated toInformationData[Association[...], longformvalue]
with the inner association including different kinds of information, andlong-form value
a boolean value specifying if the information should be shown in its long or short form: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 ofInformation
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:
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:Information
is formatted using the methodInformation.format_definition
. To do this, first calls the internal functionmathics.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 correspondingDefinition
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 classmathics.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 parameterhtmlout
.Once the
usage
string is synthetized, it is shown as aprint_out
message. Then, if theLongForm
was asked, the attributes and all the (user defined) rulesassociated 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 theusage
string. In WMA, it works in this way. If this is the case, we do not need asummary_text
field: we can synthesize it from the docstring. Also, we can use thesummary_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 colorsrepresents 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 theusage
string using WL boxes.For example, in WMA,
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?'
must sourround the full expression or just the symbol in the<dt>
entries?<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.
Beta Was this translation helpful? Give feedback.
All reactions