Add remarks.example.md, update FAQ/guidelines
The next/remarks.example.md filename is kind of a misnomer but it was named this way to match Makefile.example. It has brief instructions along with a link to the FAQ about what one should put in their remarks.md file (and the FAQ links to the new file as a starting point as it has instructions). The markdown guidelines were updated to note that if one does use sections in remarks.md file they should start out at heading level 3 (###) and for each subsection increment it by one (up to level 6).
This commit is contained in:
Cody Boone Ferguson committed
1 parent
3bef37ecc8
commit
52deabd02a
5 files changed
+127
-23
No files matched your search
@@ -425,7 +425,7 @@
|
||||
|
||||
<!-- BEFORE: 1st line of markdown file: faq.md -->
|
||||
<h1 id="ioccc-faq-table-of-contents">IOCCC FAQ Table of Contents</h1>
|
||||
<p>This is FAQ version <strong>28.2.2 2025-01-30</strong>.</p>
|
||||
<p>This is FAQ version <strong>28.2.3 2025-02-02</strong>.</p>
|
||||
<h2 id="entering-the-ioccc-the-bare-minimum-you-need-to-know">0. <a href="#enter_questions">Entering the IOCCC: the bare minimum you need to know</a></h2>
|
||||
<ul>
|
||||
<li><strong>Q 0.0</strong>: <a class="normal" href="#enter">How can I enter the IOCCC?</a></li>
|
||||
@@ -628,10 +628,12 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
|
||||
to a maximum, including the mandatory files, defined in
|
||||
<a href="https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h">limit_ioccc.h</a>
|
||||
as <code>MAX_FILE_COUNT</code>) and other information about your submission,
|
||||
information about the author (or authors), and then it runs a lot of tests before (if
|
||||
all is OK) forming your tarball. After this is done it will additionally run the
|
||||
<code>txzchk(1)</code> tool (which runs the <code>fnamchk(1)</code> tool) on the submission tarball.
|
||||
The tool <code>chkentry(1)</code> will also be run, before creating the tarball. See the
|
||||
information about the author (or authors), and then it runs a lot of tests.</p>
|
||||
<p>If everything is OK, it will write the required <code>.auth.json</code> and <code>.info.json</code>
|
||||
files, checking each with <code>chkentry(1)</code> and then, if all is OK, it will create
|
||||
the tarball. After the tarball is formed, it will run <code>txzchk(1)</code> on it, which
|
||||
runs <code>fnamchk(1)</code>. If all is OK, your submission tarball should be good to go.</p>
|
||||
<p>Please see
|
||||
FAQ on “<a href="#txzchk">txzchk</a>”,
|
||||
the
|
||||
FAQ on “<a href="#fnamchk">fnamchk</a>”
|
||||
@@ -797,7 +799,15 @@ the one linked to above.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>First, <strong>PLEASE</strong> read the <a href="markdown.html">IOCCC markdown guidelines</a>.</p>
|
||||
<p><strong>PLEASE</strong> look at the example remarks.md to give you a better idea of how
|
||||
it should be formed:</p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/ioccc-src/winner/blob/master/next/remarks.example.md">view example remarks.md</a></li>
|
||||
<li><a href="next/remarks.example.md">remarks.md example</a></li>
|
||||
</ul>
|
||||
<p>Read the instructions in the file and <strong>PLEASE</strong> pay especial attention to the
|
||||
instructions, including the <a href="markdown.html">IOCCC markdown guidelines</a>. You will
|
||||
observe that it links back to this FAQ as to what you should or should not say.</p>
|
||||
<p>Next, while you may put in as much or as little as you wish into your entry’s
|
||||
<code>remarks.md</code> file, we do have few important suggestions:</p>
|
||||
<p>We recommend that you explain how to use your entry. Explain the
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# IOCCC FAQ Table of Contents
|
||||
|
||||
This is FAQ version **28.2.2 2025-01-30**.
|
||||
This is FAQ version **28.2.3 2025-02-02**.
|
||||
|
||||
|
||||
## 0. [Entering the IOCCC: the bare minimum you need to know](#enter_questions)
|
||||
@@ -217,10 +217,14 @@ code, your Makefile, your remarks, any other data files you wish to provide (up
|
||||
to a maximum, including the mandatory files, defined in
|
||||
[limit_ioccc.h](https://github.com/ioccc-src/mkiocccentry/blob/master/soup/limit_ioccc.h)
|
||||
as `MAX_FILE_COUNT`) and other information about your submission,
|
||||
information about the author (or authors), and then it runs a lot of tests before (if
|
||||
all is OK) forming your tarball. After this is done it will additionally run the
|
||||
`txzchk(1)` tool (which runs the `fnamchk(1)` tool) on the submission tarball.
|
||||
The tool `chkentry(1)` will also be run, before creating the tarball. See the
|
||||
information about the author (or authors), and then it runs a lot of tests.
|
||||
|
||||
If everything is OK, it will write the required `.auth.json` and `.info.json`
|
||||
files, checking each with `chkentry(1)` and then, if all is OK, it will create
|
||||
the tarball. After the tarball is formed, it will run `txzchk(1)` on it, which
|
||||
runs `fnamchk(1)`. If all is OK, your submission tarball should be good to go.
|
||||
|
||||
Please see
|
||||
FAQ on "[txzchk](#txzchk)",
|
||||
the
|
||||
FAQ on "[fnamchk](#fnamchk)"
|
||||
@@ -431,7 +435,15 @@ Jump to: [top](#)
|
||||
</div>
|
||||
</div>
|
||||
|
||||
First, **PLEASE** read the [IOCCC markdown guidelines](markdown.html).
|
||||
**PLEASE** look at the example remarks.md to give you a better idea of how
|
||||
it should be formed:
|
||||
|
||||
- [view example remarks.md](%%REPO_URL%%/next/remarks.example.md)
|
||||
- [remarks.md example](next/remarks.example.md)
|
||||
|
||||
Read the instructions in the file and **PLEASE** pay especial attention to the
|
||||
instructions, including the [IOCCC markdown guidelines](markdown.html). You will
|
||||
observe that it links back to this FAQ as to what you should or should not say.
|
||||
|
||||
Next, while you may put in as much or as little as you wish into your entry's
|
||||
`remarks.md` file, we do have few important suggestions:
|
||||
|
||||
+25
-5
@@ -431,13 +431,13 @@
|
||||
<h2 id="ioccc-markdown-guidelines-version">IOCCC Markdown guidelines version</h2>
|
||||
</div>
|
||||
<p class="leftbar">
|
||||
These <a href="markdown.html">IOCCC markdown guidelines</a> are version <strong>28.1 2024-12-27</strong>.
|
||||
These <a href="markdown.html">IOCCC markdown guidelines</a> are version <strong>28.1 2025-02-02</strong>.
|
||||
</p>
|
||||
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="next/rules.html">IOCCC rules</a> and <a href="next/guidelines.html">IOCCC
|
||||
guidelines</a>.</p>
|
||||
<p>Jump to: <a href="#">top</a></p>
|
||||
<div id="markdown">
|
||||
<h2 id="ioccc-markdown-guidelines">IOCCC Markdown guidelines</h2>
|
||||
<div id="introduction">
|
||||
<h2 id="ioccc-markdown-guidelines-introduction">IOCCC Markdown Guidelines Introduction</h2>
|
||||
</div>
|
||||
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
|
||||
For example, when submitting to the IOCCC
|
||||
@@ -454,9 +454,29 @@ FAQ on “<a href="faq.html#remarks_md">remarks.md submission file</a>”.</p>
|
||||
<p>Nevertheless, the IOCCC does have certain practices that we ask authors to follow.
|
||||
Some of these relate to use of markdown directly and others relate to injecting HTML
|
||||
into the markdown file.</p>
|
||||
<p>In particular there are things we ask people to please <strong>NOT</strong> use in
|
||||
markdown files for the IOCCC:</p>
|
||||
<p>Jump to: <a href="#">top</a></p>
|
||||
<div id="sections">
|
||||
<h2 id="please-do-start-remarks.md-sections-at-level-3-increasing-for-subsections-up-to-6">Please DO start <code>remarks.md</code> sections at level 3 (<code>###</code>), increasing for subsections up to 6 (<code>######</code>)</h2>
|
||||
</div>
|
||||
<p>IF (it is not required) you do use sections in your <code>remarks.md</code> file (this does
|
||||
not apply to other markdown files), <strong>PLEASE</strong> start at level three:</p>
|
||||
<pre><code> # Foo <=== no thank you
|
||||
## Foo <=== no thank you</code></pre>
|
||||
<p>Instead, start sections with 3 <code>#</code>s:</p>
|
||||
<pre><code> ### Section 0</code></pre>
|
||||
<p>For each subsection of the current section, add another <code>#</code>, up to 6, going back
|
||||
to 3 for new sections. For instance:</p>
|
||||
<pre><code> ### Section 0
|
||||
...
|
||||
#### First subsection of section 0
|
||||
...
|
||||
##### Second subsection of section 0
|
||||
...
|
||||
###### Third subsection of section 0
|
||||
...
|
||||
### Section 1
|
||||
...
|
||||
Etc.</code></pre>
|
||||
<div id="name">
|
||||
<div id="anchor-name">
|
||||
<h2 id="please-do-not-use-the-name-attributes-in-html-a...a-hyperlink-elements">Please do NOT use the <code>name</code> attributes in HTML <code><a>...</a></code> hyperlink elements</h2>
|
||||
|
||||
+41
-6
@@ -7,7 +7,7 @@
|
||||
</div>
|
||||
|
||||
<p class="leftbar">
|
||||
These [IOCCC markdown guidelines](markdown.html) are version **28.1 2024-12-27**.
|
||||
These [IOCCC markdown guidelines](markdown.html) are version **28.1 2025-02-02**.
|
||||
</p>
|
||||
|
||||
**IMPORTANT**: Be sure to read the [IOCCC rules](next/rules.html) and [IOCCC
|
||||
@@ -16,8 +16,8 @@ guidelines](next/guidelines.html).
|
||||
|
||||
Jump to: [top](#)
|
||||
|
||||
<div id="markdown">
|
||||
## IOCCC Markdown guidelines
|
||||
<div id="introduction">
|
||||
## IOCCC Markdown Guidelines Introduction
|
||||
</div>
|
||||
|
||||
The IOCCC makes extensive use of [markdown](https://daringfireball.net/projects/markdown/).
|
||||
@@ -38,11 +38,46 @@ Nevertheless, the IOCCC does have certain practices that we ask authors to follo
|
||||
Some of these relate to use of markdown directly and others relate to injecting HTML
|
||||
into the markdown file.
|
||||
|
||||
In particular there are things we ask people to please **NOT** use in
|
||||
markdown files for the IOCCC:
|
||||
|
||||
Jump to: [top](#)
|
||||
|
||||
<div id="sections">
|
||||
## Please DO start `remarks.md` sections at level 3 (`###`), increasing for subsections up to 6 (`######`)
|
||||
</div>
|
||||
|
||||
IF (it is not required) you do use sections in your `remarks.md` file (this does
|
||||
not apply to other markdown files), **PLEASE** start at level three:
|
||||
|
||||
``` <!---markdown-->
|
||||
# Foo <=== no thank you
|
||||
## Foo <=== no thank you
|
||||
```
|
||||
|
||||
Instead, start sections with 3 `#`s:
|
||||
|
||||
|
||||
``` <!---markdown-->
|
||||
### Section 0
|
||||
```
|
||||
|
||||
For each subsection of the current section, add another `#`, up to 6, going back
|
||||
to 3 for new sections. For instance:
|
||||
|
||||
|
||||
``` <!---markdown-->
|
||||
### Section 0
|
||||
...
|
||||
#### First subsection of section 0
|
||||
...
|
||||
##### Second subsection of section 0
|
||||
...
|
||||
###### Third subsection of section 0
|
||||
...
|
||||
### Section 1
|
||||
...
|
||||
Etc.
|
||||
```
|
||||
|
||||
|
||||
<div id="name">
|
||||
<div id="anchor-name">
|
||||
## Please do NOT use the `name` attributes in HTML `<a>...</a>` hyperlink elements
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Instructions
|
||||
|
||||
0. Create an empty file `remarks.md` in your submission directory
|
||||
(alternatively after reading this file, delete everything in it and rename it
|
||||
`remarks.md`).
|
||||
|
||||
1. For help with markdown format please see this [helpful
|
||||
guide](https://www.markdownguide.org/basic-syntax/).
|
||||
|
||||
2. Please see and follow the [IOCCC markdown
|
||||
guidelines](https://www.ioccc.org/markdown.html). Doing this helps the judges
|
||||
integrate your remarks into a `README.md`, should you win.
|
||||
|
||||
3. After reading this file, write your remarks in your `remarks.md` file (as
|
||||
mentioned in step 0).
|
||||
|
||||
4. When packaging your submission with `mkiocccentry(1)`, make sure that the
|
||||
`remarks.md` is in the `topdir`.
|
||||
|
||||
**IMPORTANT NOTE**: make **SURE** you read the IOCCC
|
||||
[Rules](https://www.ioccc.org/next/rules.html) and
|
||||
[Guidelines](https://www.ioccc.org/next/guidelines.html)!
|
||||
|
||||
# What should you say?
|
||||
|
||||
Please see the
|
||||
FAQ on "[what to put in your remarks](../faq.html#remarks)".
|
||||
Reference in new issue
Block a user