First Skeletal version¶
Armed with the information above we are now ready to draft the first version of this.
Mathics3 built-in symbols are defined by writing a class which is based off of the class Builtin
.
The docstring for this class lists:
The common name for this, if a corresponding match can be found Wikipedia, use that name and link to it.
links to the WMA reference we found before.
If there is a corresponding SymPy, mpmath, or SciPy function, then link to that
A HTML “definition list” to enclose the definition of each form that can appear
User-Oriented Examples.
Undefined
Title Line¶
Here, there is no Wikipedia common name, so we’ll go with the Mathematica-like description “Undefined symbol or value”. The WMA link is put in parenthesis after that. See the next case study Adding Builtin Function KroneckerProduct for an example where we have Wikipedia and SymPy entries.
To start out then we have:
class Undefined(Builtin):
"""
Undefined symbol/value (<url>:WMA: https://reference.wolfram.com/language/ref/Undefined.html</url>)
...
"""
The slightly unusual way we add a link with text is via the XML <url>
tag.
Also, due to current limitations in our homegrown documentation system, the title line has to appear as one unbroken line. To accommodate this, We have arrange pylint
to ignore long lines.
Note: please add the class Undefined
in alphabetic order of class name. At the time of writing, Undefined
comes after Pi
and before Underflow
.
Undefined
Symbol Definition Description¶
Let us fill out the docstring further, the line above with ...
in it.
After the title line, we get to the definition list part where we list the forms that this can appear. Here there is just one form Undefined
:
class Undefined(Builtin):
"""
Undefined symbol/value (<url>:WMA: https://reference.wolfram.com/language/ref/Undefined.html</url>)
<dl>
<dt>'Undefined'
<dd>a symbol that represents a quantity with no defined value.
</dl>
...
"""
We use the pseudo XML <dt>
and <dl>
for the definition. Note
though that we don’t use the end tags: </dt>
and </dd>
although
we could if we wanted to.
Notice that the word Undefined
appears within single quotes: 'Undefined'
. This is markup that tags Undefined
as code. A complete list of homegrown markiup can be found in Documentation Markup.
User-Oriented Examples¶
Now we get to the final part of the docstring consists of informative examples for the Symbol which is getting defined. We will copy an example found in the WMA documentation for this and add an example that shows the attributes.
class Undefined(Builtin):
"""
Undefined symbol/value (<url>:WMA: https://reference.wolfram.com/language/ref/Undefined.html</url>)
<dl>
<dt>'Undefined'
<dd>a symbol that represents a quantity with no defined value.
</dl>
>> ConditionalExpression[a, False]
= Undefined
>> Attributes[Undefined]
= {Protected}
"""
# ...
In a later we will describe in more detail what the lines with >>
and =
below that mean.
Next: