From a6c34f57cf59b6f84bb70aed4d92816d162bc6a9 Mon Sep 17 00:00:00 2001 From: Landon Curt Noll Date: Tue, 3 Sep 2024 01:06:29 -0700 Subject: [PATCH] update FAQ as per changes to jparse and mkiocccentry repos --- faq.html | 35 ++++++++++++++++++++--------------- faq.md | 28 +++++++++++++++++++--------- 2 files changed, 39 insertions(+), 24 deletions(-) diff --git a/faq.html b/faq.html index a0399274d..6c98ac0df 100644 --- a/faq.html +++ b/faq.html @@ -1607,9 +1607,13 @@ tool. The IOCCC version of the jparse(1) tool may be installed from repo contains information about how to find and compile the mkiocccentry toolkit, which includes the IOCCC version of the jparse(1) tool, located -under the mkiocccentry directory as jparse/jparse. Additionally you -may use the make install command to install the mkiocccentry toolkit, -including jparse into the default location of /usr/local/bin/jparse.

+under the mkiocccentry directory as jparse/jparse.

+

Additionally you may install the jparse(1) tool from the jparse +repo:

+
    git clone https://github.com/xexyl/jparse.git
+    cd jparse
+    make clobber all test
+    sudo make install

The syntax of jparse(1) is very simple:

    jparse foo.json

If the tool shows valid JSON then the document is valid JSON; otherwise it’ll @@ -1632,12 +1636,10 @@ the tool.

If you want to validate the .auth.json or .info.json files you should use chkentry(1) from the mkiocccentry repo.

-

chkentry uses the jparse -API; you can use the jparse tool itself to validate JSON documents, discussed -above in the -FAQ on “validating JSON documents” -but the chkentry tool has additional checks on these two IOCCC specific files. -See the +

The chkentry(1) tool uses the +jparse API +API to perform additional checks on these two IOCCC specific JSON files.

+

See the FAQ on “.auth.json” and FAQ on “.info.json” @@ -1658,7 +1660,7 @@ If you pass a single argument, it is expected to be a directory that has both # run checks on .info.json and .auth.json: chkentry .info.json .auth.json

If there is a JSON issue detected by -jparse(3), then there is a JSON error and +jparse(3) API, then there is a JSON error and chkentry(1) will report it as an error. If the parsing is OK (i.e. valid JSON) but there is an issue in one or both of the JSON files in the context of the IOCCC, @@ -3190,9 +3192,9 @@ provided by the author and any other file in the winning entry, found under the entry’s subdirectory.

If you downloaded 1984/mullender/1984_mullender.tar.bz2, for instance, you might then do:

-
        cd 1984/mullender
-        make everything
-        ./mullender.alt
+
        cd 1984/mullender
+        make everything
+        ./mullender.alt

to compile all versions and then run the alternate version (if you have a PDP-11 or VAX-11 you would be able to run the original version). For more help on compiling entries, see also the @@ -3233,8 +3235,8 @@ if you switched to each entry’s directory and ran make everything

If you download the 1984 tarball, i.e. 1984/1984.tar.bz2, then you might extract it and then switch to the directory and compile everything of each entry:

-
        cd 1984
-        make everything
+
        cd 1984
+        make everything

For more help on compiling entries, see also the FAQ on “IOCCC Makefile rules”.

Of course in this case you can also switch to individual entries and look at the @@ -4245,6 +4247,9 @@ if you wish to validate every JSON file in author/ then you could d 

        for auth in *.json; do jparse -q "$auth" || echo "$auth is invalid JSON" ; done

If you see any output then it will say which file or files are invalid JSON (this should not actually happen, however).

+

See the +FAQ on “jparse”, +for now to location and/or install the jparse(1) command.

Walk through of an author_handle.json file
diff --git a/faq.md b/faq.md index 337f1475f..c1644b02d 100644 --- a/faq.md +++ b/faq.md @@ -1377,9 +1377,17 @@ The [FAQ.md file in the mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry/blob/master/FAQ.md#download) contains information about how to find and compile the mkiocccentry toolkit, which includes the IOCCC version of the `jparse(1)` tool, located -under the `mkiocccentry` directory as `jparse/jparse`. Additionally you -may use the `make install` command to install the mkiocccentry toolkit, -including `jparse` into the default location of `/usr/local/bin/jparse`. +under the `mkiocccentry` directory as `jparse/jparse`. + +Additionally you may install the `jparse(1)` tool from the [jparse +repo](https://github.com/xexyl/jparse): + +``` + git clone https://github.com/xexyl/jparse.git + cd jparse + make clobber all test + sudo make install +``` The syntax of `jparse(1)` is very simple: @@ -1418,11 +1426,10 @@ If you want to validate the `.auth.json` or `.info.json` files you should use `chkentry(1)` from the [mkiocccentry repo](https://github.com/ioccc-src/mkiocccentry). -`chkentry` uses the [jparse](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/README.md) -API; you can use the `jparse` tool itself to validate JSON documents, discussed -above in the -FAQ on "[validating JSON documents](#validating_json)" -but the `chkentry` tool has **additional** checks on these two IOCCC specific files. +The `chkentry(1)` tool uses the +[jparse API](https://github.com/ioccc-src/mkiocccentry/blob/master/jparse/man/man3/jparse.3) +API to perform **additional** checks on these two IOCCC specific JSON files. + See the FAQ on "[.auth.json](#auth_json)" and @@ -1449,7 +1456,7 @@ If you pass a single argument, it is expected to be a directory that has both ``` If there is a [JSON](https://www.json.org/json-en.html) issue detected by -`jparse(3)`, then there is a [JSON](https://www.json.org/json-en.html) error and +`jparse(3)` API, then there is a [JSON](https://www.json.org/json-en.html) error and `chkentry(1)` will report it as an **error**. If the parsing is OK (i.e. valid JSON) but there is an issue in one or both of the [JSON](https://www.json.org/json-en.html) files in **the context of the IOCCC**, @@ -5109,6 +5116,9 @@ if you wish to validate every JSON file in `author/` then you could do so like: If you see any output then it will say which file or files are invalid JSON (this should not actually happen, however). +See the +FAQ on "[jparse](#jparse)", +for now to location and/or install the `jparse(1)` command.