From 52deabd02ada8d693cb2121386004c00dcd84707 Mon Sep 17 00:00:00 2001
From: Cody Boone Ferguson <53008573+xexyl@users.noreply.github.com>
Date: Sun, 2 Feb 2025 10:16:35 -0800
Subject: [PATCH] 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).
---
 faq.html                | 22 +++++++++++++------
 faq.md                  | 24 +++++++++++++++------
 markdown.html           | 30 +++++++++++++++++++++-----
 markdown.md             | 47 +++++++++++++++++++++++++++++++++++------
 next/remarks.example.md | 27 +++++++++++++++++++++++
 5 files changed, 127 insertions(+), 23 deletions(-)
 create mode 100644 next/remarks.example.md

diff --git a/faq.html b/faq.html
index 6af4dd737..581d05cd9 100644
--- a/faq.html
+++ b/faq.html
@@ -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
diff --git a/faq.md b/faq.md
index f12383137..3434e9034 100644
--- a/faq.md
+++ b/faq.md
@@ -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:
diff --git a/markdown.html b/markdown.html
index 6f2d54bb7..aa9b7bf05 100644
--- a/markdown.html
+++ b/markdown.html
@@ -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                                   &lt;=== no thank you
+    ## Foo                                  &lt;=== 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>&lt;a&gt;...&lt;/a&gt;</code> hyperlink elements</h2>
diff --git a/markdown.md b/markdown.md
index 480e52738..b823d434e 100644
--- a/markdown.md
+++ b/markdown.md
@@ -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
diff --git a/next/remarks.example.md b/next/remarks.example.md
new file mode 100644
index 000000000..dbec0609b
--- /dev/null
+++ b/next/remarks.example.md
@@ -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)".