Start writing new documenation/readme.

[jaykrell]

This documents many things in one small document,
and needs work.

In my opinion the documentation should gloss over
the m3cc and integrated backends and focus on the C backend.

A goal should be to get anyone up and running fast as possible,
with the lowest failure rate, working from "source" (generated)
or binaries.

The .sh and .cmd scripts should be ignored as well.

The .py scripts are even barely useful to a begginer.
I suppose the primary use case, really, is iterating in on directory,
in which case cd around and run cm3 devolves to cd once and run cm3.

However the scripts should be documented for people working on the
system. And still, we should try to move toward quake, I think.

[ghost]

I like the current README, short and to the point. But this is good information that should be in the repo. It would have been helpful to me had I discovered it earlier, and I still learned a few new points today. Sure it's not polished, but there's value in just getting the documentation effort going in some form.

I'm propose that you add this at the root, not replacing the README, but as a second file, maybe AN.OVERVIEW. (I'm stealing the filename from Mythryl, b/c I like it's documentation, but it's just a suggestion.)

Anyway, not too attached to any of the details. This is a good starting point. We should start.

[jaykrell]

The word Extent is hard to read. Existing?

[ghost]

I guess the word you want there is "Extant", but the whole thing could possibly be reworded as

Existing implementation compile ahead-of-time to native code.

(Because apparently what compilers have done for decades is now a special thing with its own lingo.)

[jaykrell]

1. "ahead of time" ugh. It is called "compiling". I won't say much right about this termonology I am tired and grumpy. :)
2. I don't like the current README. You can see mine is based on it, but I don't like that it points people to the.sh files and I like that I at least tried to explain various ways to run them (.py and .sh do about the same). Maybe allude to the .sh files for the unusual systems without .py.

Aside not for docs:
I have py2 on OSF1.
I have py3 but not current on OSF1.
Porting to py3 is challenging.
I would like to try bringup on DOS maybe.
Point is though. py2 and perhaps py3 are pretty darn portable, the space that needs .sh is pretty small imho.
We could offer py -fake that writes out the commands, perhaps.

Or has been said many times, rewrite the scripts in quake or mod3, but I don't know, I am torn.

[ghost]

The scripts have definitely been a point of confusion for me. I recognize that the python scripts are there for portability, but I'm so used to shell that they're a bit foreign.

I like the idea of rewriting them in quake, but I don't know enough yet to know how practical that is. Of course there would still have to be some sort of bootstrap process.

I saw somewhere quake being compared to scons. I don't know scons, but the scripts always remind me of cmake, which gives me the idea of organizing/modularizing them in the same style. But I'm getting in way over my head.

But yes it's a mess, there will always be tension between "it works for me" and "it needs to be portable", and some sort of native/built-in solution may be the best way to resolve that.

For now just cataloguing what's there is a help.

And I get the grumpy. :)

[VictorMiasnikov]

We "have py2 on" on DOS , but we do not have py3 ( I found working py2, but do not found py3)

[jaykrell]

This should highlight the m3cg directory and parse.c

[jaykrell]

Maybe throw in vernacular like "kitchen sink" or "batteries included", "other systems call it that".

[ghost]

• "all" is everything, batteries included

to be followed by a list. I can try to put together that list.

[jaykrell]

I am not sure the list is important, but to allude to it already being mentioned, "gui library", "browsers (not very good ones, but demos", "games (tetris)", Obliq, Mentor...maybe with links to papers .... presenting hierarhical information is always an exercise in how deep to go though... links certainly helps, I would not detail obliq and mentor but maybe link. They are kinda cool.

It is tough, you know, the system, the "installers", and the documentation, tries to be all things to all people, just what one wants. Providing sockets+stdio does satisfy a large group, but not everyone. You need gui to capture some people. etc. The group satisifed with sockets+stdio might complain about the large size of all.. no great answer, but I sorta tried, or rather I mostly copied what Olaf did, possibly misunderstanding it, and doing less (I am not sure he had overlap, and he had other groups like std, I tried to reduce things for a simpler story, but ultimately if you take a Debian-like perspective, what I did is quite bad..there should be no overlap....)

[jaykrell]

List boot2-full.py or such here? I forget, need to check.

[mikanystrom]

It's optionally unsafe, not optionally safe! (You need to specifically ask for the unsafe part, is what I mean---if you don't ask, it's safe.)

…

On Thu, Sep 16, 2021, 12:20 PM Eric Sessoms ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In README-new.txt <#152 (comment)>: > @@ -0,0 +1,209 @@ += The language + +Modula-3 is an optionally safe systems programming language. + It has garbage collection (for the optionally safe part). + Extent implementations are compiled statically to native code. I guess the word you want there is "Extant", but the whole thing could possibly be reworded as Existing implementation compile ahead-of-time to native code. (Because apparently what compilers have done for decades is now a special thing with its own lingo.) — You are receiving this because your review was requested. Reply to this email directly, view it on GitHub <#152 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABKYNJMJK3E3B7MF4F76SKLUCHAHFANCNFSM4ZDVFKZA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[jaykrell]

It's optionally unsafe, not optionally safe! (You need to specifically ask for the unsafe part, is what I mean---if you don't ask, it's safe.)

I didn't mean to imply what is the default, just that both are options.
It can be reversed, sure. I get that safe is the default.
Having both options, no matter the default, is somewhat unusual. esp. in 1996, esp. with a "unified syntax" (i.e. not counting Java JNI, but Rust and C# do qualify, very worth contenders..)

[ghost]

It's optionally unsafe, not optionally safe! (You need to specifically ask for the unsafe part, is what I mean---if you don't ask, it's safe.)

Well, that is a very good point.

My motivation for revisiting this pull request is that I'm new and just learning this system. (A couple of years experience with Oberon, about 2-weeks with Modula-3.) And as a newbie, it's a very good time for me to be writing things down as I learn them, before it all becomes implicit knowledge and I forget that it was something I ever had to learn.

So I was hoping to have this added as a starting point, assuming I would be editing it and adding to it as I learn. I'm not looking for "done" documentation. I should have been more explicit.