Huge number of typo corrections and grammar improvements across the entire C3 doc site, plus many clarifications and expanded descriptions! #163
Conversation
… to the uninitiated, thus improving (like all such clarity edits no matter how minor) the chances of retaining new users.
…tch the current version of C3 much more closely. Deprecated suffixes are no longer misleadingly suggested. Some improvements to the comment page were also made.
…ge overview, especially adding addition info on where else to go or what else to do for more info, which should help a bit with user retainment and pragmatism.
…he standard library 1st before looking at the compiler if the user needs more info.
…ified. Also, I fixed a few ".." typos to "...".
…les when mentioned.
| 12. `?` suffix operator turns a `fault` into an optional value. | ||
| 13. `!!` suffix panics if the value is an optional value. | ||
| 14. `$defined(...)` returns true if the last expression is defined (sub-expressions must be valid). | ||
| 14. `$defined(...)` returns true if the last expression contained within it is defined. Sub-expressions must also be valid. |
There was a problem hiding this comment.
last expression
Should be
outermost expression
| 18. if-try statements allows you to run code where an expression is a result. | ||
| 19. if-catch statements runs code on `fault`. It can be used to implicitly unwrap variables. | ||
| 18. `if (try ...)` statements run code when an expression is a "valid"/"normal" result (i.e. to handle the "happy path" when working with Optionals). It can be used to implicitly unwrap variables. | ||
| 19. `if (catch ...)` statements run code when an expression is an "invalid"/"abnormal" (`fault`-containing) result (i.e. to handle the "failure path" when working with Optionals). It can be used to implicitly unwrap variables. |
There was a problem hiding this comment.
an expression is an "invalid"/"abnormal" (
fault-containing) result
To
an expression is an "Empty" optional result
| 5. Contracts may be attached to generic modules, functions and macros. | ||
| 6. `@require` directives are evaluated given the arguments provided. Failing them may be a compile time or runtime error. | ||
| 7. The `@ensure` directive is evaluated at exit - if the return is a result and not an optional. | ||
| 7. The `@ensure` directive is evaluated at exit — if the return is a "valid"/"normal" (non-`fault`) result and not an "invalid"/"abnormal" (`fault`-containing) Optional. |
There was a problem hiding this comment.
The
@ensuredirective is evaluated at exit — if the return is a "valid"/"normal" (non-fault) result and not an "invalid"/"abnormal" (fault-containing) Optional.
->
The
@ensuredirective is evaluated at regular exit. If the return is an optional with an "Empty" result, the check is skipped.
| It is important to remember that if we had replaced `$n` with `n` the compiler would have complained. `n <= 1` is not considered to be a constant expression, even if the actual argument to the macro was a constant. This limitation is deliberate, to offer control over what is compiled out and what isn't. | ||
|
|
||
| :::note | ||
| The act of code generation itself will still complete in compile time regardless of whether a macro is run time dependent or not. In that sense all macros could be said to "complete in compile time" when actually understood rigorously and clearly. As such, compile time code generation should not be confused with the run time effects of such generated code. |
There was a problem hiding this comment.
I found this note a bit difficult to read, could you shorten it down a bit perhaps?
| Check if an expression is assignable to the given type, e.g. `Type x = expr;` would be valid. | ||
| `$assignable(<expr>, <Type>)` checks whether an expression is assignable to the given type, meaning that `Type id = expr;` would be valid for some identifier `id`. | ||
|
|
||
| For example, `$assignable("7", int)` tests whether the string `"7"` can be assigned to an `int`. It can't. This isn't JavaScript, thankfully. Such tests are useful for generic code and testing the operating environment, so that modules and macros can behave correctly or at least report errors when incompatibilities are present. |
There was a problem hiding this comment.
Maybe remove the reference to JS. But more importantly, this is largely superseded by the macro @assignable_to which uses $define under the covers. So this part should be removed.
| Includes a file into the current file at the top level. | ||
| Includes a file into the current file at the top level as raw text, resulting in that file's text being compiled as if directly written into the location of the `$include`. | ||
|
|
||
| Often it will be cleaner to `import` a proper module though. Give it some thought. |
There was a problem hiding this comment.
I think this sentence could be removed.
| The `@` warns the reader of a macro call of the possibility that the call may be doing more "magic" or may be more prone to bugs than if the macro lacked the `@`. Thus, unlike most languages, C3 enables the programmer to choose between more safe or more expressive macros and to make that choice immediately clear to the reader. | ||
|
|
||
| A basic swap: | ||
| Note that `$` parameters (unlike `#` and `@body` parameters) do *not* cause a macro to need a `@` prefix, despite what old docs may have misled some users to believe. |
There was a problem hiding this comment.
Maybe skip the reference to the old docs.
| Foo zf = x - 2.0f; // Uses Foo.minus_float | ||
| Foo zi = x - 2; // ERROR: Ambiguous, implicitly cast value matches both overloads. | ||
| Foo zf = x - 2.0f; // Uses `Foo.minus_float`. | ||
| Foo zi = x - 2; // ERROR: Ambiguous. Implicitly casted value matches both overloads. |
There was a problem hiding this comment.
This should be cast, not casted
|
I've gotten a bit with this but not all the way. I wonder how to properly split this one. Maybe squash everything in to a single change and then split it on a per file PR? |
Main PointHey @lerno, thank you for all your time and feedback and praise. 🙂 Anything you want to change or edit is fine with me. Indeed, even if every word I wrote got overwritten by subsequent commits at some point in the future then that is fine, though I may sometimes voice contrary opinions on a case by case basis. Whatever is best for the project is what to strive for. It wouldn't bother me at all if a bunch of other commits were layered on top of mine to change whatever you or other contributors want to change, whether objective or subjective in nature. That's what I meant by of course being open to whatever aggressive edits you or any other C3 contributor wants. I am surprised that you want the commits to be squashed though, whether as one giant commit or as a per page set of ~43 commits. Usually, as far as I have ever discerned, people seem to say that the ideal is for commits to be broken up into atomic units that reflect each individual functional change. That seems to be the standard people try to live up to. Doing so ensures that each choice to change something is accompanied by corresponding comment(s) as to why in each commit and enables individual users to pick and choose which commit patches to apply to their own repos if they latter seek to only keep some specific subset of the changes and not others, which could easily happen if some later set of changes turns out to make some things better and other things worse. If we squash the commits into one giant mudball or ~43 per page commits then the repo will lose that fine grained level of control. Large lists of small commits are not even a real problem for reading through commit lists when you consider the fact that it is generally best to tag major milestones (such as per version or per major change set or even just arbitrary points for ease of reference) and then navigate based on those in part (which, by the way, the docs may benefit from since the versioning right now for docs seems ad-hoc and just roughly follows the most recent version but lagging it). It is indeed a lot of commits but that doesn't seem like a real problem to me. Repo histories should reflect reality and large numbers of small changes happen sometimes and were a good workflow here considering I couldn't predict what you'd want and so making the changes atomic for easier management by cherry picking in the present and/or future seemed (and still seems) best. In fact, I could have shaved probably a full day's work off my edits or more if I had known that you actually would want the changes to just be a big non-atomic mudball for the entire site or per each page. Most of the commits were just typo/grammar/word fixes and the sentences I wrote into the commits to describe them were in fact often more work than the changes themselves, but I wanted to do as nice a job I could to ensure a polite and easy to use submission. There is also the miscellaneous factor of the fact that fine-grained commits make a repo look more active and healthy and hence attract more users over time. That would be yet another benefit of preferring fine-grained commits. Most changes will be small anyway too, so that also is more consistent with most future commits too anyway I'd imagine. I guess I could backup my current repo, wipe it all out, then copy over individual files and make individual commits per page (thus ~43 of them), though that'll make the history mostly meaningless and useless "Changed Is that really what you want though? Side InquiryI also noticed that @joshring tagged this pull request as "pending review" and am not sure why. I only use GitHub off and on and historically have more often kept my code private than contributing to open source, so I am often rusty on using this site. Does @joshring have some additional concerns about the commits here? Anti-AI, Ethics, and Long-Term Participation Considerations (Tangent)Finally, unrelated to the commit list itself, I noticed that Microsoft's automated plagiarism system ("coding assistant") "Copilot" ran itself on my commit list and I was wondering if there is any way to disable that so that those never happen. Honestly, to me, such theft-based "AI" systems (which essentially de facto rob the rest of humanity of the value of their time and labor, like a kind of forced non-consensual digital slavery in essence, which is trying to be forced upon all of us by pervasive astroturfing of the entire internet and suppression of dissent (etc), all for the shortsighted profits of a tiny number of low/no empathy people (a.k.a. "sociopaths") who control and develop such systems) are a microcosm of everything that has gone wrong with tech and indeed of our entire society in recent years. Besides the blatantly unconscionable nature (the complete absence of both short-term and long-term ethical foresight) of such automated plagiarism systems though, they also are a quality control and information integrity nightmare, etc. This makes me wonder also what the C3 team's stance on such automated theft and pervasive privacy and personhood violations is. I have constantly been on the lookout lately for communities that are firmly 100% anti-AI regarding such plagiarism/theft/disenfranchisement engines (as I am) and frankly find it very hard to conscience any environment where such things are used and treated as if they are "just a tool" when in reality it is overwhelmingly obvious that it is basically the most unethical thing ever made in the history of the entire software industry, besides (arguably) software that directly serves harmful causes such as gambling or warfare. There has also been the very telling and horrifying pattern in recent years of people in some software companies now being forced to use such automated plagiarism systems regardless of whether they want to even, which speaks volumes of the magnitude of just how hard the companies behind them are trying to force the public to accept and integrate such inherently and irreparably unethical "tech" into our lives, all for the sake of them not losing their multi-billion dollar investment on it all and to create the conditions necessary for them to steal more of the rest of human creativity and labor than they have ever managed to before. I do not consider any of that to even be a "political" stance but rather to merely be a basic human rights stance, very much akin to other things that need to be universally recognized such as basic freedom of speech and the right not to have one's belongings stolen or one's home invaded or one's identity impersonated or to be mugged while walking down a street. The advent of such "AI" has honestly felt like being constantly violated at every second of every day and there is almost nothing I wish for current more than an end of that feeling, as it has sucked so much joy out of the entire world of tech and darkened the future of how things may turn out so deeply. So, my point in this tangent is, is the C3 community one that has enough of a grasp of ethics and respecting human rights in these regards that I can live with making lots more long-term contributions here or would I be better off elsewhere. I'm not really kidding about that even. If I had to choose between (1) using "AI" and (2) abandoning all my hopes and dreams and my entire life of investing most of my time and aspirations in tech and programming and living poor and destitute until the very end or even facing a firing squad then I literally would chose #2. I am not joking or being hyperbolic about that. I also recall how hard artists work back when I worked a AAA game dev job and that makes it even more unpalatable to see all this destructive systematic exploitation becoming so prevalent and so rationalized. There's also countless other problems with it like environmental destruction and pervasive manipulation and control of news and what's visible on search results in order to suppress people's sense of the scale of things and how little actual approval for it there was/is for it that they are trying to force to go away by sheer information control and groupthink inducement by making it seem far more inevitable and approved of than it actually is. I am above all a person of principles and I want to know if you (the C3 team and contributors) are to a sufficient extent as well. Because, if I go all-in on trying to build projects on top of C3 for the next few years I want it to be morally conscionable and that could be influenced greatly by how much/little the C3 community embraces automated plagiarism systems such as these new "AI". The less the better in my "opinion" (though I would more say my moral imperative, so greatly do I feel about it). Anyway, thanks for reading and sorry for my verbosity. Verbosity is kind of just a facet of how I am. Those are just my honest thoughts on it all and I figure that honesty + tact is the best policy in general in life. See you guys and gals around and have a great weekend and upcoming week above all! 🏝️🏄️🌃 |
|
Hello again everyone. I hope you all had pleasant weeks and have been enjoying your weekend so far as well! Anyway, to update: I haven't done any more work on the C3 docs at all nor on any other C3 code in the time since I first submitted this commit list (on 2025-08-13, so approximately 10 days). Besides the obvious reason that I don't know what to do to move forward with the current commit batch until @lerno and/or @joshring indicate such, I also have honestly been demotivated/deflated by my heightened wariness and my wanting to be more assured of how far I should go in terms of investing my time on future C3 contributions and/or personal project work. In recent years I have all too often been stuck in a state of (often self-defeating) tension on such things and on my difficulty reconciling my very strict principled stances on things with the pragmatics of only a handful of options plausibly fitting my criteria even existing (such as C3 and a few others). I also am completely in the dark as to where this puts me relative to the other C3 contributors and team, especially since I haven't been using Discord in many months (or perhaps even a couple years?) now and never got a since of the C3 community in the first place either in that regard. I really wish the "tech" world hadn't taken the bad turns it has in the past couple decades compared to how much vastly better things would have been by now if the "attention economy" and the related fallout of pervasive routine privacy violations such as now embodied in its worst-yet form of automated plagiarism systems (called "AI" for marketing/deceptive purposes largely, to make people hand-wave away its actual predominately theft-oriented real nature) and such hadn't come to dominate it. I think that'll turn around at some point, but in the mean time I am not sure what places are the best places to build up countervailing infrastructure or at least be isolated or highly protected from such dystopian trends. The future is in opposing these trends, not joining them. Nothing will be more valuable in a few decades from now than reliably human-made and untainted work and information and cleaning up the utterly disastrous mess the "AI" plagiarism bots have already made of huge swaths of the world's infrastructure and which will likely only worsen with time. In that regard, I have in recent years been seeing many programmers shifting away from GitHub in order to protect themselves and their work from MS's automated plagiaristic stealing of all of GitHub's hosted code, which will essentially let them superficially transform open source code and then pretend it is closed source among many other damaging exploitive futures it will likely enable. So, that is (tangentially) a possibility you could consider if you wanted to go that route. There are other places where harvesting is less likely, such as self hosting or non-profit hosting (e.g. "Codeburg", I think I heard about?) or whatever else, which I've seen some projects moving to to decrease the magnitude and/or probability of having all one's work stolen and uncredited (as is much more likely on GitHub now unfortunately that MS owns it). I also thought that my commits would be basically uncontroversial (and maybe they still are? I don't even know...) except perhaps a few sentences here or there where I had to make educated guesses as to why things were done in C3's design but I think those are likely correct (or at least relevant and valid regardless) since I can't think of other reasons. In any case, whatever other commits others want to pile on top are fine with me and that workflow of accepting commits and then piling changes on top seems to me like it'd be the best way to work rather than back-and-forth debating of a bunch of really small things. That's doubly true considering I don't actually mind if every word I write gets eventually overwritten since that is the natural way of open source and the big picture of iteratively improving things is what matters ultimately and old code and docs survive in the change list anyway so its not like anything gets deleted in any real sense. More broadly speaking, in my own personal life, I continue to be frustrated by the continuing trend I've dealt with for years of something always cropping up that makes me (in my hypersensitive and perhaps over-defensive state for the past decade) end up becoming very wary and drifting along to other things without getting substantive change accomplished. When I initially submitted my commits here I was happy and looking up in that regard thinking C3 would be a good place to break that trend but now I am not sure of my standing since it is all radio silence as far as I can discern and so it is hard to retain motivation in that context. I have been unsure of what I should even do the past 10 days and my productivity has dropped to near zero in that regard since I've been having trouble feeling comfortable investing time when I am so hypersensitive to anything that endangers the necessity for long term change in my life and the potentially high risk of choosing wrongly (or at least that is how my subconscious seems to perceive it, though that may just be ironically self-defeating on my part, but it is what it is). I'm tired of feeling stuck for the past decade and never being able to discern a path that feels right and sticks fully. There's always something that comes up like this. Oh, and I also wanted to say that it is not a totally black and white thing obviously, and I know I have to be pragmatic and tolerate a certain level of disagreeable things and such, but like all people my feelings on things are not like light switches that can be turned off and on but are more like a living ecosystem of factors that self-adjust to an extent but still require balance and the right context. "AI" has been disastrous for me in that regard since I innately view it as profoundly wrong. I am not even sure how I am ever going to get out of my decade-long period of stagnation for programming that I have fought for so long to get out of, both for my sake and others, but that's life and I try to be as philosophically well-adjusted as I seem to be able to be about it. Anyway though, that's my update on my thoughts on these matters. Sorry for my verbosity as usual and thanks for any time and for reading this if you do. I wasn't sure whether I should write even more here, but I don't have any idea what the status of all this even is at this point now. Have a great weekend and upcoming week, as always, in any case! 🌄🌌 |
Then we really should migrate off of Github, and tell others to follow suit. The only "true" Github competitor is Gitlab right now, but I peronsally use Gitea TBH. If you think LLMs are theft-based, provide evidence to lawmakers. Cite Suchir Balaji's blog for a start, and simultaneously sway the public opinion to support your claims. I really don't think this is controversial stance... but unfortunately people seem to believe that these AI systems are ethical. I'm personally fine with AI as long as you can prove the code it was trained on was permissively licensed. Even then, it's really, really hard to prove that open source code isn't stolen. And like many other people, I genuinely believe LLMs are useful for certain things like searching for source material to read. |
I think that hard-forking any Github repo with an open source license should be done more often. You really shouldn't have to wait for your changes to be read/accepted by someone else if you personally feel they're okay. Also, go ahead and deploy the site with Github pages for your personal use or for other people. Whoops, I meant Gitlab pages, or Forgejo pages. I think enough people will become fed up with Github and will use alternatives. |
The Discord is (whether you consider this good or bad) the primary place for discussing C3 related stuff, so feel free to hop in. There used to be a Discourse forum which was shut down due to inactivity.
Not really. It's just that this repo is separate from the main compiler repo which gets more attention. Also, not everybody gets pinged when you post updates, and the people who do get pinged don't necessarily have the time/energy to review/respond to everything... which is probably why the AI assistant was invoked by @lerno in the first place. |
License everything you post on a personal blog, block all crawlers/scrapers, sue everyone who illegally uses your blog post. It helps if the thing that is being stolen from you makes you a decent bit of money. Also, AI generated content is considered transformative in the United States with some restrictions. If you want to change this, many people including you, I, etc. have to lobby the government. Also, people must be convinced to both develop alternative technologies and use them. Stop being afraid of other people and how they will judge you. Understand that there's a huge amount of inertia and a huge financial incentive to prevent people from adopting other platforms/technologies. Take for example Pewdiepie's video on degoogling. If you want people to stop using unethical technologies, you need to make it as easy as humanly possible for them to switch (as easy as Google made it to start using their services). There's an argument to be made that Google should be protected for national security reasons, but I think there's a serious lack of competition and manipulation of supreme court judges. What else... be less vague and precisely state which technologies should be used in replacement of the old ones. For example, ladybird browser instead of Chrome/Firefox. If everybody contributed in an organized manner, these projects would be f***ing done already. |
The "C3 community" is not a monolith. What you are really looking for is money, power, and leverage to further your personal agenda. Only by talking with others can you determine if they're on the same page as you (it's possible but not guaranteed; it helps to dumb things down and be terse). Also stop giving so many f***s and overthinking everything. Help build foundational software for the future, while also respecting other people's different political opinions. What else... send money directly to developers you care about (I sent about $31 to @lerno so far). If 1000 people sent $10 per month, that's roughly $120,000 per year going to the C3 project. |
|
Also... I am technically breaking the rules outlined in https://github.com/c3lang/c3c/blob/master/CODE_OF_CONDUCT.md by talking about politics. |
Honestly it would be healthy to discuss some of these tangents in private to keep the discussions on topic. I think people are more comfortable sharing some controversial opinions that way. LLM-generated content isn't necessarily fully plagiarized, and the same goes for any content you find on the internet. You have to take inspiration from somewhere. |
|
FYI I was requested to review this, but have very limited time at present, I don't have an agenda. I think others may also have limited time also. This is a lengthy thread but I think discord may be the better place for some of these longer points, as it ate the time I had which I was going to use read the content :( Improvements are very valuable and making things better is a great idea in general as it has a "force multiplyer" effect that improves things for everyone so this sort of work is really helpful. |
|
I don't have pings set up for this repo, so I didn't see all of these messages until today. AI being as it is I didn't actually intend to invoke it 😂 It was an accident. And there might be some way to close it but I didn't find it at the time. 😅 I've been swamped these last days, trying to get on top of things despite that. I closed a few urgent bugs yesterday at least, despite most of the day being on a iaido workshop. And today I have a super stiff neck and a cold and some fever thanks to my daughter bringing home some germs. But I'll try to look at it, I'll probably grab the things I already looked at and merge them part by part. |
|
I can totally understand you feel disappointed that I didn't get around to it earlier, I would be too. I'll add a hook so that I see updates here in the discord |
|
I am merging this piece by piece into main, in the speed I'm able to review it. |
|
Hey everyone (lerno, waveproc, joshring). Thanks for all of your responses and your time. I really appreciate it and all of your nuanced and thoughtful comments and apologize for any stress or drama or wasted time my tangential remarks caused, etc. I've been hypersensitive/hypervigilant in recent years and get bent out of shape a bit easily, though I didn't used to be like that years ago. I've been stuck in a repeating pattern of largely self-defeating hypersensitive reactions and repeatedly switching up my environment and approach to try to find stable foundations and so forth in ways that ironically have prevented me from getting a lot done in the past decade. I've had trouble restarting my programming career after I "temporarily" left it a decade ago and instead ended up writing a book and ever since then it has been a struggle ever re-entering the field officially and to make matters worse my attempts to do my own thing on personal projects keeps getting confounded by my own increased hyper-reactivity to the slightest things. I am trying to do better though and be less inflexible and perfectionistic. I need to break my own cycle of counterproductive self-sabotaging behavior, etc. Anyway, it is good to hear that my hyper-reactive concern that my stance had got me in trouble is/was overblown and that I was indeed mostly just bending myself in knots and imagining things in that regard. I am currently a bit burnt out, as happens to me when I get wound up tightly on something like this, but hopefully my creative/productive spark and momentum will recover and pick up again soon. So, talk to you all some time later I guess. Sorry again for my verbosity. In the meantime, I am wishing you all the best in all your projects and endeavors. 💾🎨🕊️ |
Hello! As promised I have finally completed my accumulated edit suggestions that I tracked while I was reading through virtually all of the C3 documentation on the website over the past few weeks.
There are hundreds of changes in here and so I've split the changes into many commits so that it is hopefully easier to pick and choose which ones you want.
I was careful to make all my edits as uncontroversial in my estimate as I could and tried to follow the existing style of the docs closely whenever possible (e.g. not using oxford commas even though I personally prefer to use them, etc) though.
Also, many sections of the documentation that were previously too anemic to actually understand without experimentation now have also been significantly expanded to give a much more complete picture of what they are or do, which I tested alongside the process of editing them to ensure that they worked.
I really like what C3 has done in its approach in cleaning up and modernizing C while keeping its spirit. 💾🥳
Anyway, I hope the C3 community finds these changes to be helpful and pleasing and I wish you all a wonderful day/night/etc and happy coding with C3, etc!
See you guys and gals around. I also had a few other ideas that occurred to me in the process, but that's a story for another day. I am tired tonight and am going to sleep now. I'm glad to have finally finished the edits. 🏞️😎