Bug: The opening README.md isn’t useful

[lcn2]

Is there an existing issue for this?

• [X] I have searched for existing issues and did not find anything like this

Describe the bug

The contents of README.md was helpful for someone willing to test the code, but it is not useful for someone who wishes to use the tools in this repo to form a submission to the IOCCC.

What you expect

We expect to first see a very short, “TL;DR class” message that would get someone who wanted to form an IOCCC submission, started.

Following the TL;DR, expect to see a “quick start guide” on how to form an IOCCC submission.

Following a “quick start guide”, we expect too see a few well chosen links to FAQs into “the other repo”, and maybe this FAQ.md.

Environment

- OS: any
- Device: eyeballs 
- Compiler: the mind

bug_report.sh output

/dev/null

Anything else?

We recommend that to keep things somewhat short. Better accomplish more with less text.

There are plenty of man pages, detailed FAQs and readable source code for the curious and inquisitive. The audience for the README.md, instead, is someone wants to get their code submitted to the IOCCC.

We do NOT need to explain how to use every tool in this repo, as the current README.md does now. We need, for the somewhat impatient, how they can use this repo to form their submissions.

Keep in mind that the audience for the README.md file is NEITHER a developer of is repo, NOR a tester of this repo.

Keep in mind that the person wishing to form a submission might not have used GitHub before and only came here because some post somewhere, or some FAQ somewhere, or some told them to come here to form a submission. They probably just want to get their code submitted, perhaps in a rush to mean the end of a closing contest deadline, so they don’t want to have to wade through a lot of text to get their task done.

Keep in mind the I in the IOCCC is International and that English might not be their primary language. While you don’t have to use simple child-like language with someone capable of writing a potentially winning IOCCC entry, you probably should eschew esoteric and erudite dialogue full of multisyllabic vocabulary in writing the “TL;DR + QuickStart guide + a few well chosen FAQ links” that the short but useful README.md should strive to be. :)

See GH-issuecomment-2336464584 for an important note on adding a requirements list to the new README.md file.

[xexyl]

I was actually going to work on this soon ... will read this more later on. I have other things I have to do and then have to work out the other issue brought up by me earlier on and then open another issue for the finalising things before the code freeze and I also have something else I have to do unrelated but I hope to get to this today.

Please do assign this to me though.

[xexyl]

One of the things I was going to suggest actually is a new file where the how to help test would be put in a different file .. but don't know what the file would be called. Please give a suggestion. The tools can also be put in either a different section of the README.md or it can be put in another file that gives some idea to those who want to know.

Anyway must go for a while .. thanks for assigning.

[SirWumpus]

Should the original README be moved to test_ioccc/ which has no README?

[lcn2]

One of the things I was going to suggest actually is a new file where the how to help test would be put in a different file .. but don't know what the file would be called. Please give a suggestion. The tools can also be put in either a different section of the README.md or it can be put in another file that gives some idea to those who want to know.

Perhaps some of the existing README.md content could be moved into a new how-to-test.md file. Even so, such how-to-test.md shouldn't imply that the code in this repo is new, untested or fragile. The audience for the how-to-test.md contest is someone who is willing to test, is capable of doing such a task and just needs both a starting "what to test" and then "how to report something that needs fixing".

When the IOCCC goes into "test mode" and the public is invited to try things, the how-to-test.md could be useful.

Anyway must go for a while .. thanks for assigning.

You are most welcome.

UPDATE 0

Perhaps instead of how-to-test.md, it should be called testing-guide.md?

[lcn2]

Should the original README be moved to test_ioccc/ which has no README?

That's a good idea.

Then the top level testing-guide.md could a shorter focus on "how to test" and "how to report any problems/issues" and make reference to the revised test_ioccc/README.md file.

[xexyl]

Should the original README be moved to test_ioccc/ which has no README?

That's a good idea.

Then the top level testing-guide.md could a shorter focus on "how to test" and "how to report any problems/issues" and make reference to the revised test_ioccc/README.md file.

I agree with both ideas! Thanks @SirWumpus as well.

[xexyl]

Will move the file over soonish. Then continue what I was working on.

[xexyl]

Actually I can't easily move it over as simply as git mv .. as it would mean that there is no top level README.md file. This will require a bit more work and I am currently trying to come up with a solution for the make test failing in mkiocccentry's jparse/ without breaking it in the jparse repo. I have other things I will have to do today too but right now working on this. It is proving to be a pain so far.

[xexyl]

Okay so it works now in jparse repo but the question is will it work in this repo. Have to try this out next.

[xexyl]

It works! Although if one runs:

cd jparse/test_jparse
./jparse_test.sh -d test_JSON

it will fail and they'll have to provide instead:

./jparse_test.sh -d test_jparse/test_JSON

which might seem confusing. It is done by the $TOPDIR hack except in this case it also checks for ../../jparse.c.

I am wondering if there is a way to get it so one need not specify the test_jparse/ in front of the test_JSON in the case that they are in a subdirectory. On the other hand if documentation notes it it might not be that big of a problem. I wonder.

[SirWumpus]

It is possible to git mv README.md someplace So what if there is no top README for one commit. After the mv commit, just touch README.md and/or start editing the top level. Don't push anything till the 2nd commit with the new README is done.

[xexyl]

It is possible to git mv README.md someplace So what if there is no top README for one commit. After the mv commit, just touch README.md and/or start editing the top level. Don't push anything till the 2nd commit with the new README is done.

That is true but I was hoping to do it quickly initially so I could go back to the other task (now I'm updating documentation before a commit). That's not possible until after I get the jparse stuff done.

[xexyl]

The make test in this repo under jparse should be resolved now. Running make release now to be sure. If this does happen it will be committed. But another question comes to mind. However as that question is more of a topic for preparing for a code freeze I will put it in the new issue when I open it (soon I hope - if the make release works then hopefully after the commit .. if it does not I'll have to fix that first).

[lcn2]

We added a TODO for issue #2239 in the other repo to complete this issue.

[lcn2]

We believe we have addressed all of the current questions that still need answering at this time. If we've missed something or something else needs to be clarified, please ask again.

[SirWumpus]

Do you already or is it worth documenting in a README (probably top most) the minimum versions required of dependencies? Compilers, gnu make, shellcheck, Haskell, inpend, picky, etc. The debug output can be voluminous (high noise, low signal) and hard to spot obvious failures like missing libraries etc. Some sort of manual check list for a/ just submitting your entries b/ for dev/testers helping with tools.

[lcn2]

Do you already or is it worth documenting in a README (probably top most) the minimum versions required of dependencies? Compilers, gnu make, shellcheck, Haskell, inpend, picky, etc. The debug output can be voluminous (high noise, low signal) and hard to spot obvious failures like missing libraries etc. Some sort of manual check list for a/ just submitting your entries b/ for dev/testers helping with tools.

Thanks 🙏 @SirWumpus.

Given GH-issuecomment-2335054311, we won't need to list a number of those methods as prerequisites as they won't be required.

We also need to keep in mind that make prep and make release are for repo maintenance and NOT for the general public.

Someone who simply wishes to submit to the IOCCC just needs to do make all. So that should reduce the list even more.

Perhaps the section in the new README.md on prerequisites just needs to focus on what is needed for make all. Then there could be, at the very bottom, a p.s. section for repo maintainers that makes it clear this is not necessary for people wishing to submit to the IOCCC, a maintainers prerequisite list.

[xexyl]

I actually have this in the back of my mind. But before I can get to this I have the other things to do.

I agree we don't need to list dependencies since they're all included in the repo.

Thanks for the reminder though! I certainly will be getting to this. I started the other task but I have other things i have to do first before I can get back to the repo, either today or else tomorrow.

[xexyl]

I actually have this in the back of my mind. But before I can get to this I have the other things to do.

I agree we don't need to list dependencies since they're all included in the repo.

Thanks for the reminder though! I certainly will be getting to this. I started the other task but I have other things i have to do first before I can get back to the repo, either today or else tomorrow.

Well okay the extra tools in make release/make prep are not included but those are not needed for anyone but those who maintain the repo (or develop for it).

[lcn2]

As suggested/implied by @SirWumpus in GH-issuecomment-2335141385 with follow ups of GH-issuecomment-2336406441 and GH-issuecomment-2336407112, we need a list of dependencies for those who just need to submit to the IOCCC in a new README.md as well a "P.S. requirements for repo maintainers" at the bottom of a new README.md.

We must NOT go overboard in listing decencies. We do NOT want a pedantic list of all possible commands and functions, nor do we want to pull in all kinds of standards.

We do NOT need to list secondary requirements as this will become long and detailed. For example, in the "P.S. requirements for repo maintainers" section the mention of "shellcheck version 0.10.0 or later" is sufficient as there is no need to go into detail what some platform might require for shellcheck to be installed and work on that platform.

What follows WILL BE EDITED over time, so below is just an initial guess. We expect to modify this comment as needed over the next "few days". MOREOVER we will not attempt to put in the fully formed links. Instead will reference a resource that can be used to form a proper link inside of a parenthetical comment.

We recommend that we keep the "requirements for IOCCC submitters", short, small and easy to read:

# Requirements to use the mkiocccentry toolkit to submit to the IOCCC

* Unix-like environment (see IOCCC rule 20 "next/rules.heml/#rule20")
* GNU Make version 3.81 or later (see IOCCC FAQ for "faq.html#make_compatibility")
* C compiler that understands "-std=gnu17"
* bash version 5.1.8 or later

Then at the bottom of the new README.md we need "P.S. requirements for repo maintainers":

# P.S. requirements for repo maintainers 

**IMPORTANT NOTE:** If you are submitting to the IOCCC, you do **NOT** need to meet the requirements below!

For those who need to develop and maintain this repo, and **in addition to the list of requirements listed above**:

* bison version 3.8.2 or later
* flex version 2.6.4 or later
* independ, version 1.00 2022-12-27 or later  (see https://github.com/lcn2/independ)
* shellcheck version 0.10.0 or later (see https://github.com/koalaman/shellcheck.net)
* seqcexit version 1.12 2022-11-09 or later (see https://github.com/lcn2/seqcexit)
* picky version 2.6 or later (see https://github.com/lcn2/picky)
* a sense of humour :-)

UPDATE 0a

We added a link to the comment at the bottom of the top level TODO comment.

Made minor edits to the above.

UPDATE 1

Instead of adding a "P.S. requirements for repo maintainers" to the end of the new README.md file, put that content into a soup/README.md file.

[SirWumpus]

For terseness instead of

    * bison version 3.8.2 or later

Abbreviate it:

    * bison version 3.8.2+

Q: Should the requirements for maintainers go in the test_ioccc README so as to avoid a length top-level README and possible confusion of contestants?

For

    * C compiler that understands "-std=gnu17"

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

[SirWumpus]

For the maintainers README (I assume in test_ioccc/README.md) maybe list the most common / useful make targets. Some times Makefile go a little overboard on targets for xyzzy and plugh etc. that even reading the the file its not always clear at first. (Not that you guys would do that, right? Like frivolous timestamps? 😄)

[lcn2]

For the maintainers README (I assume in test_ioccc/README.md) maybe list the most common / useful make targets. Some times Makefile go a little overboard on targets for xyzzy and plugh etc. that even reading the the file its not always clear at first. (Not that you guys would do that, right? Like frivolous timestamps? 😄)

I can think of 4 that are useful for someone submitting to the IOCCC:

• make all
• make clobber
• make test
• make bug_report

All the rest are useful for maintainers, devlopers, and for the curious 👀 as an "RTFS" rule. 🤓

[xexyl]

For terseness instead of

    * bison version 3.8.2 or later

Abbreviate it:

    * bison version 3.8.2+

Q: Should the requirements for maintainers go in the test_ioccc README so as to avoid a length top-level README and possible confusion of contestants?

Well in the case you cite it's actually for jparse and maybe should actually not be included here except in the jparse subdirectory which comes from the repo.

Mind you I am not looking at it and I can barely see right now: still waking up.

As for the use of the + instead like you suggested that might be something but if so again that should be for the other repo.

But I am not sure if it is really necessary one way or another.

As far as not confusing contestants that might be a good idea. But this IS the IOCCC! A little confusion is a good thing! 😀

But actually you are right I think. Those rules can be moved.

Instead of a README in the test directory there might be a new file for maintainers. Or perhaps not even that: we have make help after all.

What could go in the test directory though? As Landon says there are some rules that can be useful for others that are usually for us.

What all this is telling me is that maybe I need to get working on this part too. Unfortunately other things keep coming up. I will try getting to at least part of this today.

For

    * C compiler that understands "-std=gnu17"

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

Where is this please? Just to be sure we're talking about the same thing.

[xexyl]

For the maintainers README (I assume in test_ioccc/README.md) maybe list the most common / useful make targets. Some times Makefile go a little overboard on targets for xyzzy and plugh etc. that even reading the the file its not always clear at first. (Not that you guys would do that, right? Like frivolous timestamps? 😄)

To be fair to me: the timestamps have been extremely helpful to me and are not frivolous as you put it. But it can become overmuch esp with the subdirectories. Hence why they were removed. In retrospect for me I have timestamps in my prompt so probably not a big deal anyway to not have them.

Still your comment made me laugh and I appreciate that.

[lcn2]

Well in the case you cite it's actually for jparse and maybe should actually not be included here except in the jparse subdirectory which comes from the repo.

That is not correct, @xexyl. The jparse/ directory tree IS part of this repo (even though it was copied from the jparse repo). So those lines DO apply to the proposed "P.S." section at of the new README.md file.

UPDATE 0

Well now, the idea is that the former "P.S." stuff will go into the soup/README.md file.

[lcn2]

Instead of a README in the test directory there might be a new file for maintainers. Or perhaps not even that: we have make help after all.

We like this idea: Instead of complicating the proposed new top level README.md with a final "P.S." section for repo maintainers, put that proposed "P.S." stuff into a soup/README.md file. That's a view good idea, @xexyl ‼️

UPDATE 0

We added a note to that effect as a new UPDATE to GH-issuecomment-2336464584.

[lcn2]

For

    * C compiler that understands "-std=gnu17"

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

Where is this please? Just to be sure we're talking about the same thing.

It is in the Makefile set for this repo, and has been for quite some time. In particular, the Makefile says:

# C source standards being used
#
# This repo supports c17 and later.
#
# NOTE: at one point we used -std=gnu11 because there were a few older systems
#       in late 2021 that did not have compilers that (yet) supported gnu17.
#       While there may be even more out of date systems that do not support
#       gnu11, we have to draw the line somewhere. Besides, one of those systems
#       reaches its EOL on 30 June 2024 and that's three days away at this
#       point.
#
#   --------------------------------------------------
#
#   ^^ the line is above :-)
#
#C_STD= -std=gnu11
C_STD= -std=gnu17

[xexyl]

For

    * C compiler that understands "-std=gnu17"

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

Where is this please? Just to be sure we're talking about the same thing.

It is in the Makefile set for this repo, and has been for quite some time. In particular, the Makefile says:

# C source standards being used
#
# This repo supports c17 and later.
#
# NOTE: at one point we used -std=gnu11 because there were a few older systems
#       in late 2021 that did not have compilers that (yet) supported gnu17.
#       While there may be even more out of date systems that do not support
#       gnu11, we have to draw the line somewhere. Besides, one of those systems
#       reaches its EOL on 30 June 2024 and that's three days away at this
#       point.
#
# --------------------------------------------------
#
# ^^ the line is above :-)
#
#C_STD= -std=gnu11
C_STD= -std=gnu17

Right. I was going to use grep but I didn't get a chance with having to make other fixes.

[xexyl]

Well in the case you cite it's actually for jparse and maybe should actually not be included here except in the jparse subdirectory which comes from the repo.

That is not correct, @xexyl. The jparse/ directory tree IS part of this repo (even though it was copied from the jparse repo). So those lines DO apply to the proposed "P.S." section at of the new README.md file.

That's true. But what I was trying to say is that since the repo itself is synced here and since we do not require flex/bison to be installed it should not be a problem. By that I was referring to flex/bison. We do not require that.

Of course the README.md over there suggests that the libraries dbg and dyn_array have to be installed and I did not think of that. With that in mind it seems to me we have to add a note about this to this repo, maybe in the soup/ file as you thought of. Though .. I don't know if that's the right location or not.

But whether the flex/bison has to be noted here I do not know. It can be a passing comment but it's not really required so if we're going to shorten things this would be a way to do it.

This is what I was trying to say.

UPDATE 0

Well now, the idea is that the former "P.S." stuff will go into the soup/README.md file.

Yes ... that's a better idea though again I'm not sure if most people would check this location. That makes me wonder if it's the right place. But I'm kind of unsure even of all what we were talking about - unless it's the flex/bison thing. In that case I don't really even know where it belongs. It could be just as well in the jparse/README.md but as I observed and noted above that might be a problem since it also suggests one needs the other libraries installed.

[xexyl]

For

    * C compiler that understands "-std=gnu17"

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

Where is this please? Just to be sure we're talking about the same thing.

It is in the Makefile set for this repo, and has been for quite some time. In particular, the Makefile says:

# C source standards being used
#
# This repo supports c17 and later.
#
# NOTE: at one point we used -std=gnu11 because there were a few older systems
#       in late 2021 that did not have compilers that (yet) supported gnu17.
#       While there may be even more out of date systems that do not support
#       gnu11, we have to draw the line somewhere. Besides, one of those systems
#       reaches its EOL on 30 June 2024 and that's three days away at this
#       point.
#
# --------------------------------------------------
#
# ^^ the line is above :-)
#
#C_STD= -std=gnu11
C_STD= -std=gnu17

This being said. I'm still not sure what you are getting at @SirWumpus. Would you clarify what you mean by:

Maybe cite the rule # / guideline (the tools should not require a C compiler greater than what the contest accepts).

The rules/guidelines are about submissions and how they don't have to require such a compiler. I am not sure how you mean it when it comes to this repo though.

[xexyl]

For terseness instead of

    * bison version 3.8.2 or later

Abbreviate it:

    * bison version 3.8.2+

It is this that I was thinking of when I said it could be in the jparse repo itself. That being said:

git grep 'bison version 3.8.2 or later'

... shows nothing so it does not appear to be in this repo at all. Actually the only bison version string is in jparse/run_bison.sh.

What am I missing? Even so I don't think that (though it's hard to be sure without context) it needs to be changed.

Q: Should the requirements for maintainers go in the test_ioccc README so as to avoid a length top-level README and possible confusion of contestants?

I think this is actually a great idea, @SirWumpus, since the maintainers need the directory in test_ioccc much more than the others. That being said there are some tools in there that submitters will be using, at least indirectly: fnamchk comes to mind as one. That is used by txzchk which is called by mkiocccentry.

Maybe this is what Landon was getting at with soup/README.md? Is that the case, @lcnd2?

[xexyl]

I can think of 4 that are useful for someone submitting to the IOCCC:

• make all
• make clobber
• make test
• make bug_report

---

Cody felt a strange certainty that in this matter Landon was for once not so far from the truth as might be suspected; that he had somehow found a way to parse the Makefiles, and at least believed that it was by his own cunning. For one thing, he noted that Landon used I, and that seemed usually to be a sign, on its rare appearances that some remnants of old truth and sincerity were for the moment on top. But even if Landon could be trusted on this point, Cody did not forget the wiles of @SirWumpus. The 'parsing' may have been allowed or arranged, and well known to the maintainers. And in any case Landon was plainly keeping a good deal back from the Makefiles.

-- The Two Towers, The Black Gate Is Closed, p. 643, HarperCollins

---

All the rest are useful for maintainers, devlopers, and for the curious 👀 as an "RTFS" rule. 🤓

I agree .. even with the above in mind. That should be all the make rules needed. With that in mind I can kind of copy and adapt the FAQ I added to the other repo about make rules into this repo. Want me to do that?

[lcn2]

Yes ... that's a better idea though again I'm not sure if most people would check this location.

Most people are not developers. And if the developer doesn't bother look into soup/ and other sub-directories, then we might not want them to do very much development! 🤓

[xexyl]

Yes ... that's a better idea though again I'm not sure if most people would check this location.

Most people are not developers. And if the developer doesn't bother look into soup/ and other sub-directories, then we might not want them to do very much development! 🤓

That's true. But I was referring there to the fact that people might be confused: in this repo the dbg and dyn_array libraries do not have to be installed but the jparse repo claims otherwise.

Ah .. perhaps it should go in the FAQ? I think that might work. If you agree with that I can do that.

[lcn2]

Yes ... that's a better idea though again I'm not sure if most people would check this location.

Most people are not developers. And if the developer doesn't bother look into soup/ and other sub-directories, then we might not want them to do very much development! 🤓

That's true. But I was referring there to the fact that people might be confused: in this repo the dbg and dyn_array libraries do not have to be installed but the jparse repo claims otherwise.

Ah .. perhaps it should go in the FAQ? I think that might work. If you agree with that I can do that.

answer

The answer to your implied question is yes.

[xexyl]

Yes ... that's a better idea though again I'm not sure if most people would check this location.

Most people are not developers. And if the developer doesn't bother look into soup/ and other sub-directories, then we might not want them to do very much development! 🤓

That's true. But I was referring there to the fact that people might be confused: in this repo the dbg and dyn_array libraries do not have to be installed but the jparse repo claims otherwise.

Ah .. perhaps it should go in the FAQ? I think that might work. If you agree with that I can do that.

answer

The answer to your implied question is yes.

Right. Remind me if I don't get to this soon!

[lcn2]

Once this issue #955 is finished we can set a code freezer on this repo and release it and check off 2 tasks Great Fork Merge tasks in the "other repo".

See GH-issuecomment-2371137632.

UPDATE 0

With the recent unblocking work-around in the "other repo", this issue now remains the primary concern blocking a release and later code freeze 🥶 of this repo. See the open TODO items in GH-issue-2170848675 for details, @xexyl.

[xexyl]

Once this issue #955 is finished we can set a code freezer on this repo and release it and check off 2 tasks Great Fork Merge tasks in the "other repo".

See GH-issuecomment-2371137632.

UPDATE 0

With the recent unblocking work-around in the "other repo", this issue now remains the primary concern blocking a release and later code freeze 🥶 of this repo. See the open TODO items in GH-issue-2170848675 for details, @xexyl.

Plus the other issue I opened a while back .. yes. I will very possibly be able to continue this later on today but I am not sure of that either. Otherwise I hope to tomorrow morning.

[xexyl]

I know I've not got to this for some days .. sorry! I hope to in the next week or so but I am trying to work on several things and additional things in that thing called 'real life' have also been going on ...

[xexyl]

I know this is important for the code freeze but I've been focusing on the other issue first. I am going to check that 'other repo' to make sure I did not miss anything (though maybe I will not do a thorough job) and then I have other things I need to do.

I did do some useful things at least but not much in the way of code freeze I am afraid. Maybe tomorrow. We shall see!

[lcn2]

The README.md file looks useful to someone who has COVID 🦠😷

As such, the README.md file is longer "isn't useful" 😁so we can close this issue.

[xexyl]

The README.md file looks useful to someone who has COVID 🦠😷

As such, the README.md file is longer "isn't useful" 😁so we can close this issue.

Best wishes for a further recovery!

I have made progress elsewhere: jparse and the website.

I do not know how tomorrow will go but I will not open any pull requests until you're all recovered.

Get some rest and stay hydrated and get well soon my friend!

And thanks for the laugh - even though it is dark.

[lcn2]

The README.md file looks useful to someone who has COVID 🦠😷 As such, the README.md file is longer "isn't useful" 😁so we can close this issue.

Best wishes for a further recovery!

I have made progress elsewhere: jparse and the website.

I do not know how tomorrow will go but I will not open any pull requests until you're all recovered.

Get some rest and stay hydrated and get well soon my friend!

And thanks for the laugh - even though it is dark.

You are welcome. If more needed to be dine with README.md feel free to do so.

[xexyl]

The README.md file looks useful to someone who has COVID 🦠😷 As such, the README.md file is longer "isn't useful" 😁so we can close this issue.

Best wishes for a further recovery! I have made progress elsewhere: jparse and the website. I do not know how tomorrow will go but I will not open any pull requests until you're all recovered. Get some rest and stay hydrated and get well soon my friend! And thanks for the laugh - even though it is dark.

You are welcome. If more needed to be dine with README.md feel free to do so.

Admittedly i did not read it again (to be sure) but if during your current illness you can understand it just fine I would say it's just fine! Thanks. Glad this is sorted.