New README

[Waldek Hebisch]

I have put at:

http://www.math.uni.wroc.pl/~hebisch/fricas/README

candidate for new README. A slightly longer alternative
candidate:

http://www.math.uni.wroc.pl/~hebisch/fricas/README2

It is hopefully correct .rst, but before commiting it I keep
name without extension.

I tried to keep it short. I would be good to give short
summary of FriCAS capablities, I tried to do this in
README2. But is hard to do without writing a lot or
assuming that readers know a lot (and for readers that know
a lot, short summary probobably is not needed). So
I will probably go with README and not README2. Anyway,
if you think that there is something that we really should
have in README, but is not there, then please tell me.
And of course corrections are welcome.

--
Waldek Hebisch

[Ralf Hemmecke]

> http://www.math.uni.wroc.pl/~hebisch/fricas/README

Thank you.

I've slightly modified it and have temporarily put it to my wip/rstdoc
branch.

https://github.com/hemmecke/fricas/tree/wip/rstdoc

I have kept the link to INSTALL, but I hope that eventually INSTALL will
only contain

====
See src/doc/sphinx/source/install.rst or
http://fricas.github.io/install.html.
====

And we can eventually improve this
https://hemmecke.github.io/fricas/install.html
(or rather the corresponding .rst file).

In my version of the README, I use "statically typed" instead of
"strongly typed".

I have a strong desire to put "static" here (in contrast to dynamic).
"strongly typed" doesn't seem to be sooo clear according to

https://stackoverflow.com/questions/2690544/what-is-the-difference-between-a-strongly-typed-language-and-a-statically-typed

or

https://stackoverflow.com/questions/2351190/static-dynamic-vs-strong-weak

If I look at what they write in the first reference than with our
"pretend" keyword, SPAD would be weakly typed.

> A slightly longer alternative candidate:
>
> http://www.math.uni.wroc.pl/~hebisch/fricas/README2

> It is hopefully correct .rst.

If you do not want a program like "retext" you can commit it to a
temporary git branch, 'foo' say, push it to github and then look how
github shows the text. It's easy to remove the branch from github via

git push origin :foo

You just shouldn't indent the itemized stuff. But it wouldn't hurt too
much in this case.

> I tried to keep it short. I would be good to give short summary of
> FriCAS capablities, I tried to do this in README2. But is hard to do
> without writing a lot or assuming that readers know a lot (and for
> readers that know a lot, short summary probobably is not needed).

I would prefer writing it without that list. Such a list is always too
short and it is too hard to please potential users.

However, I have added "general purpose" to the first line. That should
be an important distinction from specialized CAS.

Ralf

[Waldek Hebisch]

On Sun, Apr 18, 2021 at 05:34:36PM +0200, Ralf Hemmecke wrote:
> > http://www.math.uni.wroc.pl/~hebisch/fricas/README
>
> Thank you.
>
> I've slightly modified it and have temporarily put it to my wip/rstdoc
> branch.
>
> https://github.com/hemmecke/fricas/tree/wip/rstdoc
>
> I have kept the link to INSTALL,

Well, will look at INSTALL too, but README is shorter...

> but I hope that eventually INSTALL will
> only contain
>
> ====
> See src/doc/sphinx/source/install.rst or
> http://fricas.github.io/install.html.
> ====
>
> And we can eventually improve this
> https://hemmecke.github.io/fricas/install.html
> (or rather the corresponding .rst file).
>
> In my version of the README, I use "statically typed" instead of
> "strongly typed".
>
> I have a strong desire to put "static" here (in contrast to dynamic).
> "strongly typed" doesn't seem to be sooo clear according to
>
> https://stackoverflow.com/questions/2690544/what-is-the-difference-between-a-strongly-typed-language-and-a-statically-typed
>
> or
>
> https://stackoverflow.com/questions/2351190/static-dynamic-vs-strong-weak
>
> If I look at what they write in the first reference than with our
> "pretend" keyword, SPAD would be weakly typed.

IMO "strongly typed" is better. There are at least as strong
objections to "statically typed" (namely our types are runtime,
that is dynamic thing). I think that some fuzzines of
"strongly typed" sends right message. And I am not too concerned
by formal definitions that some people make: using formal
definitions one can conclude that the only trurly "safe"
language is machine language.

> > A slightly longer alternative candidate:
> >
> > http://www.math.uni.wroc.pl/~hebisch/fricas/README2
>
> > It is hopefully correct .rst.
>
> If you do not want a program like "retext" you can commit it to a
> temporary git branch, 'foo' say, push it to github and then look how
> github shows the text. It's easy to remove the branch from github via
>
> git push origin :foo
>
> You just shouldn't indent the itemized stuff. But it wouldn't hurt too
> much in this case.

Hmm. I actually run 'sphinx-build' and looked at resulting
.html. Without indent itemized stuff was mangled. With
indent it looked OK.

> > I tried to keep it short. I would be good to give short summary of
> > FriCAS capablities, I tried to do this in README2. But is hard to do
> > without writing a lot or assuming that readers know a lot (and for
> > readers that know a lot, short summary probobably is not needed).
>
> I would prefer writing it without that list. Such a list is always too
> short and it is too hard to please potential users.
>
> However, I have added "general purpose" to the first line. That should
> be an important distinction from specialized CAS.

We say this later, but we may also put this in the first line.

--
Waldek Hebisch

[Kurt Pagani]

On 18.04.2021 17:34, Ralf Hemmecke wrote:
>> http://www.math.uni.wroc.pl/~hebisch/fricas/README

...

>
> https://stackoverflow.com/questions/2351190/static-dynamic-vs-strong-weak
>
> If I look at what they write in the first reference than with our
> "pretend" keyword, SPAD would be weakly typed.
>

I'm advertising for 'strongly typed'. First of all, we claim it in
https://en.wikipedia.org/wiki/FriCAS and second - following the link:

"""
Generally, a strongly typed language has stricter typing rules at compile time,
which implies that ...
"""

That's just what we find, don't we? Using "pretend" should be last resort.

...
> Ralf
>

[Ralf Hemmecke]

>> In my version of the README, I use "statically typed" instead of
>> "strongly typed".
>>
>> I have a strong desire to put "static" here (in contrast to dynamic).
>> "strongly typed" doesn't seem to be sooo clear according to
>>
>> https://stackoverflow.com/questions/2690544/what-is-the-difference-between-a-strongly-typed-language-and-a-statically-typed
>>
>> or
>>
>> https://stackoverflow.com/questions/2351190/static-dynamic-vs-strong-weak
>>
>> If I look at what they write in the first reference than with our
>> "pretend" keyword, SPAD would be weakly typed.
>
> IMO "strongly typed" is better. There are at least as strong
> objections to "statically typed" (namely our types are runtime,
> that is dynamic thing).> I think that some fuzzines of "strongly typed" sends right message.

Well, for me "stong" does not tell me anything, "static" does.

We should maybe rather be more precise and mention "parametric dependent
types" in the README. What we create at runtime are the actual instances
of (parametric) types. Still everything is type-checked at compile-time.

To find a better compromise, maybe we avoid "static" and "strong"
altogehter and rather replace it with their meaning in the context of
SPAD, i.e., a SPAD program must be type-correct at compile-time.
It's a bit tricky with IntegerMod(n) when n is a variable. Aldor
requires that n is constant for such cases.

People not knowing what "strongly-typed" is might search here
https://en.wikipedia.org/wiki/Strong_and_weak_typing

Does that really reflect THE distinguished feature of FriCAS.
Personally, I like very much that I know that when my program can be
compiled that there are at least not typing errors in it.

Maybe we can agree on "strongly and statically typed". ;-)

>>> It is hopefully correct .rst.
>>
>> If you do not want a program like "retext" you can commit it to a
>> temporary git branch, 'foo' say, push it to github and then look how
>> github shows the text. It's easy to remove the branch from github via
>>
>> git push origin :foo
>>
>> You just shouldn't indent the itemized stuff. But it wouldn't hurt too
>> much in this case.
>
> Hmm. I actually run 'sphinx-build' and looked at resulting
> .html. Without indent itemized stuff was mangled. With
> indent it looked OK.

README.rst will not go through sphinx. I is just rendered by github.

And as for bulleted lists ...

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists

Ralf

[Ralf Hemmecke]

> I'm advertising for 'strongly typed'. First of all, we claim it in
> https://en.wikipedia.org/wiki/FriCAS

Then we should change the Wikipedia entry and replace it with the first
of the following two.

https://en.wikipedia.org/wiki/Type_system#Static_type_checking

https://en.wikipedia.org/wiki/Type_system#Strong_and_weak_type_systems

Ralf

[Waldek Hebisch]

I wanted to avoid useless talk in the README. I am affraid that
"parametric dependent types" does not tell much for many our
potential readers. And some folks may understand it wrong.
Formally it can be argued that Spad type system is in its own
category, different from usual dynamic/static distinction.
Namely types are runtime objects but are associated with
variables. Usual dynamic typing associates types with data,
which is quite different. OTOH, classic static type system
require all type info to be compile-type computable. SML
and followers weakens compile-type computable to compile-type
checkable, but stil requires that one can discard type info
before runtime. Spad is mostly compile-time checkable, but some
checks must be done at runtime and more importantly, types
are needed at runtime.

Concerning word "strongly": it is fuzzy, but has meaning.
And I wrote, fuzzines is exactly what I want here: it
alows concise statement, without lying and without need
for lengthy disclaimers. I am affraid that I can not
do much for folks that need to look up Wikipedia for
"strong typing". We probably could provide better
explanation about role of types in Spad programs, but
not in README. When I say better I mean both better
than our current explantations about types and better
matched to Spad than general references.

> >>> It is hopefully correct .rst.
> >>
> >> If you do not want a program like "retext" you can commit it to a
> >> temporary git branch, 'foo' say, push it to github and then look how
> >> github shows the text. It's easy to remove the branch from github via
> >>
> >> git push origin :foo
> >>
> >> You just shouldn't indent the itemized stuff. But it wouldn't hurt too
> >> much in this case.
> >
> > Hmm. I actually run 'sphinx-build' and looked at resulting
> > .html. Without indent itemized stuff was mangled. With
> > indent it looked OK.
>
> README.rst will not go through sphinx. I is just rendered by github.

Well, "retext" is claimed to be an editor, I do not want editor,
I want something to check that README does not contain formatting
blunders. Wikipedia says that Restructured Text is "sphinx"
format, so it looked natural to use "sphinx" as checker. If
github (or maybe other "sphinx" version) renders it differently,
then we have a problem...

--
Waldek Hebisch

[Ralf Hemmecke]

> I wanted to avoid useless talk in the README. I am affraid that
> "parametric dependent types" does not tell much for many our
> potential readers. And some folks may understand it wrong.

OK. Let's settle it and let it be "strongly typed".

> Formally it can be argued that Spad type system is in its own
> category, different from usual dynamic/static distinction.
> Namely types are runtime objects but are associated with
> variables. Usual dynamic typing associates types with data,
> which is quite different. OTOH, classic static type system
> require all type info to be compile-type computable. SML
> and followers weakens compile-type computable to compile-type
> checkable, but stil requires that one can discard type info
> before runtime. Spad is mostly compile-time checkable, but some
> checks must be done at runtime and more importantly, types
> are needed at runtime.

Yes, it would make sense to put such information somewhere.
I have written
https://fricas.github.io/fricas-notebooks/FriCAS-Types.html
However, that was more intended for end-users that are not experts in
classification of programming languages.

Maybe it would fit at the very end of it to explain the specific way of
how types are designed in FriCAS. Maybe, it would even be better to have
such information here
https://hemmecke.github.io/fricas/features.html
or as a subpage of it. In fact, the intention of "Features" is to list
all important things of FriCAS. In particular, it might be useful to
list a few things that other CAS do not have, so in some sense that page
might help people writing for wikipedia to easily compare to other CAS.

>> README.rst will not go through sphinx. I is just rendered by github.

> Well, "retext" is claimed to be an editor, I do not want editor,

I just use it for a simple check.

> I want something to check that README does not contain formatting
> blunders. Wikipedia says that Restructured Text is "sphinx"
> format, so it looked natural to use "sphinx" as checker. If
> github (or maybe other "sphinx" version) renders it differently,
> then we have a problem...

I guess that correct .rst files will produce the same output. If
incorrect .rst files give different output in different renderes, that's
not a problem of reStrucutredText. Sphinx should be OK.

See
https://hemmecke.github.io/fricas/_sources/features.rst.txt
and
https://hemmecke.github.io/fricas/features.html
These sources went through sphinx and look OK.

Ralf