Documentation: Improve IOCCC rules, guidelines, and FAQ

[lcn2]

Is there an existing issue for this?

• I have searched for existing issues and did not find anything like it

Describe the problem with or missing documentation

When talking about what people need to do when submitting to the IOCCC, instead of referring directly to the chkentry(1) tool, refer to the more simple chksubmit(1) tool.

Relevant files

FAQ, Rules, Guidelines, etc.

What you expect

Someone submitting to the IOCCC need to just concern themselves with the chksubmit(1) tool.

Relevant links or files

https://www.ioccc.org/* :-)

Anything else?

See in the other repo, issue 1299.

Does any of the web site documentation need to refer to the internals of chkentry(1) as used by the IOCCC judges alone? Perhaps not.

If there is some reason to refer to IOCCC judge mode stuff, it should be clearly separate from the chksubmit(1) tool and NOT make the documentation someone needs to submit to the IOCCC any more complex than it needs to be.

UPDATE 0

This is now a general "Improve IOCCC rules, guidelines, and FAQ" issue.

[xexyl]

Once we have discussed the other issues and I complete it we can then do this. But then again for some of it it might be good if we were to have the tables sorted out before writing the code - unless you think the tables in GitHub work well enough?

Feel free to assign.

[xexyl]

Does any of the web site documentation need to refer to the internals of chkentry(1) as used by the IOCCC judges alone? Perhaps not.

If there is some reason to refer to IOCCC judge mode stuff, it should be clearly separate from the chksubmit(1) tool and NOT make the documentation someone needs to submit to the IOCCC any more complex than it needs to be.

As far as this goes. I would think not. If someone really wants to know the internals of that tool they can read the source code. Or if that's too much (which I could well imagine) they can look at the man page. It's not like the judges have ever revealed everything anyway.

[lcn2]

The reason why this is a TOP PRIOTY is that this issue needs to be done BEFORE the rewrite of the rules, guidelines and FAQ can start.

[xexyl]

That being said I do have some questions that can be asked here before it's done that I think might help.

I can't ask right now and I want to finish the new tool first but if I have the energy after that I will see if I can ask those questions here.

Thankfully I already finished almost all of the necessary code changes for the new tool and the last one won't take long at all. A few line changes should be all that's needed.

Because it's all related the commit will likely be larger than usual. But that's mostly because of the new files.

But I will be away for a while now.

[xexyl]

Commit ioccc-src/mkiocccentry@e4683e2 is the new tool. Hopefully I did not miss anything. make prep works. I had to update the struct info and struct auth and the template JSON files as well as the semantics tables ... lots had to be done. It's a large commit. But it seems to be fine.

Included a man page as well. As I note in the relevant issue -J level cannot be added but that should not be a problem since if someone wants to see that they can just do chkentry -S -J level. It can't be done because of the lower level functions that shell_cmd() uses does not support all data types. I don't feel like even trying to update that though if you want to feel free. It doesn't seem like it's needed anyway for chksubmit. It's fine in chkentry.

I checked a number of times that I changed the macros and strings where necessary., One almost slipped through but I caught it. Hopefully none managed to actually slip through.

As for this issue I don't know if we need to do this before the chkentry options -s and -S are done. What do you think @lcn2?

I can see it both ways: but since chksubmit runs chkentry -S it might be good to briefly explain what that does (that is missing from the man page of course - and yes the chkentry.1 was also updated).

I'll see if you replied to the other issue and if so I'll reply. Otherwise I'll wait on you. If you updated the tables I am too tired to worry about it. Plus there is still that total files count issue that has to be answered before the code can be updated. And that change will likely have to be updated in more than chkentry - also mkiocccentry and txzchk. The latter two are easiest probably - the chkentry is more annoying as that function in soup/ has to keep track of the files and where they are in order to know if the file should count. On the other hand in some ways it might be easier as it won't have to worry about prog.c, Makefile, remarks.md as they're not in the extra files array. Neither are the .info.json and .auth.json of course. As for mkiocccentry and number of files another thing came to mind - a possible loophole. I'll mention it over there. Better do it now before I forget.

Anyway the new tool is created and hopefully everything is good.

[lcn2]

Commit ioccc-src/mkiocccentry@e4683e2 is the new tool. Hopefully I did not miss anything. make prep works. I had to update the struct info and struct auth and the template JSON files as well as the semantics tables ... lots had to be done. It's a large commit. But it seems to be fine.

THANK YOU

We are keeping that issue open in the other repo just in case documentation changes here require some tweaks over there, and to allow for more testing.

Included a man page as well. As I note in the relevant issue -J level cannot be added but that should not be a problem since if someone wants to see that they can just do chkentry -S -J level. It can't be done because of the lower level functions that shell_cmd() uses does not support all data types. I don't feel like even trying to update that though if you want to feel free. It doesn't seem like it's needed anyway for chksubmit. It's fine in chkentry.

Excellent point. And in addition, removal of the -J level from chksubmit(1) will further simplify the command line for submitters.

As for this issue I don't know if we need to do this before the chkentry options -s and -S are done. What do you think @lcn2?

We may not need to document chkentry(1) very much other than perhaps as a FAQ. Some people might remember it from the "gold old" IOCCC28 days (assuming to say that given how long IOCCC28 was in the planning stage), so a FAQ about "What happened to chkentry(1)?" might be good enough.

I can see it both ways: but since chksubmit runs chkentry -S it might be good to briefly explain what that does (that is missing from the man page of course - and yes the chkentry.1 was also updated).

In the above suggested "What happened to chkentry(1)?" FAQ, the answer could not only mention that it is still used and explain about how chksubmit(1) uses it, that FAQ could discuss the command line options, AND that only IOCCC judges need to use the command directly: well something like that.

I'll see if you replied to the other issue and if so I'll reply. Otherwise I'll wait on you. If you updated the tables I am too tired to worry about it. Plus there is still that total files count issue that has to be answered before the code can be updated. And that change will likely have to be updated in more than chkentry - also mkiocccentry and txzchk. The latter two are easiest probably - the chkentry is more annoying as that function in soup/ has to keep track of the files and where they are in order to know if the file should count. On the other hand in some ways it might be easier as it won't have to worry about prog.c, Makefile, remarks.md as they're not in the extra files array. Neither are the .info.json and .auth.json of course. As for mkiocccentry and number of files another thing came to mind - a possible loophole. I'll mention it over there. Better do it now before I forget.

The 2nd draft of the tables will in the other repo will address these changes: once various daily chores and visitors to "details omitted" have left.

Anyway the new tool is created and hopefully everything is good.

THANK YOU

[xexyl]

Commit ioccc-src/mkiocccentry@e4683e2 is the new tool. Hopefully I did not miss anything. make prep works. I had to update the struct info and struct auth and the template JSON files as well as the semantics tables ... lots had to be done. It's a large commit. But it seems to be fine.

THANK YOU

You are most welcome! I'm glad I could do it. As I say later it did take a lot more time and effort than I anticipated but I had forgotten (or didn't think of) various things that had to change along with it. Some I simply forgot. The fact I did update mkiocccentry and also chkentry is immensely helpful as well. I felt like those had to be done in order to work on this. Now we don't have to worry about mkiocccentry at all. And hopefully chksubit is done too. Once chkentry is updated we can do more testing more easily too I would guess.

We are keeping that issue open in the other repo just in case documentation changes here require some tweaks over there, and to allow for more testing.

I am sure things will change as well so that's a good idea. We still don't have a fully working chkentry test suite - not since it went from two arg to one arg. But that open issue for this new tool also has the options for chkentry. Maybe it'd be better to actually open another issue though? I'm not sure - I leave that to your judgement.

Included a man page as well. As I note in the relevant issue -J level cannot be added but that should not be a problem since if someone wants to see that they can just do chkentry -S -J level. It can't be done because of the lower level functions that shell_cmd() uses does not support all data types. I don't feel like even trying to update that though if you want to feel free. It doesn't seem like it's needed anyway for chksubmit. It's fine in chkentry.

Excellent point. And in addition, removal of the -J level from chksubmit(1) will further simplify the command line for submitters.

That's true. I did think of that. I'm glad you agree.

As for this issue I don't know if we need to do this before the chkentry options -s and -S are done. What do you think @lcn2?

We may not need to document chkentry(1) very much other than perhaps as a FAQ. Some people might remember it from the "gold old" IOCCC28 days (assuming to say that given how long IOCCC28 was in the planning stage), so a FAQ about "What happened to chkentry(1)?" might be good enough.

Actually (as I think I say later) what I was getting at is maybe THIS issue (updating documentation) should wait until after those two options are implemented? This because we might not need to update it a second time asa we would have the details up front?

I can see it both ways: but since chksubmit runs chkentry -S it might be good to briefly explain what that does (that is missing from the man page of course - and yes the chkentry.1 was also updated).

In the above suggested "What happened to chkentry(1)?" FAQ, the answer could not only mention that it is still used and explain about how chksubmit(1) uses it, that FAQ could discuss the command line options, AND that only IOCCC judges need to use the command directly: well something like that.

Sure. Although for this subject I was thinking maybe it's better to wait to write it until after the new options of chkentry are implemented? As for what happened to chkentry - that might be interesting but maybe we should have separate files for history and other things? It's not that the length of the FAQ bothers me (obviously with what I read :-) ) but I believe (maybe I am wrong) that length alone (even when in sections with much of it not being relevant to [them]) can overwhelm people. I don't mind but what is certain is it is very long and it might be good to shorten it some.

I'll see if you replied to the other issue and if so I'll reply. Otherwise I'll wait on you. If you updated the tables I am too tired to worry about it. Plus there is still that total files count issue that has to be answered before the code can be updated. And that change will likely have to be updated in more than chkentry - also mkiocccentry and txzchk. The latter two are easiest probably - the chkentry is more annoying as that function in soup/ has to keep track of the files and where they are in order to know if the file should count. On the other hand in some ways it might be easier as it won't have to worry about prog.c, Makefile, remarks.md as they're not in the extra files array. Neither are the .info.json and .auth.json of course. As for mkiocccentry and number of files another thing came to mind - a possible loophole. I'll mention it over there. Better do it now before I forget.

The 2nd draft of the tables will in the other repo will address these changes: once various daily chores and visitors to "details omitted" have left.

Sounds good. I'll look back tomorrow.

Anyway the new tool is created and hopefully everything is good.

THANK YOU

Again you are most welcome! It took more time than I thought but I had forgotten about things that would have to change. To that end I am quite tired (okay I'm always very tired and waking up at stupid o'clock does not help there) and I'll look at your updates another day. If you get them in today and I don't by chance take a look today I'll do so tomorrow.

[SirWumpus]

Woke this morning to a new IOCCC video (that I couldn't watch not being a paid member), which in the teaser did mention the R&G rewrite. Who's leading the work?

[xexyl]

Woke this morning to a new IOCCC video (that I couldn't watch not being a paid member), which in the teaser did mention the R&G rewrite. Who's leading the work?

Last I remember from Landon he's going to work on it some: since I am helping with the code it gives him more time. I'm guessing he'll want me to check for typos etc. but that obviously comes later on. He did mention in a video (which btw I think you can choose how much you pay) some while back (more than once in fact so multiple videos) Leo wanted it back to more simple (which is good): we were rushed to get the IOCCC28 open and there were many new things. He did say in the last video (that I watched - haven't had time or even energy to watch the last two ... hope to today) that the fun stuff (you probably know what I mean) will be at the end of the guidelines.

That's what I know but maybe Landon will have more to say?

[xexyl]

Incidentally @lcn2 ... I was going to do this change for you but now that there are code changes required and hoping to get done by the end of this coming week: I guess it's better that you take care of this issue? I do hope to get the last issue (necessary for IOCCC29) done in the next few days although I guess I won't get much done today and probably not tomorrow. Still unless something comes up that I can't foresee I don't see why I couldn't get the work done by 9 November 2025.

Oh and yes. Real weeks start on Monday so when I say 'coming week' I mean starting tomorrow. But then the philosophical (or similar) question is: since today is the last day of the week and it's now November doesn't that mean that this is the end of the first week of November? And if not we have to say: a week is 7 days so shouldn't it be that the first week ends on 7 November 2025 so Friday? Or if we want to start out with the first day of the week: 8 November 2025 which is Saturday and not the end of the week? So we have to start over. But I'll stop my philosophical / logical discussions now ... hoping to look at mkiocccentry soon but we'll see.