Submission tool percepitions

[SirWumpus]

On 2025-01-08 16:23, Thomas Cort wrote:

Happy New Year! I'm toying with IOCCC but the new submission tool thing is
kind of confusing.

By posting @tcort comment to me, I'm hoping to encourage him to expand upon his comment.

[xexyl]

I thought it was pretty clear. The FAQ gives a very simple synopsis.

But I would be happy to give an exact example. When I have Internet access again.

Yes it would be helpful if elaboration is possible as it's quite vague.

[lcn2]

Is this where a command of the form might be simpler:

mkiocccentry workdir topdir

And where the tool walks topdir collecting all files under the that match the sane path?

The tool would throw an error if it didn't find the required files, or if the directory tree was too deep. It would ignore "dot files" and other things that don't match the regular expression. It would perform a make clobber and then count the number of files to be sure the list was not too long. Finally, it would print out the list of files it found and ask the user to confirm the list.

UPDATE 0a

While this would require a little bit of extra programming, it would reduce the complexity of the command line and not require the user to have to specify each extra file on the command line.

The topdir could be named anything because the UUID directory tree would be built and tarred up under workdir.

UPDATE 1

If there aren't any serious objections, we could open up a new issue along these lines to complete the work and produce a tool that implemented the simplified command line.

[xexyl]

Is this where a command of the form might be simpler:

mkiocccentry work_dir topdir

And where the tool walks topdir collecting all files under the that match the sane path?

The tool would throw an error if it didn't find the required files, or if the directory tree was too deep. It would ignore "dot files" and other things that don't match the regular expression. It would perform a make clobber and then count the number of files to be sure the list was not too long. Finally, it would print out the list of files it found and ask the user to confirm the list.

UPDATE 0

While this would require a little bit of extra programming, it would reduce the complexity of the command line and not require the user to have to specify each extra file on the command line.

I already cited reasons this is not a good idea.

I will throw in another.

What if they accidentally have a file in that directory that identifies them?

Making the assumption that they want every file in a certain directory is a bad assumption to make.

I always have extra files and it would be easy to make a mistake.

I do not see how it simplifies the command in a way that matters anyway. Specifying specific files is surely not hard. But being specific is better.

If someone wants they can now use a directory anyway, right?

Anyway if this functionality was added I implore that it's an option and not default.

I fear also that doing this would further delay the contest. Doing this would quite complicate the code and we would have to redesign the test suite too.

That alone is something to remember.

[xexyl]

UPDATE 0a

While this would require a little bit of extra programming, it would reduce the complexity of the command line and not require the user to have to specify each extra file on the command line.

Yes and instead it would force the user to make sure that only files they want included are in that directory.

I do not know about others but that would be a very big burden and it would also be more error prone.

Is it really that hard to specify extra files? It is basically cp but the tool makes the target directory.

And I think it would actually be more complicated to modify the tool than you might think. It would also force rewriting parts of the test suite and potentially other things too.

I think if you really want that function it should be an option.

But are we not putting the cart before the horse ? Maybe we should find out first what the problem is.

Even so I do not see how changing the command line syntax would actually simplify it that much. It would also be making a big assumption.

Maybe this should be considered post IOCCC28 ?

Anyway I really have to stop typing. Phone typing is bothering my ulnar nerve.

BTW: the eta for Internet service restoration is now 24 hours so I will be further behind. Sure I might be able to do some work when offline but not everything can be done.

[xexyl]

UPDATE 0a

While this would require a little bit of extra programming, it would reduce the complexity of the command line and not require the user to have to specify each extra file on the command line.

Yes and instead it would force the user to make sure that only files they want included are in that directory.

I do not know about others but that would be a very big burden and it would also be more error prone.

Is it really that hard to specify extra files? It is basically cp but the tool makes the target directory.

And I think it would actually be more complicated to modify the tool than you might think. It would also force rewriting parts of the test suite and potentially other things too.

I think if you really want that function it should be an option.

But are we not putting the cart before the horse ? Maybe we should find out first what the problem is.

Even so I do not see how changing the command line syntax would actually simplify it that much. It would also be making a big assumption.

Maybe this should be considered post IOCCC28 ?

Anyway I really have to stop typing. Phone typing is bothering my ulnar nerve.

BTW: the eta for Internet service restoration is now 24 hours so I will be further behind. Sure I might be able to do some work when offline but not everything can be done.

Okay but I am pondering this more. I still would think it being the default would be a problem but what if we made use of -r (like cp -r)?

I don't know if I can get this done this time round as I have the other things going on including more for the contest.

[xexyl]

UPDATE 0a

While this would require a little bit of extra programming, it would reduce the complexity of the command line and not require the user to have to specify each extra file on the command line.

Yes and instead it would force the user to make sure that only files they want included are in that directory.

I do not know about others but that would be a very big burden and it would also be more error prone.

Is it really that hard to specify extra files? It is basically cp but the tool makes the target directory.

And I think it would actually be more complicated to modify the tool than you might think. It would also force rewriting parts of the test suite and potentially other things too.

I think if you really want that function it should be an option.

But are we not putting the cart before the horse ? Maybe we should find out first what the problem is.

Even so I do not see how changing the command line syntax would actually simplify it that much. It would also be making a big assumption.

Maybe this should be considered post IOCCC28 ?

Anyway I really have to stop typing. Phone typing is bothering my ulnar nerve.

BTW: the eta for Internet service restoration is now 24 hours so I will be further behind. Sure I might be able to do some work when offline but not everything can be done.

Okay but I am pondering this more. I still would think it being the default would be a problem but what if we made use of -r (like cp -r)?

I don't know if I can get this done this time round as I have the other things going on including more for the contest.

But as far as defaults go. If more people like the idea you have then it seems that the correct choice would be to make it the default and then have an option that does it the way it currently does.

I don't want to be unreasonable and if others prefer your idea then certainly we should go for that! Just because I don't see the point and just because I do not really see how it simplifies it and just because it would cause problems for me doesn't mean it would for others and as long as there is a way to do it the current way it would in this case be better.

Again I don't know what I can do in this case but later on maybe. Right now I have a lot on my mind especially made worse due to the outage but if say I get the other things done at the other repo maybe I can work on this.

Of course you also wanted help with the polite words list so that's something to consider too.

Perhaps opening a discussion could help to see what others prefer?

Whatever the case if more people like your proposal then obviously we should do that. Using an option is the solution to that problem.

Okay really done typing now. I don't know if I will work on the website today. It's a very frustrating day and I have two appointments today too.

But hopefully tomorrow the service will be back and I can update those files over there!

Best wishes on the submit server and other things and I will BCNU!

[SirWumpus]

I wish this discussion had waited first for @tcort to respond, before speculating and jumping in and out of rabbit holes.

[xexyl]

I wish this discussion had waited first for @tcort to respond, before speculating and jumping in and out of rabbit holes.

Well I kind of did suggest that but it might give him ideas too. This way he can consider options too.

[tcort]

It's clear that a lot of work has gone into developing mkiocccentry. I can tell there is a strong motivation to have valid and compliant entries to make the lives of the judges easier. I just find the whole process of figuring out how to properly structure and develop my entry to work with the provided tools a bit overwhelming.

I've spent several hours digging through the FAQ, Guidelines, Markdown Guidelines, and Rules. I think I've sorted out most of my confusion. At the end of my journey through RTFM, I do have some comments/suggestions.

Reading

There is a lot to read. If printed, there would be over 180 US Letter sized pages to read (FAQ 121 pages, Guidelines 33 pages, Rules 18 pages, Markdown Guidelines 11 pages, etc).

My main cause for overwhelm is that there are a lot of details about a lot of things that aren't an obfuscated C program. A lot of emphasis is placed on the validity of the submission tarball and JSON files. Initially, I thought these needed to be hand crafted or modified from a template. Instead, it looks like mkiocccentry(1) generates them. If the tool generates them, then I would assume it only generates valid files and anyone who uses the tool wouldn't have to worry about details like no_comment is REQUIRED in the JSON files.

Suggestion: Consider moving the details about these files into a separate document ("submission tarball specification") as it seems difficult to make an invalid entry with mkiocccentry(1) and most people wouldn't need to worry about the specifics.

Ability to run validation checks on demand

I'd like to be able to run the validation and other checks included in mkioccentry(1) as I develop my program so that I don't waste time on an entry that won't be accepted. For example, if my source file is over the size limits, I want to know about it during the development process rather than at the end when I run mkiocccentry to build a submission tarball. My issues are:

• it isn't clear to me how to just perform validations with mkiocccentry and not make a submission tarball.
• the validation checks are spread across several programs (mkiocccentry, txzchk, fnamchk, chkentry, iocccsize, etc). It seems that mkiocccentry drives the other programs, but it isn't 100% clear.

Suggestions:

• add an option to mkiocccentry(1) to run iocccsize on your prog.c as well as run tests on the Makefile, the remarks.md and any extra files as well, to verify that everything seems in order WITHOUT making the tarball. Maybe call it --check-only or --dry-run or whatever
• Modify the example Makefile, adding a check target which runs the checking/validation tools from the mkiocccentry toolkit (assuming they're in $PATH).

[xexyl]

It's clear that a lot of work has gone into developing mkiocccentry. I can tell there is a strong motivation to have valid and compliant entries to make the lives of the judges easier. I just find the whole process of figuring out how to properly structure and develop my entry to work with the provided tools a bit overwhelming.

I've spent several hours digging through the FAQ, Guidelines, Markdown Guidelines, and Rules. I think I've sorted out most of my confusion. At the end of my journey through RTFM, I do have some comments/suggestions.

Reading

There is a lot to read. If printed, there would be over 180 US Letter sized pages to read (FAQ 121 pages, Guidelines 33 pages, Rules 18 pages, Markdown Guidelines 11 pages, etc).

My main cause for overwhelm is that there are a lot of details about a lot of things that aren't an obfuscated C program. A lot of emphasis is placed on the validity of the submission tarball and JSON files. Initially, I thought these needed to be hand crafted or modified from a template. Instead, it looks like mkiocccentry(1) generates them. If the tool generates them, then I would assume it only generates valid files and anyone who uses the tool wouldn't have to worry about details like no_comment is REQUIRED in the JSON files.

Suggestion: Consider moving the details about these files into a separate document ("submission tarball specification") as it seems difficult to make an invalid entry with mkiocccentry(1) and most people wouldn't need to worry about the specifics.

Ability to run validation checks on demand

I'd like to be able to run the validation and other checks included in mkioccentry(1) as I develop my program so that I don't waste time on an entry that won't be accepted. For example, if my source file is over the size limits, I want to know about it during the development process rather than at the end when I run mkiocccentry to build a submission tarball. My issues are:

• it isn't clear to me how to just perform validations with mkiocccentry and not make a submission tarball.

• the validation checks are spread across several programs (mkiocccentry, txzchk, fnamchk, chkentry, iocccsize, etc). It seems that mkiocccentry drives the other programs, but it isn't 100% clear.

Suggestions:

• add an option to mkiocccentry(1) to run iocccsize on your prog.c as well as run tests on the Makefile, the remarks.md and any extra files as well, to verify that everything seems in order WITHOUT making the tarball. Maybe call it --check-only or --dry-run or whatever

• Modify the example Makefile, adding a check target which runs the checking/validation tools from the mkiocccentry toolkit (assuming they're in $PATH).

Lots of great thoughts. Can't reply well right now unfortunately.

As for the suggestion that it runs those tools: it does.

But perhaps you mean a way to do it without having to answer the questions? Unfortunately that is not really possible.

You can always run iocccsize on your program but the others are based on input.

As for the long details. That's why we have it in a separate section. Do you think it would help (rather than adding yet another document though there might be some merit there too) if there was an emphasis on those sections saying it's not necessary to read?

As far as rules and guidelines. That's something that all contestants have to deal with I am afraid. Unless they want to risk breaking the rules! Though you do not have to read the guidelines it can help.

Appreciate your thoughts and it seems like it's not the command line but maybe refining the documentation could be done. Unfortunately we might not have time this time but I think this has merit.

I can't type more now but hopefully I will be able to tomorrow.

Btw: the first section in the FAQ is the most important part but some of the later sections are also useful.

As you probably know when something changes greatly it does require more documentation. The good news is next time people should be more familiar.

Oh as far as txzchk. I explicitly wrote that tool (some others too and co-developed others but I know this one best) so if you do have some questions I would be happy to answer them when I have Internet access again.

Thanks and best wishes!

[xexyl]

There is a lot to read. If printed, there would be over 180 US Letter sized pages to read

I'm also surprised at the volume /length of material to read. I had never considered that aspect.

I just replied about that. It might be good to more clarify state what needs to be read and what doesn't.

But there's a lot of new things so it requires a lot of new documentation. But isn't that irony wonderful? With lots of new things that can be complicated you need more documentation but that can cause other kinds of confusion!

Still I am happy to try and help improve it.

[xexyl]

Thanks @tcort for taking the time; the others will be interested in this and any additional feedback you have as you progress.

In the case of iocccsize, I think there might be an assumption that many of the past participants were already familiar with the existence and use of iocccsize, which can be run separately from the mkiocccentry. Clearly some sort of tool overview is needed.

Yes that's probably true about the tool.

But please check the guidelines if you haven't. I think there is an overview? But ...

One thing that I realised is that there are things that are stated in more than one place.

That's a hard thing to fix especially since some people might go one place and not another.

For instance you told me you don't bother with guidelines.

But another part of it is it had to be updated as things developed and of course also the fact that more than one person worked on it.

It is good that this was raised though and I for one not only appreciated but also enjoyed seeing the very great feedback. It's always frustrating when people say 'it doesn't work; please fix it'. But every so often someone will give a lot of EXCELLENT feedback! They are truly gems. And I really mean that.

[SirWumpus]

For instance you told me you don't bother with guidelines.

I didn't see (can't find) that statement.

[xexyl]

For instance you told me you don't bother with guidelines.

I didn't see (can't find) that statement.

It was on mastodon .. that's probably why. But if you did not then I totally misunderstood you. Though maybe you meant you usually don't read it .. I would imagine you would after all the changes this time.

[lcn2]

@tcort makes a good suggestion and point:

add an option to mkiocccentry(1) to run iocccsize on your prog.c as well as run tests on the Makefile, the remarks.md and any extra files as well, to verify that everything seems in order WITHOUT making the tarball. Maybe call it --check-only or --dry-run or whatever

We think the idea of @tcort with a --dry-run would be a good option. With --dry-run, there would be no reason ask the user for answers/inout .. just check things and report on any problems.

But what about a tests such as txzchk(1) do? Without prompting the user, how would it run thru its motions? Well first we need a --random-seed integer option. See below:

Along that same idea, one could have the following option --random-seed integer. Like --dry-run, there would be no user prompting. Instead the tool would use pseudo-randomly generated answers and go thru the full motion of forming a submission WITH THE ONLY DIFFERENCE would be that the final prompt would not print info about uploading to a slot, but instead print something like:

Random seed 12345 test is successful.

Because --random-seed 12345 was used, the filename.tar.bz2 is not suitable for uploading.

Instead of the code reading answers from stdin (or the answers file), a call to generate a pseudo-random string (and one that conformed to what would otherwise be a valid input) that would be used.

Returning to the --dry-run: This command line option would be an alias for --random-seed ((SOME_INTEGER)).

So if someone did:

mkiocccentry --dry-run work_dir prog.c Makefile remarks.md

At the end, if all is well, instead of print info about uploading to a slot, it would print:

Dry run test is successful.

Because --dry-run was used, the filename.tar.bz2 is not suitable for uploading.

UPDATE 0

One way to implement --random-seed integer would be to call srandom(integer) and then use random() to drive the generation of a pseudo-randomly generated answers file and then have mkiocccentry use that generated random answers file.

Obviously the lines in the answers file would not be "completely random" stuff. The code would pseudo-randomly generate strings that conformed to input requirements.

One would use a seeded pseudo-random number generator with an integer seed argument BECAUSE the result would be repeatable. So of a problem were to be discovered, once corrected the result could be re-tried.

UPDATE 1

The --random-seed integer system would be a useful test of the complete system. Completely "hands free" as the expression goes.

Users could use --dry-run to test their files. In this case it would be using a well known integer that we could select.

The implementation of this would NOT be intrusive of the mkiocccentry(1) code because both --dry-run and --random-seed integer simply generate a pseudo-random strings that go into an answers file that mkiocccentry(1) uses.

[lcn2]

Yes please write it. That would be helpful.

We will pause from our submit tool work and do just this. Stay tuned.

[xexyl]

Yes please write it. That would be helpful.

We will pause from our submit tool work and do just this. Stay tuned.

Thanks!

I look forward to seeing what you have in mind.

Tomorrow I can commit the errno bug fix in txzchk that I made today and maybe look at the guidelines and rules and FAQ. But given that we're talking about breaking things up some perhaps I should wait on the FAQ edits until a better idea is decided on?

QUESTION

Besides the bug fix and the guidelines and rules updates needed for the recent feature I added what do you need most?

Perhaps for a new file a new issue should be opened?

And as for a different interface for mkiocccentry: I can try and start playing with an option for it if you want but maybe an enhancement issue should be opened here? (And if a new documentation file has to be added maybe a new issue at the other repo? .. though honestly maybe that is not really necessary depending on what is being discussed here).

I can barely see. It's been a very long two days but hopefully tomorrow will be better and more productive. Need sleep now. Good night!

[lcn2]

Tomorrow I can commit the errno bug fix in txzchk that I made today

When you submit your PRs for this repo, we will start on the code to generate a random answers file as per GH-discussioncomment-11791313.

and maybe look at the guidelines and rules and FAQ. But given that we're talking about breaking things up some perhaps I should wait on the FAQ edits until a better idea is decided on?

... content replaced by action in UPDATE 0 ...

Now that the "Enter the IOCCC" / "OCCC Quick Start Guide" has moved the FAQ 0.0 contents, we need to simplyfty quick-start.html.

The actions in UPDATE 0 only moved content: Now we need to think about simplification of this content. We can still keep the details .. but those details can be pushed into other web pages AND/OR the main FAQ. All we have done so far is to setup our ability to simplify.

QUESTION

Besides the bug fix and the guidelines and rules updates needed for the recent feature I added what do you need most?

The Rules and Guidelines need to be updated to reflect the new subdirectory capabilities.

Perhaps for a new file a new issue should be opened?

Open a issue to add the --dry-run and --random-seed integer` as discussed in GH-discussioncomment-11791313.

And as for a different interface for mkiocccentry: I can try and start playing with an option for it if you want but maybe an enhancement issue should be opened here? (And if a new documentation file has to be added maybe a new issue at the other repo? .. though honestly maybe that is not really necessary depending on what is being discussed here).

Perhaps this is a post IOCCC28 thing, @xexyl ? But maybe that could be determined and discussed in a new enhancement issue about "simplify the mkiocccentry(1) command line"?

I can barely see. It's been a very long two days but hopefully tomorrow will be better and more productive. Need sleep now. Good night!

We need to sleep as well. Good night!

UPDATE 0

With commit 11dfe51c6cbd70bbbdbc60d9fc9b10781222adc3 we have moved the IOCCC Quick Start Guide:

moved IOCCC Quick Start Guide

Created quick-start.md to hold the FAQ 0.0 content.

Used sgit(1) to change:

• faq.html#enter ==> quick-start.html#enter
• faq.html#enter_questions ==> quick-start.html#enter_questions
• faq.html#step_0 ==> quick-start.html#step_0
• faq.html#step_1 ==> quick-start.html#step_1
• faq.html#step_2 ==> quick-start.html#step_2
• faq.html#register ==> quick-start.html#register
• faq.html#step_3 ==> quick-start.html#step_3
• faq.html#step_4 ==> quick-start.html#step_4
• faq.html#step_5 ==> quick-start.html#step_5
• faq.html#step_6 ==> quick-start.html#step_6
• faq.html#step_7 ==> quick-start.html#step_7
• faq.html#step_submit ==> quick-start.html#step_submit

Via:

sgit -e 's/faq\.html#enter/quick-start.html#enter/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#enter_questions/quick-start.html#enter_questions/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_0/quick-start.html#step_0/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_1/quick-start.html#step_1/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_2/quick-start.html#step_2/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#register/quick-start.html#register/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_3/quick-start.html#step_3/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_4/quick-start.html#step_4/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_5/quick-start.html#step_5/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_6/quick-start.html#step_6/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_7/quick-start.html#step_7/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_submit/quick-start.html#step_submit/g' '*.md' '*.hdr' 'inc/*.html'

The former FAQ 0.0 section in faq.html now just refers to quick-start.html.

Modified menu and non-JS menu so that "Enter the IOCCC" refers to quick-start.html.

Changed bin/gen-top-html.sh VERSION from "1.4.10 2024-11-23"
to "1.4.11 2025-01-09".

Performed make www on macOS to complete the above.

[xexyl]

Tomorrow I can commit the errno bug fix in txzchk that I made today

When you submit your PRs for this repo, we will start on the code to generate a random answers file as per GH-discussioncomment-11791313.

Sounds good! I'll do the commit later this morning. Not sure if I'll do it after replying to this or not .. it's been hectic (as you know). I think I will do it soon though. Today I have another appointment but this time it's just a call at least (well FaceTime whereas yesterday was a call - usually zoom but as you know had no Internet - and in person).

and maybe look at the guidelines and rules and FAQ. But given that we're talking about breaking things up some perhaps I should wait on the FAQ edits until a better idea is decided on?

... content replaced by action in UPDATE 0 ...

Now that the "Enter the IOCCC" / "OCCC Quick Start Guide" has moved the FAQ 0.0 contents, we need to simplyfty quick-start.html.

The actions in UPDATE 0 only moved content: Now we need to think about simplification of this content. We can still keep the details .. but those details can be pushed into other web pages AND/OR the main FAQ. All we have done so far is to setup our ability to simplify.

Okay once you've figured out HOW you want to do this, @lcn2, I'll be happy to help here!

QUESTION

Besides the bug fix and the guidelines and rules updates needed for the recent feature I added what do you need most?

The Rules and Guidelines need to be updated to reflect the new subdirectory capabilities.

Of course! I'll do that. Thanks for confirming! The FAQ has to have this too but do we want to do that AFTER the other contents were simplified? Perhaps it's also an idea to move some of the other information about mkiocccentry to quick start? For instance the -a/-A/-i options are very useful for when you have to update a submission!

Perhaps for a new file a new issue should be opened?

Open a issue to add the --dry-run and --random-seed integer` as discussed in GH-discussioncomment-11791313.

I'll do this and link to the issue.

And as for a different interface for mkiocccentry: I can try and start playing with an option for it if you want but maybe an enhancement issue should be opened here? (And if a new documentation file has to be added maybe a new issue at the other repo? .. though honestly maybe that is not really necessary depending on what is being discussed here).

Perhaps this is a post IOCCC28 thing, @xexyl ? But maybe that could be determined and discussed in a new enhancement issue about "simplify the mkiocccentry(1) command line"?

I think it should be post IOCCC28 yes. I can open this too ... then after the two issues are open I can look at making that commit (or try to).

I can barely see. It's been a very long two days but hopefully tomorrow will be better and more productive. Need sleep now. Good night!

We need to sleep as well. Good night!

Good night! Even though you wrote that in the morning :-) .. hope you're sleeping well my good friend (though I saw you went ahead and did some of the above anyway)!

UPDATE 0

With commit 11dfe51c6cbd70bbbdbc60d9fc9b10781222adc3 we have moved the IOCCC Quick Start Guide:

moved IOCCC Quick Start Guide

Created quick-start.md to hold the FAQ 0.0 content.

Used sgit(1) to change:

• faq.html#enter ==> quick-start.html#enter
• faq.html#enter_questions ==> quick-start.html#enter_questions
• faq.html#step_0 ==> quick-start.html#step_0
• faq.html#step_1 ==> quick-start.html#step_1
• faq.html#step_2 ==> quick-start.html#step_2
• faq.html#register ==> quick-start.html#register
• faq.html#step_3 ==> quick-start.html#step_3
• faq.html#step_4 ==> quick-start.html#step_4
• faq.html#step_5 ==> quick-start.html#step_5
• faq.html#step_6 ==> quick-start.html#step_6
• faq.html#step_7 ==> quick-start.html#step_7
• faq.html#step_submit ==> quick-start.html#step_submit

Via:

sgit -e 's/faq\.html#enter/quick-start.html#enter/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#enter_questions/quick-start.html#enter_questions/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_0/quick-start.html#step_0/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_1/quick-start.html#step_1/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_2/quick-start.html#step_2/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#register/quick-start.html#register/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_3/quick-start.html#step_3/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_4/quick-start.html#step_4/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_5/quick-start.html#step_5/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_6/quick-start.html#step_6/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_7/quick-start.html#step_7/g' '*.md' '*.hdr' 'inc/*.html'
sgit -e 's/faq\.html#step_submit/quick-start.html#step_submit/g' '*.md' '*.hdr' 'inc/*.html'

The former FAQ 0.0 section in faq.html now just refers to quick-start.html.

Modified menu and non-JS menu so that "Enter the IOCCC" refers to quick-start.html.

Changed bin/gen-top-html.sh VERSION from "1.4.10 2024-11-23" to "1.4.11 2025-01-09".

Performed make www on macOS to complete the above.

Yes I just did a pull to look at updating this stuff and I saw you took care of it, thanks!

Nice to see you used sgit(1) a lot :) .. though it's not the first time.

I'll open those issues and then I'll see if I can commit the fix to txzchk (have to update version which means using sgit as well actually). I also have to do the regexp update now i think on it .. and do that in jparse also. Okay well I'll get to that when the email comes through and I can more easily find it. Everything is syncing from over 24 hours now so not everything has come through yet (or if it has I haven't yet seen it). I have an hour and then I'll be up away for a bit (that'll be at about 14:30 UTC).

Hope you had a nice sleep!

[xexyl]

@tcort makes a good suggestion and point:

add an option to mkiocccentry(1) to run iocccsize on your prog.c as well as run tests on the Makefile, the remarks.md and any extra files as well, to verify that everything seems in order WITHOUT making the tarball. Maybe call it --check-only or --dry-run or whatever

We think the idea of @tcort with a --dry-run would be a good option. With --dry-run, there would be no reason ask the user for answers/inout .. just check things and report on any problems.

But what about a tests such as txzchk(1) do? Without prompting the user, how would it run thru its motions? Well first we need a --random-seed integer option. See below:

Along that same idea, one could have the following option --random-seed integer. Like --dry-run, there would be no user prompting. Instead the tool would use pseudo-randomly generated answers and go thru the full motion of forming a submission WITH THE ONLY DIFFERENCE would be that the final prompt would not print info about uploading to a slot, but instead print something like:

Random seed 12345 test is successful.

Because --random-seed 12345 was used, the filename.tar.bz2 is not suitable for uploading.

Instead of the code reading answers from stdin (or the answers file), a call to generate a pseudo-random string (and one that conformed to what would otherwise be a valid input) that would be used.

Returning to the --dry-run: This command line option would be an alias for --random-seed ((SOME_INTEGER)).

So if someone did:

mkiocccentry --dry-run work_dir prog.c Makefile remarks.md

At the end, if all is well, instead of print info about uploading to a slot, it would print:

Dry run test is successful.

Because --dry-run was used, the filename.tar.bz2 is not suitable for uploading.

UPDATE 0

One way to implement --random-seed integer would be to call srandom(integer) and then use random() to drive the generation of a pseudo-randomly generated answers file and then have mkiocccentry use that generated random answers file.

Obviously the lines in the answers file would not be "completely random" stuff. The code would pseudo-randomly generate strings that conformed to input requirements.

One would use a seeded pseudo-random number generator with an integer seed argument BECAUSE the result would be repeatable. So of a problem were to be discovered, once corrected the result could be re-tried.

UPDATE 1

The --random-seed integer system would be a useful test of the complete system. Completely "hands free" as the expression goes.

Users could use --dry-run to test their files. In this case it would be using a well known integer that we could select.

The implementation of this would NOT be intrusive of the mkiocccentry(1) code because both --dry-run and --random-seed integer simply generate a pseudo-random strings that go into an answers file that mkiocccentry(1) uses.

Just opened a feature request issue for this: #1069.

[lcn2]

Reading

There is a lot to read. If printed, there would be over 180 US Letter sized pages to read (FAQ 121 pages, Guidelines 33 pages, Rules 18 pages, Markdown Guidelines 11 pages, etc).

My main cause for overwhelm is that there are a lot of details about a lot of things that aren't an obfuscated C program. A lot of emphasis is placed on the validity of the submission tarball and JSON files. Initially, I thought these needed to be hand crafted or modified from a template. Instead, it looks like mkiocccentry(1) generates them. If the tool generates them, then I would assume it only generates valid files and anyone who uses the tool wouldn't have to worry about details like no_comment is REQUIRED in the JSON files.

Suggestion: Consider moving the details about these files into a separate document ("submission tarball specification") as it seems difficult to make an invalid entry with mkiocccentry(1) and most people wouldn't need to worry about the specifics.

We believe this can be improved. Your idea about modding details into separate files is a good one.

Some of this newer style was done with the submit server process where the details were put into a separate web pages.

Moreover we could create a mini-faq.md file that would be very short, and point to more details in the faq.md file for those who are curious, @tcort

UPDATE 0

We have time to do things like this: This is we put about a month into the IOCCC28 scheduled "pending" phase.

Thank you, @tcort, for your suggestions.

[SirWumpus]

Maybe quick-start.md instead of mini-faq.md?

[xexyl]

Maybe quick-start.md instead of mini-faq.md?

I think both have merit. The quick start one could be for those who are new to the IOCCC and maybe those who are new to the new way but a mini FAQ could be (just saying this quickly as I have to go again) something like the old FAQ. Maybe.

[lcn2]

Maybe quick-start.md instead of mini-faq.md?

I think both have merit. The quick start one could be for those who are new to the IOCCC and maybe those who are new to the new way but a mini FAQ could be (just saying this quickly as I have to go again) something like the old FAQ. Maybe.

We like @SirWumpus improved filename suggestion.

We recommend that the filename / named tags of faq.md and faq.html NOT change very much. New, more brief content should have a different name.

[xexyl]

Maybe quick-start.md instead of mini-faq.md?

I think both have merit. The quick start one could be for those who are new to the IOCCC and maybe those who are new to the new way but a mini FAQ could be (just saying this quickly as I have to go again) something like the old FAQ. Maybe.

We like @SirWumpus improved filename suggestion.

We recommend that the filename / named tags of faq.md and faq.html NOT change very much. New, more brief content should have a different name.

That sounds reasonable to me.

[xexyl]

I just opened an enhancement about the 'simplifying' the command line interface: #1070.

As you'll see I do have some concerns if there's no way to disable it but obviously if more people like the idea then that should be the default! I just need a way to disable it. And then since I'll probably be helping with it anyway I can just go ahead and do that. But perhaps we can figure out which way is preferred. How I don't know. it seems like this repo might not be monitored that much but maybe it is and they just don't look at it .. but perhaps if this is brought up (a question) it would be better at the winner repo ?

Anyway feel free to assign it to me and I'll look at it after IOCCC28!

[lcn2]

Hello @tcort

The latest commit to the repo contains:

Added -s seed to mkiocccentr(1) seed a pseudo-random generator, then generate a random_answers.seed file with pseudo-random answers, and then to use that as if -i random_answers.seed had been called with pseudo-random answers. This is useful as a dry run in that one does not have go thru the interactive process of answering questions.

Added -d as an alias for -s 21701.

So this can be used as a dry run:

mkiocccentry -d workdir prog.c Makefile remarks.md

A set of pseudo random answers will be generated, without any need for you to intervene. If all is well the command completes with a compressed tarball and submission directory under workdir.

See the mkiocccentry(1) man page, or just try it and see.

Obviously this is just for testing as the result is not suitable for a submission. Nevertheless it is a quick and easy way to check.

Both -d and -s seed turn on -E which will cause mkiocccentry(1) to abort with an error and exit 1, if there are any warnings. This -E mode makes it easier for you to see if something is a problem. And while in some cases, interactively you can override some warnings (although at some risk), it does give you a "dry run" check of things.

We hope you find this useful.

[xexyl]

Hello @tcort

The latest commit to the repo contains:

Added -s seed to mkiocccentr(1) seed a pseudo-random generator, then generate a random_answers.seed file with pseudo-random answers, and then to use that as if -i random_answers.seed had been called with pseudo-random answers. This is useful as a dry run in that one does not have go thru the interactive process of answering questions.

Added -d as an alias for -s 21701.

So this can be used as a dry run:

mkiocccentry -d workdir prog.c Makefile remarks.md

A set of pseudo random answers will be generated, without any need for you to intervene. If all is well the command completes with a compressed tarball and submission directory under workdir.

See the mkiocccentry(1) man page, or just try it and see.

Obviously this is just for testing as the result is not suitable for a submission. Nevertheless it is a quick and easy way to check.

Both -d and -s seed turn on -E which will cause mkiocccentry(1) to abort with an error and exit 1, if there are any warnings. This -E mode makes it easier for you to see if something is a problem. And while in some cases, interactively you can override some warnings (although at some risk), it does give you a "dry run" check of things.

We hope you find this useful.

Please bug me Landon if I forget in the next day or so to not update the man pages and documentation over there.

[lcn2]

((Text from GH-discussioncomment-11855354 included here))

Please bug me Landon if I forget in the next day or so to not update the man pages and documentation over there.

Did you perform the above request, @xexyl ?

[xexyl]

We hope you find this useful.

Please bug me Landon if I forget in the next day or so to not update the man pages and documentation over there.

Did you perform the above request, @xexyl ?

Well you had done the man pages so that was not necessary. But I added it to the FAQ and guidelines - so yes.