Merge pull request #2758 from xexyl/try-scripts

faq.html

@@ -439,6 +439,7 @@
 <li><strong>Q 0.2</strong>: <a class="normal" href="#platform">What platform should I assume for my submission?</a></li>
 <li><strong>Q 0.3</strong>: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a></li>
 <li><strong>Q 0.4</strong>: <a class="normal" href="#remarks">What should I put in the remarks.md file of my submission?</a></li>
+<li><strong>Q 0.5</strong>: <a class="normal" href="#try_scripts">What should I do with the <code>try.sh</code> and <code>try.alt.sh</code> scripts?</a></li>
 </ul>
 <h2 id="entering-the-ioccc-more-help-and-details">1. <a href="#submitting_help">Entering the IOCCC: more help and details</a></h2>
 <ul>
@@ -880,6 +881,24 @@ this is not clear!</li>
 <li>leaving the remark section empty.</li>
 </ul>
 <p>Jump to: <a href="#">top</a></p>
+<div id="try_scripts">
+<h3 id="q-0.5-what-should-i-do-with-the-try.sh-and-try.alt.sh-scripts">Q 0.5 What should I do with the <code>try.sh</code> and <code>try.alt.sh</code> scripts?</h3>
+</div>
+<p>If your submission has more than one use, or if you have interesting ways to
+invoke your program, perhaps using other commonly installed tools (or tools
+included in your submission), it can be helpful to include a <code>try.sh</code> script.</p>
+<p>A <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/template/entry/try.sh">template try.sh</a> can be used as a
+starting point, or you can look at some of the others in the website, to get
+some ideas.</p>
+<p>It is not detrimental to your chances of winning if you do not include one as
+not all submissions can make use of them. Nevertheless, it is helpful to include
+ways to use your program, and if you have creative ways this can be a bonus. It
+does not mean that a program that cannot be used with other programs is less
+interesting or less likely to win, but we do enjoy interesting and creative uses
+of submissions.</p>
+<p>If you have alternate code that you are including, then you can use the
+<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/template/entry/try.alt.sh">try.alt.sh template</a> instead.</p>
+<p>Jump to: <a href="#">top</a></p>
 <hr style="width:50%;text-align:left;margin-left:0">
 <hr style="width:50%;text-align:left;margin-left:0">
 <div id="submitting_help">

faq.md

@@ -13,6 +13,7 @@ This is FAQ version **28.1.3 2024-10-25**.
 - **Q 0.2**: <a class="normal" href="#platform">What platform should I assume for my submission?</a>
 - **Q 0.3**: <a class="normal" href="#makefile">What should I put in my submission Makefile?</a>
 - **Q 0.4**: <a class="normal" href="#remarks">What should I put in the remarks.md file of my submission?</a>
+- **Q 0.5**: <a class="normal" href="#try_scripts">What should I do with the `try.sh` and `try.alt.sh` scripts?</a>
 
 
 ## 1. [Entering the IOCCC: more help and details](#submitting_help)
@@ -511,7 +512,6 @@ The following rules should exist in your Makefile:
 
 Jump to: [top](#)
 
-
 <div id="remarks_md">
 <div id="remarks">
 <div id="readme">
@@ -562,6 +562,32 @@ rounds; we look at the author name only if an entry wins. See the guidelines if
 this is not clear!
 - leaving the remark section empty.
 
+Jump to: [top](#)
+
+
+<div id="try_scripts">
+### Q 0.5 What should I do with the `try.sh` and `try.alt.sh` scripts?
+</div>
+
+If your submission has more than one use, or if you have interesting ways to
+invoke your program, perhaps using other commonly installed tools (or tools
+included in your submission), it can be helpful to include a `try.sh` script.
+
+A [template try.sh](%%REPO_URL%%/template/entry/try.sh) can be used as a
+starting point, or you can look at some of the others in the website, to get
+some ideas.
+
+It is not detrimental to your chances of winning if you do not include one as
+not all submissions can make use of them. Nevertheless, it is helpful to include
+ways to use your program, and if you have creative ways this can be a bonus. It
+does not mean that a program that cannot be used with other programs is less
+interesting or less likely to win, but we do enjoy interesting and creative uses
+of submissions.
+
+If you have alternate code that you are including, then you can use the
+[try.alt.sh template](%%REPO_URL%%/template/entry/try.alt.sh) instead.
+
+
 Jump to: [top](#)
 
 <hr style="width:50%;text-align:left;margin-left:0">

next/guidelines.html

@@ -465,7 +465,7 @@ writing by <a href="../contact.html">contacting the judges</a>.</p>
 </div>
 </div>
 <p class="leftbar">
-These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.20 2024-11-26</strong>.
+These <a href="guidelines.html">IOCCC guidelines</a> are version <strong>28.21 2024-11-27</strong>.
 </p>
 <p><strong>IMPORTANT</strong>: Be <strong>SURE</strong> to read the <a href="rules.html">IOCCC rules</a>.</p>
 <p>Jump to: <a href="#">top</a></p>
@@ -1091,12 +1091,22 @@ Again, please note that in macOS, <code>/usr/bin/gcc</code> is actually <code>cl
 </div>
 </div>
 <p class="leftbar">
-We <strong>LIKE</strong> entries that use an edited variant of the
+We <strong>LIKE</strong> submissions that use an edited variant of the
 <a href="https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example">example Makefile</a>,
 renamed as <code>Makefile</code> of course. This makes it easier for the <a href="../judges.html">IOCCC Judges</a>
 to test your submission. And if your submissions wins, it makes it easier to integrate it into
 the <a href="https://www.ioccc.org/index.html">Official IOCCC winner website</a>.
 </p>
+<p class="leftbar">
+We <strong>LIKE</strong> submissions that use an edited version of the
+<a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/template/entry/try.sh">try.sh</a> template script (and if you have alternate code,
+the same applies with the <a href="https://github.com/ioccc-src/temp-test-ioccc/blob/master/template/entry/try.alt.sh">try.alt.sh</a>
+template script). Of course, it is
+quite possible that only one invocation is possible, so it is not necessarily
+detrimental to your submission if you do not include one, though we do like
+interesting and creative uses of submissions. See also the
+FAQ on “<a href="../faq.html#try_scripts">submitting try.sh and try.alt.sh scripts</a>”.
+</p>
 <p>Doing masses of <code>#define</code>s to obscure the source has become ‘old’. We
 tend to ‘see thru’ masses of <code>#define</code>s due to our pre-processor tests
 that we apply. Simply abusing <code>#define</code>s or <code>-Dfoo=bar</code> won’t go as far

next/guidelines.md

@@ -52,7 +52,7 @@ Jump to: [top](#)
 </div>
 
 <p class="leftbar">
-These [IOCCC guidelines](guidelines.html) are version **28.20 2024-11-26**.
+These [IOCCC guidelines](guidelines.html) are version **28.21 2024-11-27**.
 </p>
 
 **IMPORTANT**: Be **SURE** to read the [IOCCC rules](rules.html).
@@ -862,13 +862,24 @@ Jump to: [top](#)
 </div>
 
 <p class="leftbar">
-We **LIKE** entries that use an edited variant of the
+We **LIKE** submissions that use an edited variant of the
 [example Makefile](https://github.com/ioccc-src/mkiocccentry/blob/master/Makefile.example),
 renamed as `Makefile` of course.  This makes it easier for the [IOCCC Judges](../judges.html)
 to test your submission. And if your submissions wins, it makes it easier to integrate it into
 the [Official IOCCC winner website](https://www.ioccc.org/index.html).
 </p>
 
+<p class="leftbar">
+We **LIKE** submissions that use an edited version of the
+[try.sh](%%REPO_URL%%/template/entry/try.sh) template script (and if you have alternate code,
+the same applies with the [try.alt.sh](%%REPO_URL%%/template/entry/try.alt.sh)
+template script). Of course, it is
+quite possible that only one invocation is possible, so it is not necessarily
+detrimental to your submission if you do not include one, though we do like
+interesting and creative uses of submissions. See also the
+FAQ on "[submitting try.sh and try.alt.sh scripts](../faq.html#try_scripts)".
+</p>
+
 Doing masses of `#define`s to obscure the source has become 'old'.  We
 tend to 'see thru' masses of `#define`s due to our pre-processor tests
 that we apply.  Simply abusing `#define`s or `-Dfoo=bar` won't go as far

next/rules.html

@@ -460,8 +460,10 @@ and remains unaltered. All other uses must receive prior permission in
 writing by <a href="../contact.html">contacting the judges</a>.</p>
 <p>Jump to: <a href="#">top</a></p>
 <div id="rules_version">
+<div id="version">
 <h2 id="ioccc-rules-version">IOCCC Rules version</h2>
 </div>
+</div>
 <p>Jump to: <a href="#">top</a></p>
 <p class="leftbar">
 These <a href="rules.html">IOCCC rules</a> are version <strong>28.10 2024-10-25</strong>.

next/rules.md

@@ -49,8 +49,10 @@ writing by [contacting the judges](../contact.html).
 Jump to: [top](#)
 
 <div id="rules_version">
+<div id="version">
 ## IOCCC Rules version
 </div>
+</div>
 
 Jump to: [top](#)
 

template/entry/try.alt.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# try.sh - demonstrate IOCCC entry abstract alternate code
+#
+# NOTE: if your submission wins and become an entry, 'abstract' will be changed
+# to the YYYY/directory name. You can remove this comment if you wish but if not
+# it'll be done by the judges.
+#
+
+# make sure CC is set so that when we do make CC="$CC" it isn't empty. Doing it
+# this way allows us to have the user specify a different compiler in an easy
+# way.
+if [[ -z "$CC" ]]; then
+    CC="cc"
+fi
+
+make CC="$CC" alt >/dev/null || exit 1
+
+# clear screen after compilation so that only the entry is shown
+clear
+
+# XXX - Invoke the program in one or more ways                    - XXX
+# XXX - It is good to use the shell built-in read to let the user - XXX
+# XXX - read what will happen and then proceed as they wish.      - XXX
+# XXX - You may modify the command based on your program and you  - XXX
+# XXX - may provide more than one invocation.                     - XXX
+# XXX - Please remove the XXX lines                               - XXX
+# XXX - an example follows                                        - XXX
+
+read -r -n 1 -p "Press any key to run: ./prog.alt: "
+echo 1>&2
+./prog.alt

template/entry/try.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# try.sh - demonstrate IOCCC entry abstract
+#
+# NOTE: if your submission wins and become an entry, 'abstract' will be changed
+# to the YYYY/directory name. You can remove this comment if you wish but if not
+# it'll be done by the judges.
+#
+
+# make sure CC is set so that when we do make CC="$CC" it isn't empty. Doing it
+# this way allows us to have the user specify a different compiler in an easy
+# way.
+if [[ -z "$CC" ]]; then
+    CC="cc"
+fi
+
+make CC="$CC" all >/dev/null || exit 1
+
+# clear screen after compilation so that only the entry is shown
+clear
+
+# XXX - Invoke the program in one or more ways                    - XXX
+# XXX - It is good to use the shell built-in read to let the user - XXX
+# XXX - read what will happen and then proceed as they wish.      - XXX
+# XXX - You may modify the command based on your program and you  - XXX
+# XXX - may provide more than one invocation.                     - XXX
+# XXX - Please remove the XXX lines                               - XXX
+# XXX - an example follows                                        - XXX
+
+read -r -n 1 -p "Press any key to run: ./prog: "
+echo 1>&2
+./prog