From b20d6370d0d1107e63f014446519e48f688d89f7 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Sat, 29 Jun 2024 01:09:10 -0700 Subject: [PATCH] improve markdown conformance to IOCCC best practices --- CHANGES.md | 14 +++---- CODE_OF_CONDUCT.md | 11 ++++++ FAQ.md | 99 ++++++++++++++++++++++++++++++---------------- README.md | 24 ++++++----- remarks.example.md | 2 +- 5 files changed, 94 insertions(+), 56 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index dba941fb9..b6e0d7342 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -440,7 +440,7 @@ which stores the _found_ location. This is useful for `-v 1` as one can then see something like: -```sh +``` ./location -a -s -N -v 1 'united' United Arab Emirates ==> AE United Kingdom of Great Britain and Northern Ireland (the) ==> GB @@ -454,7 +454,7 @@ United States of America ==> US Without the `-v 1` it will only show: -```sh +``` $ ./location -a -s -n 'united' AE GB @@ -477,7 +477,7 @@ find their country code, if they do not know what it is (or they want say anonymous and don't know that it's `XX`). Search is done case-insensitively. Another example use: -```sh +``` $ ./location -asnv 1 germ German Democratic Republic ==> DD Germany ==> DE @@ -624,14 +624,14 @@ like what was done yesterday for `jval`. Fixed bug where one could not do: -```sh +``` echo '"test"' | ./jfmt - ``` and the same thing with `jval` and `jnamval`. This also fixes the bug where one could not do: -```sh +``` ./jfmt - "test" ^D @@ -2613,7 +2613,7 @@ The JSON parser is code complete! The following JSON parses now work: -```sh +``` ./jparse -J 3 -s '{ "curds" : "whey", "foo" : 23209 }' ./jparse -J 3 test_JSON/info.json/good/info.good.json ./jparse -J 3 test_JSON/author.json/good/author.default.json @@ -2702,7 +2702,7 @@ Added `-T` flag to `mkiocccentry`, `fnamchk`, `txzchk`, `jstrencode` and `jstrdecode` to print the IOCCC entry tool set release tag: -```sh +``` ./mkiocccentry -T ./fnamchk -T ./txzchk -T diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 96ccffe89..d0acffe75 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,5 +1,6 @@ # Contributor Covenant Code of Conduct + ## Our Pledge We as members, contributors, and leaders pledge to make participation in our @@ -12,6 +13,7 @@ and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + ## Our Standards Examples of behavior that contributes to a positive environment for our @@ -36,6 +38,7 @@ Examples of unacceptable behavior include: * Other conduct which could reasonably be considered inappropriate in a professional setting + ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of @@ -48,6 +51,7 @@ comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + ## Scope This Code of Conduct applies within all community spaces, and also applies when @@ -56,6 +60,7 @@ Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be @@ -66,11 +71,13 @@ All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. + ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed @@ -80,6 +87,7 @@ unprofessional or unwelcome in the community. clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + ### 2. Warning **Community Impact**: A violation through a single incident or series @@ -92,6 +100,7 @@ includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including @@ -103,6 +112,7 @@ private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community @@ -112,6 +122,7 @@ individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. + ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], diff --git a/FAQ.md b/FAQ.md index 96ec8fab3..1b70d49f3 100644 --- a/FAQ.md +++ b/FAQ.md @@ -30,7 +30,9 @@ 12. Why do these tools sometimes use the incorrect IOCCC terms? -## 0. Where can I find the mkiocccentry tool? +
+## 0. Where can I find the mkiocccentry tool? +
The `mkiocccentry` tool source code is found in the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). @@ -38,8 +40,8 @@ If you have not already done so, you may download the source by using `git clone`: -```sh -git clone git@github.com:ioccc-src/mkiocccentry.git +``` +git clone https://github.com/ioccc-src/mkiocccentry.git ``` If you don't have `git` you may @@ -47,18 +49,20 @@ If you don't have `git` you may and then extract that file. -## 1. How do I compile the mkiocccentry tool? +
+## 1. How do I compile the mkiocccentry tool? +
After downloading the repo (making sure that if you downloaded the zip file that you unzip it first) move into the _mkiocccentry_ directory: -```sh +``` cd mkiocccentry ``` and compile everything from scratch: -```sh +``` make clobber all ``` @@ -67,8 +71,9 @@ local directory. If something went wrong, see how do I report bugs or other issues? - -## 2. How do I package my submission? +
+## 2. How do I package my submission? +
We recommend that you use the `mkiocccentry` tool to package your submission. If you have not already done so, download the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry) @@ -78,7 +83,7 @@ and compile it From the top level directory, run the `mkiocccentry` executable: -```sh +``` ./mkiocccentry work_dir prog.c Makefile remarks.md [file ...] ``` @@ -89,7 +94,7 @@ the submit slot number. Something like _/tmp/ioccc_ is a good choice: -```sh +``` mkdir -p /tmp/ioccc ``` @@ -110,19 +115,19 @@ Once you have answered all of the questions, the tool will form a XZ compressed tarball, in v7 format, under the _work_dir_ directory. -## 3. What do I do for the Makefile in my submission? +
+#<# 3. What do I do for the Makefile in my submission? +
Although you are welcome to add additional rules, we recommend that you use the example Makefile, [Makefile.example](Makefile.example), removing and changing comments as appropriate, and making sure to add the correct specifics of each rule. -XXX - make sure to link to the winner repo FAQ about the Makefile - XXX -XXX - this is not done now because of link changes and possibly an anchor - XXX -XXX - name being added to this FAQ item - XXX - -## 4. Can't I just submit my obfuscated C program to the judges? +
+## 4. Can't I just submit my obfuscated C program to the judges? +
No. While we appreciate your enthusiasm for wanting to show us your obfuscated code, the [IOCCC judges](https://www.ioccc.org/judges.html) request your help by @@ -138,7 +143,9 @@ In short, you cannot simply upload your obfuscated C program as it needs to be in a certain form and the `mkiocccentry` tool does that. -## 5. Do I have to use mkiocccentry to package my submission? +
+## 5. Do I have to use mkiocccentry to package my submission? +
Technically you do not have to use the `mkiocccentry` tool; however, you run the risk of having your submission rejected if what you upload to the submit server is @@ -154,7 +161,10 @@ inspect the directory that you used to form the tarball to verify that the contents under that directory are also OK. In particular, that tool tests that the JSON files are correct. -## 6. Do I need to install this code to use it? + +
+## 6. Do I need to install this code to use it? +
No, installing the code in this repo is not necessary to use it. These tools were designed to be used from the top level directory of the source, or after @@ -168,11 +178,14 @@ put _./_ before the name of a command. For example: -```shell +``` ./mkiocccentry -h ``` -## 7. How can I learn more about how to use the tools? + +
+## 7. How can I learn more about how to use the tools? +
Assuming you have downloaded and compiled the code you can get a quick reminder of command @@ -180,7 +193,7 @@ options and arguments by use of the `-h` option of any tool: For instance: -```shell +``` ./mkiocccentry -h ./iocccsize -h ./chkentry -h @@ -196,7 +209,7 @@ directory at the top of the source directory. For example: -```shell +``` man man/man1/mkiocccentry.1 man man/man1/iocccsize.1 man man/man1/chkentry.1 @@ -211,12 +224,14 @@ Luke!"_ as you may find the code in this repo reasonably un-obfuscated and fairl well commented. -## 8. How do I report bugs or other issues? +
+## 8. How do I report bugs or other issues? +
Please run the following from the main directory: -```sh +``` make bug_report ``` @@ -227,7 +242,7 @@ making sure to attach the bug report file. You may also run the `bug_report.sh` tool directly: -```sh +``` ./bug_report.sh -v 1 ``` @@ -252,7 +267,9 @@ The script that the make rule runs, `bug_report.sh`, will tell you the name of the file to upload. -## 9. How can I help test this repo? +
+## 9. How can I help test this repo? +
Thank you for any and all help! @@ -261,7 +278,9 @@ Please see the for more details on what you can do to help us. -## 10. What can I do if my system's tar(1) does not support the correct options? +
+## 10. What can I do if my system's tar(1) does not support the correct options? +
If your tar does not support the `-J` option you can either use a system @@ -274,17 +293,27 @@ Some systems have a `GNU tar` that you can use. For instance FreeBSD has a specify in the tools the `-t tar` option to make this work. -## 11. Where can I find help with formatting markdown files for my submission? +
+## 11. Where can I find help with formatting markdown files for my submission? +
+ +The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/). + +Please see [Official IOCCC FAQ FAQ 0.6](https://www.ioccc.org/faq.html#markdown) + +**IMPORTANT**: Please read the [IOCCC markdown best practices](markdown.html) guide +as it lists things you **should not use** in markdown files. -Please see this simple -[markdown guide](https://www.markdownguide.org/basic-syntax) for more help. +See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide. +See also [CommonMark Spec](https://spec.commonmark.org/current/). -## 12. Why do these tools sometimes use incorrect IOCCC terms? +
+## 12. Why do these tools sometimes use incorrect IOCCC terms? +
-According to the [Official IOCCC FAQ -6.9](https://www.ioccc.org/faq.html#terms) this repo sometimes uses -the wrong term. For example the name `mkiocccentry(1)` contains +According to the [Official IOCCC FAQ 6.9](https://www.ioccc.org/faq.html#terms) +this repo sometimes uses the wrong term. For example the name `mkiocccentry(1)` contains the name _entry_ when the tool is dealing with a _submission_. So why don't we call the tool _mkiocccsubmission_ and rename the this repo? @@ -311,4 +340,4 @@ it's correct, a pull request that corrects the mistake or mistakes. Note, however, that there are many cases where the words _entry_ and/or _entries_ are actually correct: they would only be incorrect if they refer to an IOCCC submission that has not won. In other words if it refers to submissions -won then it should be _entry_ or _entries_. \ No newline at end of file +won then it should be _entry_ or _entries_. diff --git a/README.md b/README.md index c9c84cc93..1fe73cb54 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Official IOCCC submission toolkit -*NOTE*: This code is currently under alpha-test. - *NOTE*: you may wish to also read our [FAQ](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md). @@ -16,12 +14,13 @@ under different platforms. In order to help you help us, we provide the following information. + ### Running the test suite Perhaps the most important thing you can do for us is run the `bug_report.sh` script with all information like: -```sh +``` make bug_report ``` @@ -36,7 +35,7 @@ do so. If the script does not report any issues you may delete the file safely (it will tell you the log file name). Alternatively you can run: -```sh +``` ./bug_report -x ``` @@ -88,7 +87,7 @@ Form an **IOCCC** submission as an XZ compressed tarball file. For examples and more information, try: -```sh +``` man ./soup/man/man1/mkiocccentry.1 ``` @@ -103,7 +102,7 @@ This code is based on code by *@SirWumpus* (**Anthony Howe**): For more information and examples, try: -```sh +``` man ./soup/man/man1/iocccsize.1 ``` @@ -130,12 +129,13 @@ used and there was no screwing around with the resultant tarball. For more information and examples, try: -```sh +``` man ./soup/man/man1/txzchk.1 ``` NOTE: After doing a `make all`, this tool may be found as: `./txzchk`. + ### `chkentry` The official **IOCCC** `.info.json` and `.auth.json` sanity checker tool. @@ -156,10 +156,9 @@ with improvements made by: [https://ioccc.xexyl.net](https://ioccc.xexyl.net)) - For more information and examples, try: -```sh +``` man ./soup/man/man1/chkentry.1 ``` @@ -172,7 +171,7 @@ The official **IOCCC** XZ compressed tarball filename sanity checker tool. For more information and examples, try: -```sh +``` man ./test_ioccc/man/man1/fnamchk.1 ``` @@ -210,7 +209,7 @@ with minor improvements by: For more information and examples, try: -```sh +``` man ./soup/man/man1/bug_report.1 ``` @@ -237,14 +236,13 @@ with improvements (`-a` and `-s` options via new re-entrant functions) by: For more information and examples, try: -```sh +``` man ./soup/man/man1/location.1 ``` NOTE: After doing a `make all`, this tool may be found as: `./soup/location`. - ## How do I submit my submission to the IOCCC? To submit your submission to the IOCCC, follow the diff --git a/remarks.example.md b/remarks.example.md index 0adff74ef..e805b0d41 100644 --- a/remarks.example.md +++ b/remarks.example.md @@ -2,7 +2,7 @@ 0. For help with markdown format please see this [helpful guide](https://www.markdownguide.org/basic-syntax/). -1. Please see the [IOCCC markdown guidelines](https://ioccc-src.github.io/temp-test-ioccc/markdown.html). +1. Please see the [IOCCC markdown guidelines](https://www.isthe.com/markdown.html). 2. Copy this file into your entry directory under the name: remarks.md