2023-02-04 A journal with single-line entries with timestamps ================================================== On 2023-02-01, I discovered the article "Simple Tools" by James Card, which you can find here: spartan://jdcard.com:3300/SimpleTools.gmi gemini://jdcard.com/SimpleTools.gmi http://jdcard.com/SimpleTools.gmi It contains the description of a script called "j", which takes a line of text and appends it to a journal file, along with the current date and time. You can supply the line either as a single command line argument (i.e. in quotes), as multiple command line arguments (i.e. as separate words without quotes, like with the echo utility), or as a line on stdin (which you would usually type out in the terminal, but technically you could also pipe it in). The date and time, which are separated by a space, are prepended to the text line with a space too. After every transaction, the last 5 lines of the journal file are printed out. I'm amazed by the brilliance and simplicity of this concept. I usually keep notes about different categories (books read, films watched, other diary stuff) in files like ~/logs/YYYY/mm/dd/CATEGORY.txt. But with varying definitions of a day's boundary (at midnight? but what if you go to bed after that? but what if on one day you didn't go to bed at all? etc.), it can be hard to decide which directory to put a note in. And after a few weeks, you would never remember *when exactly* during a day some particular thing happened, unless you tediously supplied the time by hand. With the "j" script, the date and time are automatically attached to every line that comes in. It's like sending a short message to yourself (which some people actually do instead of taking notes, but the "j" script is more privacy-friendly as it operates only on your machine). You can use it to document your thoughts, feelings, or discoveries, or to keep a "logfile" of what you're doing--and everything is stored along with the very second of your life in which you wrote it, in a uniform way that is easy to process. Because why should some computer-internal process have a more detailed record than your own life? Of course, both my directory approach and the timestamp approach of "j" can coexist easily. For example, you could extract lines from your journal file and insert them into the directory hierarchy at a later point. And because entries are so quick to make with "j", you can just give it whatever comes to your mind and discard the less valuable entries later, finalizing your journal in the directory hierarchy. My changes ---------- I've written my own version of the "j" script, which you can find at /sh/j.sh on this server. It differs from the script presented in the article in the following ways: 1. Every line has the format "YYYY-mm-dd HH:MM:SS +zzzz TEXT\n", where "+zzzz" is a time zone like "-0400" or "+0545". This gives each entry an unambiguous point in time. Four digits are both necessary and sufficient to cover all time zones.^[1] 2. To locate the journal file, the environment variable JOURNAL (instead of JRNL) is checked. 3. If no $JOURNAL is specified, ~/journal is used by default (without "~/Documents/" or ".txt"). I thought about [ "${journal:="$JOURNAL"}" ] || journal="$(xdg-user-dir DOCUMENTS 2> /dev/null)/journal.txt" || journal="${HOME:?}/journal.txt" at first, which would use $JOURNAL if specified, or else ~/Documents/journal.txt (with the language-specific equivalent of ~/Documents/) if the XDG user directory utility is installed, or else ~/journal.txt. But after reading the well-written gopher://manpager.net/0/art/hier.txt , I decided against it. 4. Instead of just $1, $* is checked for input. This recognizes input on the command line even if $1 is (for some reason) "". 5. The script doesn't prompt for input when reading from stdin. 6. If both the command line input is empty (which triggers reading from stdin) as well as the line read from stdin, skip adding the empty line to the journal and just show the last 5 lines of the journal without changing it. This means you can check your last entries simply by typing "j" and hitting Return twice. (You might consider this an anti-feature if you want to use j+Return+Return as a kind of "quick (anonymous) checkpoint marker".) 7. The script uses printf instead of echo, as echo is considered harmful^[2]. 8. By using printf and date instead of ts, the script only depends on the GNU coreutils instead of the moreutils package. Licensing --------- I use the GNU GPLv3+ for all of my software, whereas James Card uses the CC BY-NC-SA 4.0 license for all of his articles. If my version of the "j" script were to be considered an adaptation of his article, then I wouldn't be allowed to publish the script under the GPL, as it allows people to sell my script and all derivative works, for example, whereas the BY-NC-SA license prohibits this. However, I believe that my script doesn't contain any material from the article that is large enough to be still under copyright. I've only taken very few code lines (and no text) from the article in the first place and changed them considerably. Imagine, for example, if the article had been published under the CC BY-ND license: I believe I still would have been able to publish my script even though the BY-ND license doesn't allow *any* adaptations. From the CC FAQ: Do I always have to comply with the license terms? If not, what are the exceptions? You need to comply with the license terms if what you are doing would otherwise require permission from the rights holder. If your use would not require permission from the rights holder because it falls under an exception or limitation, such as fair use, or because the material has come into the public domain, the license does not apply, and you do not need to comply with its terms and conditions. Additionally, if you are using an excerpt small enough to be uncopyrightable, the license does not apply to your use, and you do not need to comply with its terms. (https://creativecommons.org/faq/) I still intend to inform James Card of my use and I have mentioned the article in my script. Footnotes --------- ^[1] See . ^[2] See . About this document ------------------- I had published a previous version, which was much shorter and written in Gemtext, on 2023-02-01, but I have since taken it down. This document was last updated on 2023-02-05. Copyright (C) 2023 Daniel Kalak This document is licensed under the CC BY-ND 4.0 International License. Learn more at . EOF