Skip to content

Commit

Permalink
Many updates and fixes to FAQ
Browse files Browse the repository at this point in the history 
Added version to FAQ - first version is 28.0.0 2024-07-31 (same format
to the temp-test-ioccc repo but since the version is just being added it
is at 28.0.0).

Removed FAQs about how to use the tools in favour of just one FAQ about
how to participate in the contest. This FAQ links to the proper FAQs in
the temp-test-ioccc repo (the rendered html) with the note that the
links will have to be updated once the great fork merge happens (this is
in XXX html comments), the rules and the guidelines. This way the FAQ
here focuses on how to obtain, compile and get help on these tools (as
well as if necessary report bugs though that is also in the other repo's
FAQ). Also the information is not duplicated.

It is however unclear to me if the FAQ in the other repo should just
refer to the FAQ here: maybe (probably I would guess) it should but
right now it does not. This can be decided and fixed later.

Reorganised the order of the questions in what I think flows a bit
better (for certain definitions of better I suppose).

Added new named tags/links and the table of contents links to those
instead of something like '#0-where-can-i-find-the-mkiocccentry-tool'
which would have to be updated if the question changes or even if the
number changes (which as this commit shows can happen).
  • Loading branch information
@xexyl
xexyl committed Jul 31, 2024
1 parent 4ba5d59 commit fb006b5
Showing 1 changed file with 104 additions and 171 deletions.
275 changes: 104 additions & 171 deletions FAQ.md
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,33 @@
# Frequently Asked Questions about the `mkiocccentry` repo

This is FAQ version **28.0.0 2024-07-31**.

<div id="toc"></div>

## Table of Contents

0. [Where can I download the mkiocccentry tool?](#0-where-can-i-find-the-mkiocccentry-tool)
0. [Where can I download the mkiocccentry toolkit?](#download)

1. [How do I compile the mkiocccentry tools?](#1-how-do-i-compile-the-mkiocccentry-tool)
1. [How do I compile the mkiocccentry tools?](#compiling)

2. [How do I package my submission?](#2-how-do-i-package-my-submission)
2. [Do I need to install this code to use it?](#install)

3. [What do I do for the Makefile in my submission?](#3-what-do-i-do-for-the-makefile-in-my-submission)
3. [What can I do if my system's tar(1) does not support the correct options?](#tar)

4. [Can't I just submit my obfuscated C program to the judges?](#4-cant-i-just-submit-my-obfuscated-c-program-to-the-judges)
4. [How can I learn more about how to use the tools?](#help)

5. [Do I have to use mkiocccentry to package my submission?](#5-do-i-have-to-use-mkiocccentry-to-package-my-submission)
5. [How do I report bugs or other issues?](#bugs)

6. [Do I need to install this code to use it?](#6-do-i-need-to-install-this-code-to-use-it)
6. [How can I help test this repo?](#how-to-help)

7. [How can I learn more about how to use the tools?](#7-how-can-i-learn-more-about-how-to-use-the-tools)
7. [Why do these tools sometimes use the incorrect IOCCC terms?](#terms)

8. [How do I report bugs or other issues?](#8-how-do-i-report-bugs-or-other-issues)

9. [How can I help test this repo?](#9-how-can-i-help-test-this-repo)

10. [What can I do if my system's tar(1) does not support the correct options?](#10-what-can-i-do-if-my-systems-tar1-does-not-support-the-correct-options)

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)

12. [Why do these tools sometimes use the incorrect IOCCC terms?](#12-why-do-these-tools-sometimes-use-incorrect-ioccc-terms)
8. [How do I participate in the IOCCC?](#ioccc)


<div id="download"></div>

## 0. Where can I find the mkiocccentry tool?
## 0. Where can I find the mkiocccentry toolkit?

The `mkiocccentry` tool source code is found in the
[mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry).
Expand All @@ -46,18 +39,18 @@ clone`:
git clone https://github.com/ioccc-src/mkiocccentry.git
```

If you don't have `git` you may
If you don't have `git` you can instead
[download the zip file](https://github.com/ioccc-src/mkiocccentry/archive/refs/heads/master.zip)
and then extract that file.



<div id="compiling"></div>

## 1. How do I compile the mkiocccentry tool?
## 1. How do I compile the mkiocccentry tools?

After downloading the repo (making sure that if you downloaded the zip file that
you unzip it first) move into the _mkiocccentry_ directory:
you unzip it first) move into the `mkiocccentry` directory:

``` <!---sh-->
cd mkiocccentry
Expand All @@ -74,100 +67,10 @@ local directory. If something went wrong, see
<a href="#reporting-bugs">how do I report bugs or other issues?</a>


<div id="package"></div>

## 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)
(instructions <a href="#download">here</a>)
and compile it
(instructions <a href="#compiling">here</a>).

From the top level directory, run the `mkiocccentry` executable:

``` <!---sh-->
./mkiocccentry work_dir prog.c Makefile remarks.md [file ...]
```

The _work_dir_ is the path where your submission's files will be packaged from.
The _work_dir_ **must** exist as _mkiocccentry_ will create a subdirectory under it to
package your submission. The submission directory depends on the IOCCC contestant id and
the submit slot number.

Something like _/tmp/ioccc_ is a good choice:

``` <!---sh-->
mkdir -p /tmp/ioccc
```

The _prog.c_ is the path to the main C source code for your submission.

The _Makefile_ is the path to a Makefile used to build your submission.

The _remarks.md_ is a path to a
[markdown file](https://www.markdownguide.org/basic-syntax)
that describes your submission.

If you have other optional files that belong to your submission, give them
as additional paths at the end if your `mkiocccentry` tool command line.

The `mkiocccentry` tool, by default, will ask you a series of
questions about your submission and about the authors of your submission.
Once you have answered all of the questions, the tool will form a
XZ compressed tarball, in v7 format, under the _work_dir_ directory.


<div id="makefile"></div>

## 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.


<div id="submitting"></div>

## 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
using the `mkiocccentry` tool to package your submission.

We need your submission in the form of an XZ compressed tarball in v7 format,
along with things like your Makefile, a pair of JSON files that
help describe you and your submission, some remarks you wrote about your
submission etc. The `mkiocccentry` tool does a lot in packaging your
submission and we kindly request that you use it.

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.


<div id="mkiocccentry-requirements"></div>

## 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
malformed. Moreover, the contents of the XZ compressed tarball (in v7 format)
that you upload to the submit server must be in proper form or your submission could
be rejected. The mkiocccentry tool also creates two JSON files that are
required. Therefore we highly recommend that you use the `mkiocccentry` tools.

If you simply must package your submission yourself then we strongly recommend that
you use the `txzchk` tool to verify that the tarball you plan to upload to the
submit server is OK. We also strongly recommend that use the `chkentry` tool to
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.


<div id="install"></div>
<div id="installing"></div>

## 6. Do I need to install this code to use it?
## 2. 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
Expand All @@ -176,19 +79,39 @@ installing, whichever you prefer.
You can simply execute the code from the top level directly of the source, after
compiling of course.

As `.` may not be (and probably shouldn't be) in your `$PATH`, you may need to
put _./_ before the name of a command.
As `.` might not be (and almost certainly should NOT be) in your `$PATH`, you
might need to put `./` before the name of a command.

For example:

``` <!---sh-->
./mkiocccentry -h
```

However, it is much easier if you do run `make install` (as root or via sudo) as
then you can just run it from your submission's directory (the one you work on
it from) or anywhere else. On the other hand the `bug_report.sh` script needs to
be run from the repo directory itself. Of course, you should make sure you have
the latest version of the toolkit prior to using it!

<div id="tar"></div>

## 3. 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
which does have such a `tar` or you can try downloading GNU Tar from
the [GNU website](https://www.gnu.org/software/tar/) and after extracting it,
compile it and then install it so that the tools may find it.

Some systems have a `GNU tar` that you can use. For instance FreeBSD has a
`gtar` command so if necessary you can use that. Note that you'll have to
specify in the tools (that require a correct `tar`) the `-t tar` option to make
this work.


<div id="help"></div>

## 7. How can I learn more about how to use the tools?
## 4. How can I learn more about how to use the tools?

Assuming you have <a href="#download">downloaded</a> and <a
href="#compiling">compiled</a> the code you can get a quick reminder of command
Expand Down Expand Up @@ -227,21 +150,26 @@ Luke!"_ as you may find the code in this repo reasonably un-obfuscated and fairl
well commented.


<div id="bugs"></div>
<div id="reporting-bugs"></div>

## 8. How do I report bugs or other issues?
## 5. How do I report bugs or other issues?

If you've run into a problem with the repo and you think it is a bug then you
should [report it as a
bug](https://github.com/ioccc-src/mkiocccentry/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D+%3Ctitle%3E),
making sure to give as much information as possible.

Please run the following from the main directory:
To help us help you **PLEASE** run the following command from the **top level
mkiocccentry directory** (in other words, if you have [installed](#install) the
toolkit you **MUST** still run this from the toolkit directory):


``` <!---sh-->
make bug_report
```

and open a new issue at the
[GitHub issues page](https://github.com/ioccc-src/mkiocccentry/issues/new/choose),
making sure to give us as much information on your problem as possible and
making sure to attach the bug report file.
and then attach the bug report log (see below about the filename).

You may also run the `bug_report.sh` tool directly:

Expand All @@ -253,11 +181,11 @@ The bug report filename is in the format:
`bug-report.$(/bin/date +%Y%m%d.%H%M%S).txt` where:


- `%Y` is the four digit year (e.g. 2023).
- `%Y` is the four digit year (e.g. 2024).

- `%m` is the two digit month (01..12).

- `%d` is the two digit day of the month (e.g. 30).
- `%d` is the two digit day of the month (e.g. 31).

- `%H` is the two digit hour of the day (00..23).

Expand All @@ -269,10 +197,19 @@ The bug report filename is in the format:
The script that the make rule runs, `bug_report.sh`, will tell you the name of
the file to upload.

**NOTE**: the script might report that there is no problem but that does not
mean there is no bug; on the other hand even if it reports a problem it does not
necessarily mean there is a bug but you can report it as a bug as we can
hopefully help. Feel free to use your judgement in this matter but most likely
unless it's a feature request the best one is a bug report.

On the other hand, see the [SECURITY](SECURITY.md) file if you have a security
concern.


<div id="how-to-help"></div>

## 9. How can I help test this repo?
## 6. How can I help test this repo?

Thank you for any and all help!

Expand All @@ -281,66 +218,62 @@ Please see the
for more details on what you can do to help us.


<div id="tar"></div>

## 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
which does have such a tar or you can try downloading GNU Tar from
the [GNU website](https://www.gnu.org/software/tar/) and after extracting it,
compile it and then install it so that the tools may find it.

Some systems have a `GNU tar` that you can use. For instance FreeBSD has a
`gtar` command so if necessary you can use that. Note that you'll have to
specify in the tools the `-t tar` option to make this work.


<div id="markdown"></div>
<div id="terms"></div>

## 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.

See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
See also [CommonMark Spec](https://spec.commonmark.org/current/).


<div id="keyword"></div>

## 12. Why do these tools sometimes use incorrect IOCCC terms?
## 7. 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
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?
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?

Because the name `mkiocccentry(1)` and this repo name was selected
before decisions were made in regards to the IOCCC term _entry_.
before decisions were made in regards to the IOCCC term `entry`.
And besides, the name `mkiocccentry(1)` contains a fun pun. And
renaming the repo is not worth the hassle.
renaming the repo and updating all the code and data files (of which there are
many) is not worth the hassle.

If the inconsistency bothers you, think of the name `mkiocccentry(1)`
as a hopeful sign that the _submission_ it is processing might
as a hopeful sign that the `submission` it is processing might
actually win the IOCCC and become a winning entry. :-) After all,
some submissions do go on to become winners, so maybe yours will too. :-)

You may find inconsistent use of _Author_, _Entry_, and _Submission_
in this repo as well. The above "excuse" for _entry_ instead of _submission_ is
You may find inconsistent use of `Author(s)`, `Entry`, and `Submission`
in this repo as well. The above "excuse" for `entry` instead of `submission` is
just an example.

We made an attempt to correct some of the inconsistent use of the
terms _Author_, _Entry_, and _Submission_ in this repo. If you DO
terms `Author(s)`, `Entry`, and `Submission` in this repo. If you DO
find a situation where the inconsistency is causing a problem and/or
confusion, please let us know in the way of a bug report or if you're sure that
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_.
it's correct, a pull request that corrects the mistake or mistakes. Please note
that if you do this you **MUST** run `make prep` or at least `make test`. Not
doing this poses a great risk of causing problems.

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 submission(s)
won then it should be `entry` (or `entries`).

<div id="ioccc"></div>

## 8. How do I participate in the IOCCC?

Please see the [official IOCCC website
FAQ](https://ioccc-src.github.io/temp-test-ioccc/faq.html) and in particular the
FAQ on
"[submitting](https://ioccc-src.github.io/temp-test-ioccc/faq.html#submit)",
the
FAQ on
"[Makefiles](https://ioccc-src.github.io/temp-test-ioccc/faq.html#makefile)",
the
FAQ on "[source code
filename](https://ioccc-src.github.io/temp-test-ioccc/faq.html#prog),
the
FAQ on
"[mkiocccentry](https://ioccc-src.github.io/temp-test-ioccc/faq.html#mkiocccentry),
the [Rules](https://ioccc-src.github.io/temp-test-ioccc/next/rules.html) and the
[Guidelines](https://ioccc-src.github.io/temp-test-ioccc/next/guidelines.html).

Pay especial care to [Rule
17](https://ioccc-src.github.io/temp-test-ioccc/next/rules.html#rule17)!

0 comments on commit fb006b5

Please sign in to comment.