@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2021, la-ninpre
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

@@ -0,0 +1,51 @@
+# nimisewi
+
+nimisewi is a small program that outputs random toki pona phrase.
+[toki pona](https://tokipona.org) is a small conlang created by sonja lang.
+
+[first implementation](https://fsl.aaoth.xyz/nimisewi.py)
+was created using python, but then i decided to create more portable version.
+
+## installation
+
+installation is very straightforward:
+
+```terminal
+$ fsl clone https://fsl.aaoth.xyz/nimisewi.c
+$ cd nimisewi
+$ make
+$ doas make install
+```
+
+## usage
+
+```
+$ nimisewi
+
+nanpa apeja pi sin len
+```
+
+## adding new words
+
+to add new words, edit `nimitoki.txt` file. add one word per line.
+
+then, rebuild `nimitoki.c` and `nimitoki.h` and then relink the whole program.
+
+```terminal
+$ vim nimitoki.txt
+$ make distclean
+$ make
+  ...
+```
+
+## bugs
+
+i am pretty much beginner in c, so it is possible that the code contains some
+odd things.
+
+if you have found something wrong or weird,
+send me an email to `aaoth_at_aaoth_dot_xyz`.
+
+## license
+
+isc. see [LICENSE](/LICENSE).

@@ -1,16 +1,31 @@
 /* Copyright (c) 2021, la-ninpre
+ * 
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *
+ * *************************************************************************
+ * 
  * this file creates necessary data files for nimisewi.c.
- *
+ * 
  * i thought that it would be stupid to hardcode all the tokipona words into
  * actual code, so this little program is created. it reads nimitoki.txt file
  * which is in such format that one word is on separate line. i hope it's
  * easy now to add and remove desired words.
- *
+ * 
  * it's use is very narrow and tied to nimisewi.c, but it could be adapted.
  * 
  * TODO: make use of templates, maybe?
  */
+
 #include <err.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -58,10 +73,10 @@
 int
 main(int argc, char *argv[])
 {
+    char *nimitoki_txt_path; /* file path for wordlist file */
     FILE *nimitoki_txt; /* list of words */
     FILE *nimitoki_h;   /* output header file */
     FILE *nimitoki_c;   /* output code file */
-    char *nimitoki_txt_path;
 
 #ifdef __OpenBSD__
     if (pledge("stdio rpath wpath cpath", NULL) == -1) {

@@ -1,3 +1,31 @@
+/* Copyright (c) 2021, la-ninpre
+ * 
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * *************************************************************************
+ * 
+ * this file contains main code for nimisewi.
+ * 
+ * nimisewi is a small program that generates random toki pona noun phrase.
+ * toki pona is a small constructed language created by sonja lang 
+ * (see https://tokipona.org).
+ *
+ * functions and variables here a primarily named in tokipona, just because i
+ * can. but just in case there are annotations in english.
+ *
+ * sona nanpa li ike. taso ona li pali e nimi pona.
+ */
+
 #include <err.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -10,7 +38,14 @@ #include "nimisewi.h"
 #include "nimitoki.h" /* nimi_toki, suli_pi_nimi_toki */
 
 void
-open_e_nanpa_sewi() {
+open_e_nanpa_sewi()
+{
+    /* initialize pseudorandom generator using pid, microseconds and seconds
+     *
+     * for such silly program there's no need to implement cryptographically
+     * secure random number generator.
+     */
+
     pid_t pid;
     struct timeval time;
 
@@ -24,6 +59,23 @@ *pana_e_nimi(const char *nimi_mute[],
              const int suli_pi_nimi_mute,
              const int nanpa_nimi)
 {
+    /* wrapper function to get word from array
+     *
+     * noun phrases in toki pona could have arbitrary amount of words and they
+     * are left grouped (the leftmost word is main, and words to the right
+     * are modifying it:
+     *
+     * ((nimi) sewi)
+     *
+     * special word 'pi' could be used to alter this grouping order to achieve
+     * something like english preposition 'of'
+     *
+     * ((suli) pi ((nimi) mute))
+     *
+     * this functions inserts 'pi' in the middle to avoid generating
+     * very heavy phrases.
+     */
+
     if (nanpa_nimi > suli_pi_nimi_mute) {
         err(EXIT_FAILURE, "index out of bounds");
     } else if (nanpa_nimi == -1) {
@@ -36,6 +88,11 @@
 void
 pana_e_nanpa_nimi(struct nanpa_nimi *nn)
 {
+    /* generate random number, which is later used as number of words
+     * in the phrase
+     *
+     * also here is made decision, whether to insert 'pi'
+     */
     nn->pi_li_lon = 0;
     nn->nanpa_pi = -1;
     nn->nanpa_nimi = (rand() % 6);
@@ -56,6 +113,11 @@ pana_e_nanpa_pi_nimi_sewi(int *nanpa_sewi_mute,
                           const int suli_nimi,
                           struct nanpa_nimi *nn)
 {
+    /* create specified amount of random numbers
+     *
+     * they are used later as indices to get words from wordlist
+     */
+
     int i;
 
     for (i = 0; i <= nn->nanpa_nimi; i++) {
@@ -70,9 +132,9 @@
 int
 main(void)
 {
-    int *nanpa_sewi_nimi;
+    int *nanpa_sewi_nimi; /* container for random indices */
     int i;
-    struct nanpa_nimi nn;
+    struct nanpa_nimi nn; /* see nimisewi.h */
 
 #ifdef __OpenBSD__
     if (pledge("stdio", NULL) == -1) {
@@ -90,6 +152,10 @@ }
 
     pana_e_nanpa_pi_nimi_sewi(nanpa_sewi_nimi, suli_pi_nimi_toki, &nn);
 
+    /* i think that this section could be improved. i had an idea that
+     * it would be cool to include options to output in cgi format instead
+     * of just text
+     */
     for (i = 0; i < nn.nanpa_nimi; i++) {
         printf("%s ",
                 pana_e_nimi(nimi_toki, suli_pi_nimi_toki, nanpa_sewi_nimi[i]));

@@ -1,10 +1,26 @@
+/* Copyright (c) 2021, la-ninpre
+ * 
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
 #ifndef NIMI_SEWI_H
 #define NIMI_SEWI_H
 
+/* struct to hold stuff useful for random index generation */
 struct nanpa_nimi {
-    int nanpa_nimi;
-    int pi_li_lon;
-    int nanpa_pi;
+    int nanpa_nimi; /* number of words */
+    int pi_li_lon;  /* whether to insert 'pi' or not */
+    int nanpa_pi;   /* index to insert 'pi', if pi_li_lon is 1 */
 };
 
 void open_e_nanpa_sewi(void);

@@ -126,4 +126,4 @@ "weka",
     "wile",
 };
 
-const unsigned long suli_pi_nimi_toki = sizeof(nimi_toki)/sizeof(const char *);+const unsigned long suli_pi_nimi_toki = sizeof(nimi_toki)/sizeof(const char *);

@@ -7,4 +7,4 @@
 extern const char *nimi_toki[];    /* list of words */
 extern const unsigned long suli_pi_nimi_toki   /* length of word list */;
 
-#endif /* NIMI_TOKI_H */+#endif /* NIMI_TOKI_H */