search

ioccc-src / temp-test-ioccc

Temporary test IOCCC web site that will go away
Creative Commons Attribution Share Alike 4.0 International
28 stars 6 forks source link

Enhancement: improve the consistency of winning directories #3

Closed lcn2 closed 1 month ago

lcn2 commented 1 year ago

Scope - About this issue

Where reasonable, try to make winning entries consistent.

Consistency includes things such as:

NOTE: This writeup is subject to changes and revisions as the understanding of this issue evolves / improves. Check back to this note from time to time. When modification are made to this comment, we will try to add a note indicating that the scope of this issue has been updated.

TODO

Suggested section:

NOTE: Feel free to come up with better section titles. A better section title may suggest itself as the FAQs are being written as well. NOTE: Once the FAQ is mostly done, ask us add "About the IOCCC" FAQs that have come in over the years. Adding raw detail text for "About the IOCCC" FAQ section is beyond the scope of this issue. The above TODO is intended to not only build out the framework for the FAQ, but to populate it with most of the easier FAQ entries.

NOTE: either search for and find it and add it to the directory - referring to it in the README.md file or note that the image is missing and ask for help in finding it - ask for a pull request to add it as 1984/anonymous/tattoo.jpg.

NOTE: Also consider this as entry for bugs.md. This probably needs we need a Status of "Missing files".

NOTE: This includes: checking that files don't refer to .text files when they should be .markdown or .md or whatever (in fact make it consistent and make sure to change the references to be the new form but make sure to do it carefully). Ideally they link to html files that are generated instead but whether those exist here or not.

NOTE: Regarding the 3 FAQ.md TODOs above:

The audience for the 3 FAQ.md TODOs above are different. The 1st TODO above is a web site change that needs to refer the person to the winner GitHub repo and submitting a pull request. The 2nd TODO above is about how a winner can update their entry by submitting a pull request. The 3rd TODO above is about how someone other than the winner can submit a pull request.

In the case of the 1st " change to the web site" TODO above: one needs to explain that the web site is managed via the GitHub winner repo and that they need to submit a pull request the winner GitHub repo.

In the case of the 2nd " how a winner can submit" TODO above: Winners will be given a "wider set of latitude" when it comes to changing their winning entry, so the bugs.md page is less applicable. Nevertheless the winner will need to submit a pull request against the winner GitHub repo.

In the case of the 3rd "change someone else's entry" TODO above, it should tell the person to be sure to read the bugs.md page as well AND that they will need to issue a pull request against the winner GitHub repo.

NOTE: What is missing is how someone who is reading the web site and who may not be familiar with git / GitHub does a pull request. Such a person needs know how to create a GitHub account if they don't have one, how to fork a repo, how to modify the forked repo on their computer, how to push the changes back to the forked repo, and then how to create a pull request against the winner repo. Such information does NOT belong in the bugs.md page, it belongs on the FAQ.md page, see the next TODO item about GitHub pull requests.

NOTE: It would be a good idea for the bugs.md page should refer someone to FAQ.md page about how to submit a GitHub pull request.

This will involve explaining that because the web site is managed via the winner GitHub repo, to report a problem they need to open an issue against the winner GitHub repo, including create a GitHub account if they don't have one.

It would be a good idea for this FAQ to mention the 'bugs.md' page.

The FAQ should consider how someone who is not familiar with GitHub, can review the list of open winner repo issues and other add a comment to an existing issue or open a new issue.

NOTE: Currently most of the README.md files are just ASCII text with some inconsistent indentation and a few Markdown # added. Come up with a way to display things like the author information, etc. Turn it into a true Markdown file, not simply an ASCII text file. 😜

NOTE: Apply markdown formatting to README.md files, for example turning:

Some text
---------

into a highlighted level 3 or more entry.

NOTE: In places where the author added highlighted text at level 1 to 2, reduce the level to level 3 or more. The start of the "Author's remarks:" should be at level 2. Everything else should be below that level.

NOTE: In cases where shell commands are used, place them under a download code block starting with ```sh.

NOTE: Where text is indented, with the exception of the top level winner "address / URL info" section, consider if such text should not be intended.

NOTE: Long ago when README.md files were just ASCII text, various methods if highlighting (with underscores, ALL CAPS), blank lines, and indenting were used to help "highlight" text. Such ASCII text formatting needs to be converted to use markdown.

We need only two blank lines before and one blank line after the following markdown headers:

And of course, zero blank lines before and only 1 after the top "# Award" line.

We don't need apply these rules to any markdown header lines that the author may have added to their "## Author's remarks:" beyond that which is noted above.

All this will help critical markdown headers in README.md stand out when viewing the raw markdown without adding too many blank lines. It will also help README.md look more consistent.

In a few cases, the README.md uses "Original code", or "Original build", or "Original use", etc. Should those instances use the word "Alternate" instead of "Original"? Maybe or maybe not.

All README.md files (unless there is some very good reason for an exception) must have the following markdown headers:

In some cases these mandatory lines are missing, or there is a typo/different wording used in the README.md file.

In cases where there are NO Author's remarks, the text below the header (after a blank line) should read:

No remarks were provided by the author.

Should the "##Try:" be a mandatory markdown header as well? Perhaps not, but if not then most README.md files should probably have one anyway.

This tool is beyond the scope of this issue and will be part of a tool that builds and maintains the web site. The existing tool under tmp/ will be considered in so far as the existing current status.json file format is kept.

The authorship information that may be found in the SQL data that is referenced in issue #4 should be used to update / correct / improve authorship information. In some cases the authorship information was limited in the original file because there was "who won" elsewhere.

Eventually this authorship information will be auto generated. But until that happens, we need to manually improve the authorship information. Therefore the authorship information needs to be consistent in format:

NOTE: In cases where the author information contains a symbol that markdown would interpret, such as a underscore or backquote, that needs to be modified to prevent accidental markdown information.

NOTE: In some cases when the README.md file was a simple text file, blank lines were sometimes added to help format an author information such as putting an home page URL with a precedent blank line. Such empty or blank lines should be eliminated.

NOTE: Author information should refer to their county. You could use the county code, or the text of the county. You may wish to refer to a file in mkiocccentry repo source code for such translation.

Makefiles

We need to try and make Makefiles reasonably consistent in type and layout.

Pay attention to Makefile variable consistency use.

Pay attention to use of whitespace, especially in comments.

The use of the Makefile variable, ${ECHO} should be replaced with just echo and the ECHO= Makefile variable should be removed.

NOTE: While some warnings cannot be silenced, those that can should be silenced with -Wno-stuff flags added to the ${CSILENCE} Makefile variables.

NOTE: The first "CSILENCE=" line should be setup to silence the generic cc warnings with -Wno-stuff. The 2nd "CSILENCE+=" line in the clang area is for clang. This line appends to the generic cc warnings for clang. The 3rd "CSILENCE+=" line in the gcc area: but if you need to it is there for a final set of changes. That line too appends the generic cc warnings, but in this case go gcc.

NOTE: Be sure that the pfmt (version 1.0.1 2023-03-23 or later) and csilence (1.0.2 2023-07-07 or later) code is up to date.

NOTE: We recommend you first silence warnings on macOS first. Then carry those Makefiles over to Linux and add more -Wno-stuff for linux.

NOTE: We recommend, for a given entry on macOS, that you first clear out all CSILENCE values in all 3 Makefile locations. The use:

csilence -v 1 -c -g clobber all alt

To just print the recommendation for the generic cc CSILENCE first line. Once the Makefile us edited rerun the command. If your edit was successful, no warnings should be printed by the command.

Next run it for clang only:

csilence -v 1 -C -g clobber all alt

To just print the recommendations for clang. Add those to the 2nd clang CSILENCE=+ line. Rerun the command to verify nothing is printed by the command.

Last, try to run the entire set on the entry. 

csilence -v 1 clobber all alt

And make any last minute changes that are needed.

Finally check all entries with:

find ???? -mindepth 1 -maxdepth 1 -type d | while read dir; do
    (cd "$dir"; echo =-=-= "$dir" =-=-= ; csilence -v 1 clobber all alt)
done 2>&1 | less

Once that is clean for macOS, copy the makefiles over to Linux and do a similar procedure, but this time DO NOT remove the existing CSILENCE values in the Makefile, just append any new Linux generated values to them.

judges remarks / winner writeup / winner's remarks

The filenames containing " judges remarks / winner writeup / winner's remarks filenames" is all over the map. A common filename should be used, such as README.md.

Wosre still, in some cases there are multiple copies in different formats such as text and html. There should be ONLY one copy of the file, and that should be in Markdown format. For example in 2018/mills we have both hint.html and hint.text. In this case the one file is a copy of the other file. Only one copy should be kept (a quick check should be made to verify that to apparent duplicate files are in fast, duplicates). When it doubt, keep the text of markdown copy. If needed, marge the content into a single file if the copies have substantial differences.

NOTE: Later on, such markdown files will be rendered into html by a site building process. So the html copy should NOT be kept.

In cases where the " judges remarks / winner writeup / winner's remarks filenames" is just hint.text or winner_name.hint, it should be converted into a markdown format file README.md.

The content of having a "hint" file is going away. So hint.txt files, for example, need to become README.md. Such files should not be treated as spoiler files, but other files a user is encouraged to read.

filename extensions

The use of .text extension should be replaced with .txt where reasonable. Be careful when the file is some sort of "data file" where the .text extension may be required.

The use of .makrdown extension should be replaced with .md where reasonable. Be careful when the file is some sort of "data file" where the .markdown extension may be required.

index.html files in winner directories

These files in winner directories will be built by a tool that uses JSON files, HTML templates and the jval and jnamval tools (once they are ready).

This topic is beyond the scope of this issue.

years.hmtl links

This will be built by a tool that uses JSON files, HTML templates and the jval and jnamval tools (once they are ready).

This topic is beyond the scope of this issue.

orig and alt source files

This section has been replased per the comment 1766839666.

Here are the current rules for orig and alt source files:

A manual check to verify that the prog.orig.c has not changed might be a good idea as a sanity check.

If there is a reason to compile the original source code, make a copy (possibly modified copy) to port.alt.c or something like that.

orig and alt source file TODOs

See also comment 1766839666

When the Makefile rules are discussed, also mention make orig_prog_diff and mention make orig_alt_diff suggesting that those rules can help someone understand what changed.

If the README.md needs to discuss specific changes to the entry source code, refer to the appropriate diff rules.

The year level Makefile and the top level Makefile should support running entry level make orig_prog_diff and make orig_alt_diff rules.

See comment 1802524685

See comment 1802524685

Not only should the top section helps emphasize the desire for "low impact" bug fixes, and because some people might not read the top section of that file, every time we ask for someone to help fix a bug we should add a standout line near the top of the entry's bugs.md section, a line alone the lines (pun intended) of:

When fixing this bug, please strive for a "low impact" bug fix to the source code.

Or something short, surrounded by blank lines to help it stand out, near the top of the entry's bugs.md section.

Other TODOs

NOTE: In macOS when trying to run 2013/mills it did not work and macOS did not actually ask if I wanted to allow connections to it.

Move the stuff about compilers into 1986/marshall/compilers.md and add a simple "see also" reference to that new file in 1986/marshall/README.md.

Update bugs.md for the echo "Quartz .. | ./jaw as found in 1990/jaw/README.md as a bug and ask OTHER people to try and fix it.

See comment 1792689994 for more information.

See also comment 1792926524 as well as comment 1792942954.

There is a note in 1990/jaw/README.md about the echo "Quartz .. | ./jaw" that is actually a bug. Ask OTHER people to try and fix it by adding an entry to bugs.md and making the appropriate edits to 1990/jaw/README.md.

See comment 1901172231 and comment 1901148133.

Final TODOs

See comment 1792961765

See comment 1821159601 for more information.

This has been done in the fast a few times, but as entries have been modified a final check using the csilence tool should be done. See the text under the previous "Silence any compiler warnings" TODO for details.

NOTE: The above final check TODO will be done by @lcn2.

Perform a last minute quick scan to see of anything major / anything critical / anything glaring / anything important was missed.

See also:

xexyl commented 1 year ago

As you know I'm also EXTREMELY GOOD at this. However some things are not entirely clear to me as I get to below.

Scope - About this issue

Where reasonable, try to make winning entries consistent.

Consistency includes things such as:

  • [ ] winner Makefile
  • [ ] year Makefile
  • [ ] filenames
  • [ ] hint / judges remarks / winner writeup / winner's remarks
  • [ ] etc.

I have a problem with the hint/judges' remarks/winner write-up/remarks.

Namely that this is a matter of style and each winner will have a different style. I think it might be a mistake to do this. Also for judges' comments that might also be relevant.

On the other hand the year and Makefile names might be okay to change.

I have a concern with filenames also because this could break some entries.

NOTE: This writeup is subject to changes and revisions as the understanding of this issue evolves / improves. Check back to this note from time to time. When modification are made to this comment, we will try to add a note indicating that the scope of this issue has been updated.

Makefiles

We need to try and make Makefiles reasonably consistent in type and layout.

Pay attention to Makefile variable consistency use.

Pay attention to use of whitespace, especially in comments.

The use of the Makefile variable, ${ECHO} should be replaced with just echo and the ECHO= Makefile variable should be removed.

Okay that is reasonable.

source code filenames

In early years, all winning source code for a year was put into a single directory. As such, winner program names were based on the winner name (such as horton.c in 1994/horton). Such code should be renamed to prog.c now that winners are in their own directory.

Ah .. you mean entry code filenames. Okay but what about entries with more than one source file ? That could be unwise to rename alternative files. It also incidentally would have to align with any documentation (man pages included or in the case of one of my entires a FILES file .. that entry actually has some formatting fixes I need to make in the remarks).

Of course, the Makefile will need to be modified accordingly.

Of course.

In some cases, the program may not work when it is renamed to prog.c, for example. Is such code can be easily renamed, the Makefile should be modified to copy prog.c into the _requiredfilename.c and compiled under the original name. A note in the Makefile should be echoed indicating that such a copy is needed. For example:

Well! Two great minds think alike they say! :-) or as it is in German:

Zwei Doofe ein Gedanke

.. it's supposed to mean the above but it actually means two idiots one thought! :-)

prog: prog.c
        @echo 'The original winner source code was called ${ENTRY}.c so we rename it accordingly'
        ${CP} -f -v prog.c ${ENTRY}.c
        ...

Good idea.

The Makefile's clobber rule should remove the copy of the code that was made.

Okay.

judges remarks / winner writeup / winner's remarks

The filenames containing " judges remarks / winner writeup / winner's remarks filenames" is all over the map. A common filename should be used, such as README.md.

You're referring to for example the file: 2020/README.md, right?

Just want to be sure.

Wore still, in some cases there are multiple copies in different formats such as text and html. There should be ONLY one copy of the file, and that should be in Markdown format. For example in 2018/mills we have both hint.html and hint.text. In this case the one file is a copy of the other file. Only one copy should be kept (a quick check should be made to verify that to apparent duplicate files are in fast, duplicates). When it doubt, keep the text of markdown copy. If needed, marge the content into a single file if the copies have substantial differences.

I'm not sure how it's worse but the idea is to keep the markdown files - that seems reasonable esp with your below comment (which you told me before).

NOTE: Later on, such markdown files will be rendered into html by a site building process. So the html copy should NOT be kept.

That makes sense yes.

In cases where the " judges remarks / winner writeup / winner's remarks filenames" is just hint.text or winner_name.hint, it should be converted into a markdown format file README.md.

So are we renaming the hint.text .. ah, I see below.

The content of having a "hint" file is going away. So hint.txt files, for example, need to become README.md. Such files should not be treated as spoiler files, but other files a user is encouraged to read.

Other files? How do you mean? Like how I have included extra files with information them in my entries ?

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

filename extensions

The use of .text extension should be replaced with .txt where reasonable. Be careful when the file is some sort of "data file" where the .text extension may be required.

The use of .makrdown extension should be replaced with .md where reasonable. Be careful when the file is some sort of "data file" where the .markdown extension may be required.

The latter part of each is indeed a concern of mine esp if the entry cannot be compiled to test.

index.html files in winner directories

In some cases, a index.html file was created by taking a text of markdown file and rendering it into html. For example see 1985/applin.

In this case both 1985/applin/index.html and 1985/applin/hint.txt are duplicates and so the above commentary on " judges remarks / winner writeup / winner's remarks" applies, and only the 1985/applin/hint.txt file should be kept as README.md.

To determine if they're the same do you recommend something like:

$ rdiscount < hint.text > hint.tmp.html
$ diff -q ...
$ ..

?

years.hmtl links

If is important that links in the years.hmtl file still work!

When a file needs to be renamed, the link in years.hmtl needs to me modified.

When a file needs to be deleted, the ink in years.hmtl needs to be removed.

Next to the link in years.hmtl in some cases, an additional "- very short one line remark" should be added. This is specially true for the README.md file. Add a "- README" to the end of such a link line.

Please remind me what you mean by year.html..

When renaming a file in order to preserve the original file, HTML of the form "- original README" should be adde to the end of the line.

I'm not sure I I understand this part either. Would you please clarify?

An experiment of using the markdown browser of GitHub is being tested. So some files in years.hmtl are being linked directly into the repo. For example:

<UL TYPE=square>
<LI><A HREF="1984/anonymous/index.html">index.html</A> - <B>README</B>
<LI><A HREF="https://github.com/ioccc-src/temp-test-ioccc/blob/master/1984/anonymous/anonymous.c">anonymous.c</A>
<LI><A HREF="https://github.com/ioccc-src/temp-test-ioccc/blob/master/1984/anonymous/Makefile">Makefile</A>
<LI><A HREF="1984/anonymous/hint.txt">hint.txt</A> - <I>original README</I>
<LI><A HREF="https://github.com/ioccc-src/temp-test-ioccc/blob/master/1984/anonymous/orig.Makefile">orig.Makefile</A> - <I>original Makefile</I>
</UL>

This is done because a links such as:

<UL TYPE=square>
<LI><A HREF="1989/tromp/Makefile">Makefile</A>
<LI><A HREF="1989/tromp/tromp.hint">tromp.hint</A>
<LI><A HREF="1989/tromp/tromp.c">tromp.bsd.c</A>
<LI><A HREF="1989/tromp/tromp.orig.c">tromp.s5.c</A>
</UL>

cause most browsers to want to download the file instead of displaying them.

Yes the wanting to download issue is a very annoying one indeed.

Until a better solution is found, such as when a tool is developed to better format the web site, an link into the "https://github.com/ioccc-src/temp-test-ioccc/blob/master/..." should be used.

Would you please elaborate on this as well?

While suggestions are welcome using a tool to generate, say html files containing a Makefile, are out of WELL OUT OF SCOPE for this issue.

Would you please elaborate here too?

NOTE: There will be a tool that generates a web site from this repo. However such a tool will only be designed, let along coded, until after a number of issues (an especially this issue) have been resolved.

To help me help: what will this tool do exactly? Or have you not done any thinking on it yet? I just think it might help if we had an idea as it might help work on this issue.

Next to the winner directory name should be the award that they won. For example, instead of:

<A NAME="1985_applin"></A>
<P><B>applin</B></P>

one should have:

<A NAME="1985_applin"></A> - <I>Best one liner</I>
<P><B>applin</B></P>

Thank you.

I think that this issue will be the hardest actually and (as noted above) I think for some things it might be problematic. But hopefully my comments will help move things along here!

lcn2 commented 1 year ago

Ah .. you mean entry code filenames. Okay but what about entries with more than one source file ? That could be unwise to rename alternative files. It also incidentally would have to align with any documentation (man pages included or in the case of one of my entires a FILES file .. that entry actually has some formatting fixes I need to make in the remarks).

We may NOT want to do this: I.e., we may not want to rename source files.

Should the scope of this issue be modified to remove such C code file renaming (to prog.c?).

lcn2 commented 1 year ago

You're referring to for example the file: 2020/README.md, right?

Just want to be sure.

Yes.

Moreover want to turn per-winning entry stuff like hint.text into a README.md in markdown form.

Then a tool could be written to concert that markdown into HTML, and use data from the JSON manifest for the entry (see issue #4) to form an index.html people viewing the entry from a browser. However that index.html will happen MUCH LATER: after the primary issues are resolved. We are just explaining out think in the future, and why we want to fit rid of the existing html that was not part of the original winning entry.

UPDATE 0

The very top level html files that are part of the web site navigation must be kept and maintained (link wise).

Also any HTML files that are part of the original entry must be kept.

What we refer to mostly about eliminating are HTML files that we added by the judges, in some cases as duplicates of a hints file or judges remarks. The text should turn into a markdown file, say in the case of a wining entry, an README.md file.

lcn2 commented 1 year ago

Other files? How do you mean? Like how I have included extra files with information them in my entries ?

Yes.

lcn2 commented 1 year ago

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

Yes.

lcn2 commented 1 year ago

Please remind me what you mean by year.html..

At the very top directory they are two critical navigational HTML files years.html and winner.html. The links in those files need to be maintained by hand until issue #4 is resolved and we have a tool to automatically generate those links.

lcn2 commented 1 year ago

One idea that we might want to do is to separate the judges remarks from the authors remarks of a winning entry.

The README.md could be for the judges remarks. The winning author remarks, in markdown form (say that are currently at the bottom of most hint.text files for one example) could be put into a separate markdown file, say AUTHOR.README.md.

The judges README.md would have at the bottom (in "nice big friendly letters" as they say 😁) to see the authors remakes as a link to that AUTHOR.README.md file.

In cases where the authors of the wining entry have elaborate writes, say in HTML form, man pages, multiple file documentation: the AUTHOR.README.md file would still exist but be a guide to that other documentation.

The point would be to separate the judges remarks form the authors remarks, to have them as predictable markdown files (README.md and AUTHOR.README.md) and for complex winning entry write ups and complex entry documentation, have the predictable markdown files serve as a jumping off point to such complex / non-markdown documents.

We are open to a different name than AUTHOR.README.md, especially a shorter one.

lcn2 commented 1 year ago

When renaming a file in order to preserve the original file, HTML of the form "- original README" should be adde to the end of the line. I'm not sure I I understand this part either. Would you please clarify?

See what was done near the very bottom of this repo years.html file.

lcn2 commented 1 year ago

Would you please elaborate on this as well?

If you have force it to be a link to the page where GitHub renders the file, there will be no download.

Look as what the top level years.html is doing now for some files: it points to the GitHub page for that file so the user can see it as GitHub renders the file instead be being forced to download.

Not ideal, but good enough for now.

xexyl commented 1 year ago

Ah .. you mean entry code filenames. Okay but what about entries with more than one source file ? That could be unwise to rename alternative files. It also incidentally would have to align with any documentation (man pages included or in the case of one of my entires a FILES file .. that entry actually has some formatting fixes I need to make in the remarks).

We may NOT want to do this: I.e., we may not want to rename source files.

Should the scope of this issue be modified to remove such C code file renaming (to prog.c?).

I think it might be a good idea to remove that yes.

But what it should look like besides that I don't know. There is something to consider too: we can't verify with absolute certainty that there is no requirement that the filename stays the same. I mean it might be noted by the author but it might not and what if the name is enciphered (for example)?

The question is what should the fixed files be called. Should they be put in a subdirectory? That's not a suggestion but it popped into my head. I honestly don't know.

xexyl commented 1 year ago

You're referring to for example the file: 2020/README.md, right? Just want to be sure.

Yes.

Thanks.

Moreover want to turn per-winning entry stuff like hint.text into a README.md in markdown form.

That should be easy to do. But still I would like to have the right repo cloned before I start doing that. I did have a thought on that. What would happen if I delete my current fork and then clone this one? I wonder if it would let me fork this repo and not the main one. I'll try that in a bit or if not a bit then tomorrow.

Then a tool could be written to concert that markdown into HTML, and use data from the JSON manifest for the entry (see issue #4) to form an index.html people viewing the entry from a browser. However that index.html will happen MUCH LATER: after the primary issues are resolved. We are just explaining out think in the future, and why we want to fit rid of the existing html that was not part of the original winning entry.

Not something like rdiscount instead? Or is the idea that it does the transformation and the other stuff too?

UPDATE 0

The very top level html files that are part of the web site navigation must be kept and maintained (link wise).

Also any HTML files that are part of the original entry must be kept.

Of course. Which is what I was getting at yesterday with not renaming files. But html files too of course. That was immediately obvious to me because Snake and Enigma both have html files that are not the remarks.

What we refer to mostly about eliminating are HTML files that we added by the judges, in some cases as duplicates of a hints file or judges remarks. The text should turn into a markdown file, say in the case of a wining entry, an README.md file.

Right. In other words the only html file that should be removed is that which corresponds to the hint/markdown file, right?

xexyl commented 1 year ago

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

Yes.

Well as I think I noted that should be easy (of course). Just a matter of many git mv invocations and a commit. But still there's the issue of the wrong repo being forked. I will try that idea I had but I fear it will just fork the winner.git and not this one. It would be nice if it wouldn't though because then I could start working on these issues.

xexyl commented 1 year ago

Please remind me what you mean by year.html..

At the very top directory they are two critical navigational HTML files years.html and winner.html. The links in those files need to be maintained by hand until issue #4 is resolved and we have a tool to automatically generate those links.

Oh those. Yes. I don't want to touch those. Thanks for clarifying.

xexyl commented 1 year ago

One idea that we might want to do is to separate the judges remarks from the authors remarks of a winning entry.

The README.md could be for the judges remarks. The winning author remarks, in markdown form (say that are currently at the bottom of most hint.text files for one example) could be put into a separate markdown file, say AUTHOR.README.md.

The judges README.md would have at the bottom (in "nice big friendly letters" as they say 😁) to see the authors remakes as a link to that AUTHOR.README.md file.

In cases where the authors of the wining entry have elaborate writes, say in HTML form, man pages, multiple file documentation: the AUTHOR.README.md file would still exist but be a guide to that other documentation.

The point would be to separate the judges remarks form the authors remarks, to have them as predictable markdown files (README.md and AUTHOR.README.md) and for complex winning entry write ups and complex entry documentation, have the predictable markdown files serve as a jumping off point to such complex / non-markdown documents.

We are open to a different name than AUTHOR.README.md, especially a shorter one.

There's one downside to this one: unless the tool will merge them it would mean that the author's comments would not be right under the judges' comments and I (at least) like how it looks.

Are you suggesting that they should be in different files? I think there's another downside to that: namely it means that viewers will have to go to another file instead of just scrolling down a bit. This is probably a problem with using a web browser and probably more annoying when using a text editor (obviously vim! :-) ).

Not that these things can't be done but it seems to me like it would be good to keep them together.

Or are you saying something else maybe?

xexyl commented 1 year ago

When renaming a file in order to preserve the original file, HTML of the form "- original README" should be adde to the end of the line. I'm not sure I I understand this part either. Would you please clarify?

See what was done near the very bottom of this repo years.html file.

Do you mean:

(all years) (ALL) Master README Top level Makefile A summary of the winners all.tar.bz2 - all of the data (16.3 MiB)

and the fact there aren't any spoilers ? If not what do you mean? If yes I'll have to look back to find the context as I certainly don't know now.

xexyl commented 1 year ago

Would you please elaborate on this as well?

If you have force it to be a link to the page where GitHub renders the file, there will be no download.

Look as what the top level years.html is doing now for some files: it points to the GitHub page for that file so the user can see it as GitHub renders the file instead be being forced to download.

Not ideal, but good enough for now.

Thanks. Do you have an example file I can take a look at ? (It sounds like it's not all files so might be easier to just have an example file name to check.)

lcn2 commented 1 year ago

Thanks. Do you have an example file I can take a look at ? (It sounds like it's not all files so might be easier to just have an example file name to check.)

Any file that is part of entry in the directory should be listed in the entry's set of URLs in the top level years.html page.

This is why if you add, rename or delete files in a direct entry, the corresponding side of your ells on the years.html page needs to be updated as well.

Once issue #4 is resolved, each directory entry will have a JSON file that contains a manifest. When we have all those manifests, the next tool can be written (we anticipate it being written in a language such as Perl or ac) to generate the years.html file automatically. Until we have those Jason files, we will have to manually maintain the years.html file.

As far as what should be in the manifest, at this point, everything in the directory should be listed now. And the corresponding entries in the years.html page need to be updated accordingly.

lcn2 commented 1 year ago

One thing we could do now, is to generate an initial JSON file for all of the existing winning entries as they are now. Here we are talking about the Jason files for each winning directories only (not the author information).

Do you want us to do that?

lcn2 commented 1 year ago

Moved comment form issue #2

One thing we might want to do to help with this issue is to go through our records and be sure that every file that's been modified has an original copy somewhere.

lcn2 commented 1 year ago

Moved comment from issue #2

One idea is to build a set of year level directories that contain the original copies of all entries. So there would be a 1984 directory tree and a orig.1984 tree.

BTW: The orig.1984 tree would not be a part of the repo (instead there would be an orig.1984.txz file that would be part of the repo). See UPDATE 0b below.

Instead of trying to keep a mix of original and modified files in the same winning directories, we could simply have a parallel tree containing the originals.

Now there are a few minor decisions that we need to be made if we go down this path, but those are refinements of the idea, not complications nor problems with it.

UPDATE 0b

We could just simply declare the existing tarballs for each year as containing the original files. So instead of having an orig.1984 tree, we would simply provide a orig.1984.txz file that would untar into a orig.1984 directory. If we did this, we wouldn't need to worry about maintaining navigational links into such directories. Here's a record would be preserved, just not in a super convenient web friendly form.

The orig.YYYY.txz file would reside as a file under the YYYY directory. It would untar as orig.YYYY. We could put orig.YYYY under a .gitignore file so that we could easily have the tree untar-ed your reference purposes for ourselves and not impact the web site nor GitHub repo.

The orig.YYYY.txz file would be part of the GitHub repo and be linked to in the years.html near the top of the given year. But then we would remove links to other "orig" files links from years.html.

The existing "orig" files could be deleted, for the most part, since there would be a copy somewhere in the orig.YYYY.txz file.

One minor point, for a few entires the so-called ALT build isn't an original source, it is a 2nd copy provided by the author. For example, some winners provided an unobstructed version of their code and some winners provided an obfuscated copy with additional functionality that was over the size limit (so they provided it as an auxiliary file). In these cases the "orig" file isn't an original but rather an alternative copy.

What do you think of that, @xexyl ?

UPDATE 1

If we did, according to UPDATE 0b above, we would no longer need to maintain original copies in the winning directories, and we would no longer need to try to have Makefile rules that tries to compile (and often fails) such original code.

Now there may be a few minor decisions. We have to make if we wait along this route.

What do you think?

UPDATE 2

This proposal has implications for issue #1 and issue #2. To some extent the JSON manifests mentioned in issue #4 are also touched.

This is because these for issues are recently interconnected.

So we need to make some early decisions about this now as this will likely impact the other issues going forward.

xexyl commented 1 year ago

I was hoping that I could address that but as you might imagine it is kind of difficult on the phone.

I will read it but depending on what kind of reply might be needed I might have to wait until tomorrow.

It might also be that I am just too tired to parse it too.

It seems to me though that you have some good ideas here.

I will either reply tomorrow or else in a bit.

xexyl commented 1 year ago

Moved comment form issue #2

One thing we might want to do to help with this issue is to go through our records and be sure that every file that's been modified has an original copy somewhere.

Is that necessary with git?

Or what is the purpose of this that you’re talking of?

xexyl commented 1 year ago

Moved comment from issue #2

One idea is to build a set of year level directories that contain the original copies of all entries. So there would be a 1984 directory tree and a orig.1984 tree.

BTW: The orig.1984 tree would not be a part of the repo (instead there would be an orig.1984.txz file that would be part of the repo). See UPDATE 0b below.

Instead of trying to keep a mix of original and modified files in the same winning directories, we could simply have a parallel tree containing the originals.

Now there are a few minor decisions that we need to be made if we go down this path, but those are refinements of the idea, not complications nor problems with it.

UPDATE 0b

We could just simply declare the existing tarballs for each year as containing the original files. So instead of having an orig.1984 tree, we would simply provide a orig.1984.txz file that would untar into a orig.1984 directory. If we did this, we wouldn't need to worry about maintaining navigational links into such directories. Here's a record would be preserved, just not in a super convenient web friendly form.

The orig.YYYY.txz file would reside as a file under the YYYY directory. It would untar as orig.YYYY. We could put orig.YYYY under a .gitignore file so that we could easily have the tree untar-ed your reference purposes for ourselves and not impact the web site nor GitHub repo.

The orig.YYYY.txz file would be part of the GitHub repo and be linked to in the years.html near the top of the given year. But then we would remove links to other "orig" files links from years.html.

The existing "orig" files could be deleted, for the most part, since there would be a copy somewhere in the orig.YYYY.txz file.

One minor point, for a few entires the so-called ALT build isn't an original source, it is a 2nd copy provided by the author. For example, some winners provided an unobstructed version of their code and some winners provided an obfuscated copy with additional functionality that was over the size limit (so they provided it as an auxiliary file). In these cases the "orig" file isn't an original but rather an alternative copy.

What do you think of that, @xexyl ?

UPDATE 1

If we did, according to UPDATE 0b above, we would no longer need to maintain original copies in the winning directories, and we would no longer need to try to have Makefile rules that tries to compile (and often fails) such original code.

Now there may be a few minor decisions. We have to make if we wait along this route.

What do you think?

UPDATE 2

This proposal has implications for issue #1 and issue #2. To some extent the JSON manifests mentioned in issue #4 are also touched.

This is because these for issues are recently interconnected.

So we need to make some early decisions about this now as this will likely impact the other issues going forward.

Having directories for modified versions sounds like a great idea.

I don’t think I will be able to reply in more detail about any thoughts and or concerns about this at the phone though so I will delay it until the morning.

I do think that what you have proposed might very well work though.

More from me on this tomorrow morning!

xexyl commented 1 year ago

Oh and as far as alt versions: I think my Snake entry has am alt version. It certainly has a number of versions but I think one of them is alt.

Anyway I will reply properly tomorrow.

I hope you have a great night!

lcn2 commented 1 year ago

Oh and as far as alt versions: I think my Snake entry has am alt version. It certainly has a number of versions but I think one of them is alt.

Anyway I will reply properly tomorrow.

I hope you have a great night!

Yes, so you understand that not every "orig" can be moved/removed. Someone has to go thru each winning entry and make a decision.

lcn2 commented 1 year ago

Moved comment form issue #2

One thing we might want to do to help with this issue is to go through our records and be sure that every file that's been modified has an original copy somewhere.

Is that necessary with git?

Or what is the purpose of this that you’re talking of?

We are proposing that if we build those alternate tarballs, then we could work on the contents of those tarballs to make sure that files are actually original.

But that might be more work than it's worth so we might simply declare that the existing downloadable compressed tarballs that are available on the website now are the originals and leave it at that.

lcn2 commented 1 year ago

When renaming a file in order to preserve the original file, HTML of the form "- original README" should be adde to the end of the line.

I'm not sure I I understand this part either. Would you please clarify?

See what was done near the very bottom of this repo years.html file.

Do you mean:

(all years) (ALL)

Master README

Top level Makefile

A summary of the winners

all.tar.bz2 - all of the data (16.3 MiB)

and the fact there aren't any spoilers ? If not what do you mean? If yes I'll have to look back to find the context as I certainly don't know now.

We mean near the bottom of the years.html file of this repo. Look for the stuff like "- README" and "- download all of 1984".

Of course, if we planning to move the originals into tarballs, some of those lines can go away.

lcn2 commented 1 year ago

One idea that we might want to do is to separate the judges remarks from the authors remarks of a winning entry.

The README.md could be for the judges remarks. The winning author remarks, in markdown form (say that are currently at the bottom of most hint.text files for one example) could be put into a separate markdown file, say AUTHOR.README.md.

The judges README.md would have at the bottom (in "nice big friendly letters" as they say 😁) to see the authors remakes as a link to that AUTHOR.README.md file.

In cases where the authors of the wining entry have elaborate writes, say in HTML form, man pages, multiple file documentation: the AUTHOR.README.md file would still exist but be a guide to that other documentation.

The point would be to separate the judges remarks form the authors remarks, to have them as predictable markdown files (README.md and AUTHOR.README.md) and for complex winning entry write ups and complex entry documentation, have the predictable markdown files serve as a jumping off point to such complex / non-markdown documents.

We are open to a different name than AUTHOR.README.md, especially a shorter one.

There's one downside to this one: unless the tool will merge them it would mean that the author's comments would not be right under the judges' comments and I (at least) like how it looks.

Are you suggesting that they should be in different files? I think there's another downside to that: namely it means that viewers will have to go to another file instead of just scrolling down a bit. This is probably a problem with using a web browser and probably more annoying when using a text editor (obviously vim! :-) ).

Not that these things can't be done but it seems to me like it would be good to keep them together.

Or are you saying something else maybe?

We thing that probably the idea of splitting them into do different files might be more trouble than value.

If we went with just a single README.md then all that would be needed is to put a line such as:

Selected authors remarks follow

Kind of like we do in most cases.

Do you think the single README.md file is better?

lcn2 commented 1 year ago

Please remind me what you mean by year.html..

At the very top directory they are two critical navigational HTML files years.html and winner.html. The links in those files need to be maintained by hand until issue #4 is resolved and we have a tool to automatically generate those links.

Oh those. Yes. I don't want to touch those. Thanks for clarifying.

When you rename files, or remove files, or creat new files as part of your work, these files WILL need to be updated.

While we get that this is not convenient or nice to do, for now those HTML files are the navigation within the web site.

There is an alternative process, and that would be to create and maintain the JSON files in each directory as mentioned in issue #4. Then instead of editing, say, years.html you would instead edit the "JSON file in the directory" that contained the manifest. And by "JSON file in the directory" we refer to the ".award.json per winner directory" mentioned at the top of issue #4.

lcn2 commented 1 year ago

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

Yes.

Well as I think I noted that should be easy (of course). Just a matter of many git mv invocations and a commit. But still there's the issue of the wrong repo being forked. I will try that idea I had but I fear it will just fork the winner.git and not this one. It would be nice if it wouldn't though because then I could start working on these issues.

We need to be issuing pull requests against the temp-test-ioccc repo and not the winner repo.

lcn2 commented 1 year ago

Not something like rdiscount instead? Or is the idea that it does the transformation and the other stuff too?

The tools to do this are TBD, but in general, things like rdiscount run within some sort of wrapper tool.

lcn2 commented 1 year ago

Right. In other words the only html file that should be removed is that which corresponds to the hint/markdown file, right?

Correct.

xexyl commented 1 year ago

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

Yes.

Well as I think I noted that should be easy (of course). Just a matter of many git mv invocations and a commit. But still there's the issue of the wrong repo being forked. I will try that idea I had but I fear it will just fork the winner.git and not this one. It would be nice if it wouldn't though because then I could start working on these issues.

We need to be issuing pull requests against the temp-test-ioccc repo and not the winner repo.

Agreed but Github is being a git about forking.

I can try deleting my fork and see if it will let me but it doesn’t look like it will work.

Something has to change but if this doesn’t work it’s not something that I can do. I will let you know but I fear that something will have to be done at your end.

I will try it in the morning.

But now I am going to bed.

Good night! I will reply to everything in the morning.

lcn2 commented 1 year ago

The Scope of this issue has been modified.

We removed the "source code filenames" requirement.

UPDATE 0

We also converted the checkbox list into like a - list.

lcn2 commented 1 year ago

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.

xexyl commented 1 year ago

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.

I will address the comments in a bit .. have some things at the laptop I need to address first. I will also, I think, open an issue like the OT one in the other repo to help clear things up. One example will be the issue of GitHub and the forking of this repo. Another one that might have been useful is the DNSSEC stuff (that's actually one thing I want to do before I address the comments .. make absolute certain it's working as expected).

UPDATE 0

Sorry for the delay ... I ran into an issue and then - well never mind. All good now. I'll work on the comments though I'm not sure if I'l get to all of them in one sitting. I'm sure I won't.

xexyl commented 1 year ago

As far as the hint.text and hint.txt and hint.html files see the open pull request.

I'm not sure if something else needs to be done with that one.

The reason I'm still here is because I have a cat between my legs so obviously I can't get him up!

IMG_8900

I will see if I can reply to the other comments now. That's not a guarantee of course but it's something I'm thinking that if I have the energy to do I will do so. In a while I'll have to get up, cat or no, but for now I'm fine sitting up in bed.

xexyl commented 1 year ago

Thanks. Do you have an example file I can take a look at ? (It sounds like it's not all files so might be easier to just have an example file name to check.)

Any file that is part of entry in the directory should be listed in the entry's set of URLs in the top level years.html page.

Plus the MANIFEST and any other files in entries and years.

This is why if you add, rename or delete files in a direct entry, the corresponding side of your ells on the years.html page needs to be updated as well.

I did this for the README.md files for example.

Once issue #4 is resolved, each directory entry will have a JSON file that contains a manifest. When we have all those manifests, the next tool can be written (we anticipate it being written in a language such as Perl or ac) to generate the years.html file automatically. Until we have those Jason files, we will have to manually maintain the years.html file.

I did this but if something went wrong please let me know .. I am quite tired as I said! I think it's good though as it was just a matter of changing a couple filenames to README.md.

As far as what should be in the manifest, at this point, everything in the directory should be listed now. And the corresponding entries in the years.html page need to be updated accordingly.

By MANIFEST you mean for instance 2020/MANIFEST ?

I noticed that very few years have one. Do the others need one? I guess so. What about the root directory - does it need one with all the files from over the years (and maybe other files)?

xexyl commented 1 year ago

Essentially what you're saying is: hint.text and hint.markdown should be renamed to README.md, right?

Yes.

Well as I think I noted that should be easy (of course). Just a matter of many git mv invocations and a commit. But still there's the issue of the wrong repo being forked. I will try that idea I had but I fear it will just fork the winner.git and not this one. It would be nice if it wouldn't though because then I could start working on these issues.

We need to be issuing pull requests against the temp-test-ioccc repo and not the winner repo.

Fortunately this was resolved! .. though I feel like I might have already replied to it saying that (and I did elsewhere too) ...

xexyl commented 1 year ago

Not something like rdiscount instead? Or is the idea that it does the transformation and the other stuff too?

The tools to do this are TBD, but in general, things like rdiscount run within some sort of wrapper tool.

Do you mean that it is built that way or rather that another tool would be a wrapper to it ? Just curious on a technical level as I never looked at the source of rdiscount.

xexyl commented 1 year ago

Right. In other words the only html file that should be removed is that which corresponds to the hint/markdown file, right?

Correct.

See 77fb0f11a2ddc8584a1ebe8d68fb0cccf3b959a6, 851e191519953c743cdd363dc19099e89210319c and 5850cf96056f4281aa6849988801b48e7b1360df please.

xexyl commented 1 year ago

Only one copy should be kept (a quick check should be made to verify that to apparent duplicate files are in fast, duplicates). When it doubt, keep the text of markdown copy. If needed, marge the content into a single file if the copies have substantial differences.

I actually forgot to do the check but given how many html files were removed I'm not sure how I could have gone about this. Do you want me to try it though? If so please check the one I mentioned before - the one by Korn - so that one day I can actually see if I can figure it out!

xexyl commented 1 year ago

Right. In other words the only html file that should be removed is that which corresponds to the hint/markdown file, right?

Correct.

See 77fb0f1, 851e191 and 5850cf9 please.

I just noticed that there are some hint files that were not named 'hint.text' but rather by the author. I will have to think of a way to find the remaining files.

In the meantime the ${ECHO} has been updated to be just echo in commit 046692c03e01670df0c0ce9c70d7e7be4a36edf8. I did NOT do it in hint files which is important as it would break things. For instance the script in 1998/dlowe/dlowe.hint.

Now that does bring up a point. Can you think of a way to test all Makefiles ? Problem is that not all entries will compile so it might be difficult. Perhaps using sed there is no need to do this - yet - but it might be something we need to do later and probably for each major change.

xexyl commented 1 year ago

Right. In other words the only html file that should be removed is that which corresponds to the hint/markdown file, right?

Correct.

See 77fb0f1, 851e191 and 5850cf9 please.

I just noticed that there are some hint files that were not named 'hint.text' but rather by the author. I will have to think of a way to find the remaining files.

Commit 17ea7fbd9e165b8c33874f367ec7d508b3711d7d takes care of this except for one file:

$ find . -name '*.hint' -execdir git mv '{}' README.md \;
fatal: destination exists, source=1992/albert/albert.hint, destination=1992/albert/README.md

and unfortunately the files differ quite a bit so I'm not sure what to do.

UPDATE 0

The README.md was only an email from Leo to you, before he was a judge (presumably :-) ), about a bug. This meant that the index file did not have information about the entry. Thus I renamed the README.md so that the hint file could become README.md. The old contents were renamed to albert.bug.md but a better name might be contrived. I leave that to you though I'm happy to provide thoughts on it.

xexyl commented 1 year ago

Re-replying to this as you changed it I believe enough to warrant this.

Makefiles

We need to try and make Makefiles reasonably consistent in type and layout.

Pay attention to Makefile variable consistency use. Pay attention to use of whitespace, especially in comments.

I'll do these later on.

The use of the Makefile variable, ${ECHO} should be replaced with just echo and the ECHO= Makefile variable should be removed.

As noted this is done but only in Makefiles.

judges remarks / winner writeup / winner's remarks

The filenames containing " judges remarks / winner writeup / winner's remarks filenames" is all over the map. A common filename should be used, such as README.md.

As noted this is also done but see below.

Wore still, in some cases there are multiple copies in different formats such as text and html. There should be ONLY one copy of the file, and that should be in Markdown format. For example in 2018/mills we have both hint.html and hint.text. In this case the one file is a copy of the other file. Only one copy should be kept (a quick check should be made to verify that to apparent duplicate files are in fast, duplicates). When it doubt, keep the text of markdown copy. If needed, marge the content into a single file if the copies have substantial differences.

Like I said I did not check for differences except for when one file had a change to README.md already from the earlier commit. But the thing is with that one is it appears that one file is not the correct file. That's not worded so well so let me just show what I mean. As I noted in the updated above comment.

NOTE: Later on, such markdown files will be rendered into html by a site building process. So the html copy should NOT be kept.

Removed them - at least the obvious ones. The extra html files were of course not removed. A question is which html files besides the hint.html can be removed though? I just had the thought that just because there's an author.html file does not mean that it is supposed to be the html of the markdown.

What do you think should be done if any of these exist?

In cases where the " judges remarks / winner writeup / winner's remarks filenames" is just hint.text or winner_name.hint, it should be converted into a markdown format file README.md.

Well I believe those already are meant to be markdown so is there anything that needs to be done there? After all define markdown: it can be just text too. Also what formatting? I guess one could look at others but which are correct?

The content of having a "hint" file is going away. So hint.txt files, for example, need to become README.md. Such files should not be treated as spoiler files, but other files a user is encouraged to read.

Done though I wonder what you mean by not a spoiler. It seems in some cases they are but then it's just like before - the reader is typically warned - so it's probably fine.

filename extensions

The use of .text extension should be replaced with .txt where reasonable. Be careful when the file is some sort of "data file" where the .text extension may be required.

Besides README files and hint.text the only other ones were in my entries .. fixed with commit 19d5c3a84827779826e86b1062d2ad407d8b2914 though I do not know how the html generation will go so I don't know if everything is okay with it!

The use of .makrdown extension should be replaced with .md where reasonable. Be careful when the file is some sort of "data file" where the .markdown extension may be required.

I believe I did this were reasonable. The only exception is that 2020/ferguson1 has a number of markdown files that have corresponding .md files as well. I have to check the differences but that will happen another time.

I must go for now but I will reply to the rest of the updated comment later. Not sure how long that will be .. have a number of things I must do this morning.

xexyl commented 1 year ago

I remembered I had other comments to reply to first so I'll do that before I reply to the rest of the updated issue.

Oh and as far as alt versions: I think my Snake entry has am alt version. It certainly has a number of versions but I think one of them is alt. Anyway I will reply properly tomorrow. I hope you have a great night!

Yes, so you understand that not every "orig" can be moved/removed. Someone has to go thru each winning entry and make a decision.

That makes sense yes. I think getting rid of such files would be risky anyway. Don't you agree?

xexyl commented 1 year ago

When renaming a file in order to preserve the original file, HTML of the form "- original README" should be adde to the end of the line.

I'm not sure I I understand this part either. Would you please clarify?

See what was done near the very bottom of this repo years.html file.

Do you mean:

(all years) (ALL)

Master README Top level Makefile A summary of the winners all.tar.bz2 - all of the data (16.3 MiB) and the fact there aren't any spoilers ? If not what do you mean? If yes I'll have to look back to find the context as I certainly don't know now.

We mean near the bottom of the years.html file of this repo. Look for the stuff like "- README" and "- download all of 1984".

Ah .. at the top of each year. Though as for 'download all of' that wording is inconsistent. Want me to change them? If so what do you prefer it say? But maybe the years file shouldn't be modified until a way to use a markdown file exists ?

Of course, if we planning to move the originals into tarballs, some of those lines can go away.

Of course.

xexyl commented 1 year ago

We thing that probably the idea of splitting them into do different files might be more trouble than value.

If we went with just a single README.md then all that would be needed is to put a line such as:

Selected authors remarks follow

Kind of like we do in most cases.

Do you think the single README.md file is better?

I do indeed think a single file is better. It keeps it together which I think is important. It's also easier to maintain and navigate (latter for the viewers mostly but sometimes the winners I'd imagine).

xexyl commented 1 year ago

Please remind me what you mean by year.html..

At the very top directory they are two critical navigational HTML files years.html and winner.html. The links in those files need to be maintained by hand until issue #4 is resolved and we have a tool to automatically generate those links.

Oh those. Yes. I don't want to touch those. Thanks for clarifying.

When you rename files, or remove files, or creat new files as part of your work, these files WILL need to be updated.

What files? The renamed / moved / new files? And in what way updated? I guess it depends on the type of file so maybe you have an example so I can figure out what you are getting at?

While we get that this is not convenient or nice to do, for now those HTML files are the navigation within the web site.

True.

There is an alternative process, and that would be to create and maintain the JSON files in each directory as mentioned in issue #4. Then instead of editing, say, years.html you would instead edit the "JSON file in the directory" that contained the manifest. And by "JSON file in the directory" we refer to the ".award.json per winner directory" mentioned at the top of issue #4.

How would this change the updating / renaming / etc. the html (and other) files ?

xexyl commented 1 year ago

Moved comment form issue #2

One thing we might want to do to help with this issue is to go through our records and be sure that every file that's been modified has an original copy somewhere.

Is that necessary with git? Or what is the purpose of this that you’re talking of?

We are proposing that if we build those alternate tarballs, then we could work on the contents of those tarballs to make sure that files are actually original.

But that might be more work than it's worth so we might simply declare that the existing downloadable compressed tarballs that are available on the website now are the originals and leave it at that.

As long as they're original I'd agree there.