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 2025-02-02 10:16:35 -08:00
1 parent 3bef37ecc8
commit 52deabd02a
5 files changed
+127 -23

No files matched your search

+16 -6
View File
@@ -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