Consider adhering to the XDG Base Directory specification

[ccjmne]

Calc is a stunningly competent tool, its documentation and the ease of browsing of its code base are astonishing, the way it integrates most completely with the rest of one's terminal habits and tools is an utter delight, and your consistently impeccable follow-throughs and curation efforts throughout the issues here are outright splendid.
Thank you very much for all of this!

Is your feature request related to a problem? Please describe.

I'm a bit bothered with tools generally polluting my home directory, and the XDG (now "freedesktop.org") established a number of largely well adopted specifications to try and rally people and their tools around some agreements. One such specification contends with where files may go: the XDG Base Directory specification.

I know full well that calc employs the CALCPATH, CALCRC, and CALCHISTFILE environment variables well, but I wish it'd be just that one little bit nicer if I could have it sniff out content where the XDG suggests content may be best found.

Describe the solution you'd like

In summary, I'd like:

• CALCPATH to additionally look into $XDG_DATA_HOME/calc,
• CALCRC to additionally look into $XDG_CONFIG_HOME/calc/startup, and
• CALCHISTFILE to use $XDG_STATE_HOME/calc_history.

More specifically, so as to not possibly disrupt any preexisting user set-ups, we could/should have:

• CALCRC only look there as a "last resort", after all the other paths searched by default have been exhausted and come up empty, and
• CALCHISTFILE only default to preferring $XDG_STATE_HOME/calc_history if $XDG_STATE_HOME is defined.

I don't believe that taking any precautionary measure against attempting to read what the user may have in XDG_DATA_HOME/calc would be necessary.

I calqued XDG_CONFIG_HOME/calc/startup's name from its default search path component for system-wide configuration, /usr/share/calc/startup, but have no strong opinion on the naming there—except the considerable preference for a plain (read: non-hidden, non-dot-prefixed) file.

Describe alternatives you've considered

I did use CALCPATH, CALCRC, and CALCHISTFILE, as intended, to great effect already.

---

PS: I'm not too sure how they're generated but it seems that the copyright history is missing the years.
I had a quick look through their history and the only vaguely remarkable hint I came by was this curious replacement of 19xx by year in help/credit some time ago, in 9b6c308#diff-772e33e523d07c0ef8fb9912992a9bae5d74666a4c98caaae8b7d6b2d2ad99c5:

-Copyright (c) 19xx David I. Bell
-Copyright (c) 19xx David I. Bell and Landon Curt Noll
-Copyright (c) 19xx Landon Curt Noll
-Copyright (c) 19xx Ernest Bowen and Landon Curt Noll
+Copyright (c) year David I. Bell
+Copyright (c) year David I. Bell and Landon Curt Noll
+Copyright (c) year Landon Curt Noll
+Copyright (c) year Ernest Bowen and Landon Curt Noll

For reference, here are the "copyright history" entries I am talking about:

calc/COPYING

Lines 114 to 125 in 86a14ec

	Copyright (C) year David I. Bell
	Copyright (C) year David I. Bell and Landon Curt Noll
	Copyright (C) year David I. Bell and Ernest Bowen
	Copyright (C) year David I. Bell, Landon Curt Noll and Ernest Bowen
	Copyright (C) year Landon Curt Noll
	Copyright (C) year Ernest Bowen and Landon Curt Noll
	Copyright (C) year Ernest Bowen
	Copyright (C) year Petteri Kettunen and Landon Curt Noll
	Copyright (C) year Christoph Zurnieden
	Copyright (C) year Landon Curt Noll and Thomas Jones-Low
	Copyright (C) year Klaus Alexander Seistrup and Landon Curt Noll
	Copyright (C) year Viktor Bergquist

calc/calc.man

Lines 1337 to 1347 in 86a14ec

	Copyright (C) year David I. Bell
	Copyright (C) year David I. Bell and Landon Curt Noll
	Copyright (C) year David I. Bell and Ernest Bowen
	Copyright (C) year David I. Bell, Landon Curt Noll and Ernest Bowen
	Copyright (C) year Landon Curt Noll
	Copyright (C) year Ernest Bowen and Landon Curt Noll
	Copyright (C) year Ernest Bowen
	Copyright (C) year Petteri Kettunen and Landon Curt Noll
	Copyright (C) year Christoph Zurnieden
	Copyright (C) year Landon Curt Noll and Thomas Jones-Low
	Copyright (C) year Klaus Alexander Seistrup and Landon Curt Noll

calc/help/credit

Lines 29 to 39 in 86a14ec

	Copyright (C) year David I. Bell
	Copyright (C) year David I. Bell and Landon Curt Noll
	Copyright (C) year David I. Bell and Ernest Bowen
	Copyright (C) year David I. Bell, Landon Curt Noll and Ernest Bowen
	Copyright (C) year Landon Curt Noll
	Copyright (C) year Ernest Bowen and Landon Curt Noll
	Copyright (C) year Ernest Bowen
	Copyright (C) year Petteri Kettunen and Landon Curt Noll
	Copyright (C) year Christoph Zurnieden
	Copyright (C) year Landon Curt Noll and Thomas Jones-Low
	Copyright (C) year Klaus Alexander Seistrup and Landon Curt Noll

[lcn2]

Thank you for your kind words, @ccjmne

We will review your post and give it a good consideration afterwards.

Stay tuned ...

[lcn2]

TL;DR

Made historic observations about UNIX from the mid 1970's, the history of the ls -a command, and "dot-files".

Details

Thank you again for your kind words about calc, @ccjmne

The idea you suggest is an interesting one. I am partly sympathetic to the issue of putting lots of stuff into $HOME. It is one of the reasons why calc uses only "dot-files".

Back in the days of UNIX 5th addition (not System V, but the 5th addition of the UNIX manual set) and PWB UNIX (we are talking 1974 era), the ls(1) command was changed to NOT list files that begin with "." (Dot). Mostly this was because every directory had both "." (Dot) and ".." (Dot-Dot) and those of us with teletype printers (that printed at about 10 characters per second) found it annoying to have to wait until the ls(1) commands would get pack those two before printing stuff that was interesting.

Beginning with UNIX 6th edition, the ls(1) command required one to use -a to list all files. This convenience started the notion of having one's personal config files (such as .profile) to become a "dot-file" so that it too wasn't printed.

So I found it annoying when programs started landing cruft in the home directory that wasn't a "dot file". Some early window managers began to populate non-dot files under the home directory: especially those that tried to give one a so-called "desktop environment". With various window/desktop managers one could make an effort to rename some of those "mandatory" files and directories into "dot-files/dot-directories" and/or move them elsewhere. However window manager/desktop bugs, updates, and new features made that an on-going maintenance task.

So yes, I am sympathetic in part to the general concept. If was up to me, such "mandatory" files and directories would be only "dot-files/dot-directories". But that is a tall order to ask.

Thus, there is some merit to the XDG concept.

On the other hand, I suspect you will find it difficult to "hurd the cats" in terms of files and directories. I suspect for a while, and unless the XDG concept comes into wide spread use, you will face a combination of things that "plop" stuff under the home directory, "dot-files/dir-directories", and XDG compliant stuff.

Best wishes on trying to get the XDG concept adopted.

I will talk about calc next .. and ask a question about XDG.

[lcn2]

Calc v2

The current calc version 2.16.1.2 is now a frozen release. It is a legacy release, especially for the hardware accelerators that use the calc v2 memory models. It is unlikely that we will modify that calc v2 code base.

The situation for calc v2 is not lost, however. Depending on how the calc v3 works with the XDR specification, we could make edits to the calc repo README.md and related documentation to suggest how someone should set environment variables to allow calc v2 to "play nicely" in an XDR world. Such a repo level documentation update would also reference the XDR specification URL.

We guess that with the setting of the right environment variables, @ccjmne, calc v2 could make use of the XDR support concept.

Calc v3

The current effort is focused on release in calc v3.

Calc version 3 is designed to support MUCH LARGER numeric models. The calc v2 code was limited to values of about 128 MBytes, in part because of 16-bit and 32-bit processors where 28 bits of address space was considered "huge". ;-)

Calc version 3 will drop support of 16-bits and 32-bits processors: supporting only 64-bits and larger CPU word sizes. The memory models we target are to support values that are 128 TByte (47 bit) and larger. The upper limit is TBD. Moreover the upper limit will be a configuration parameter so that is in the future 128 TByte values are "too small", a configuration parameter change is all it takes to increase it.

The calc v3 memory model will have 64-bit pointers, and lengths that could support 64-bits values. However testing such large values today is impractical. :-) Given our resources, we plan to limit our testing to 128 TBytes values.

XDR and calc

We not going to modify calc v2. So XDR specification support will be on calc v3 only.

The calc v3 code is highly experimental at this stage. Within a year or two, we hope to try and release our first "stable" calc v3 code .. assuming coding efforts and testing go as planned.

So adding XDR support into calc v3 comes at the right time. Had you made the request about 6 months ago, calc v2 could have consider this. Sorry @ccjmne: we home you understand our reluctance to modify the frozen legacy calc 2 code base.

FYI: The calc v3 code is found under the calcv3 branch. The current master branch is calc v2 until some version of calc v3 becomes stable.

So we want to add XDR support into calc v3. In the next comment we have a question for you, @ccjmne about the XDR specification support.

[lcn2]

QUESTIONS

Please consider each of these questions, @ccjmne :

0. What happens of someone does not set an environment variable such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME?

1. What happens if an environment variable such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME exist, but is an empty string?

2. What happens if an environment variable such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME exist, but the path it references does not exist?

3. What happens if an environment variable such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME exists, and the path it references does exist, but is not accessible: say the path is mode 0, or the path is read-only (and calc needs to create a file), or the directory cannot be searched, or there is some other permissions problem with the path making it unusable by calc?

4. What happens if an environment variable such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME exist, but the value is BOGUS: say it contains byte values that are not allowed by the file system, or is a path that is longer than the file system/kernel supports, or some other garbage data?

5. What other environment variables do you think calc v3 will need to consider besides $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME?

6. Calc v3 could be written to look for environment variables such as $XDG_CONFIG_HOME, or $XDG_DATA_HOME, or $XDG_STATE_HOME, and that variable is problematic, then calc could fall back to $HOME, and if that doesn't work, then calc could fall back to something else. This way, if someone were attempt to use the XDG specification, and the proper environment variables are set to useable paths, things could do well. Otherwise $HOME and dot files would be used. What do you think of that idea, @ccjmne ?

[ccjmne]

Thank you, @lcn2, and all the collaborators you are the emissary of!

I understand your justified reluctance to introduce this change to v2, and have no problem with any of it. I'd even go so far as to be somewhat flustered that such a vaguely punctilious request is given that much attention amidst the greater designs and plans you have for calc.

0. As far as I've seen, software considering these variables generally offers a fall-back for each of these, most notably specifically as such:

   • ${XDG_CONFIG_HOME:-$HOME/.config}
   • ${XDG_DATA_HOME:-$HOME/.local/share}
   • ${XDG_STATE_HOME:-$HOME/.local/state}
   • ${XDG_CACHE_HOME:-$HOME/.cache}
     These are in line with the recommendations outlined in section 3 of that same Base Directories specification document.

1. The same document suggests that any of these variables being defined but empty shall be functionally equivalent to them not being defined. I can only speak to the execution of that vision by commenting that, from my limited experience, the very ${X:-Y} parameter expansion (which will use Y whenever X is either unset or empty) constitutes the idiomatic implementation. It indeed suggests I mostly base my understanding on shell scripts, however ;-)

2. Huh! I would think that the least astonishing response would be to emit an error, but in that case, I would rather hope that whichever program is first made to rely on this (then presumably non-existing) directory structure would just create it: if the environment specifies these variables, I would argue it would appreciate the paths they're pointing to being reified as soon as necessary. Generally, perhaps at the cost of some terseness, the configuration files are stored not directly under $XDG_CONFIG_HOME, but rather one level further down, in $XDG_CONFIG_HOME/my_project/config.ini (even when there is only one such file): that doesn't really make nor break any hypothesis, but I recall noting that some tools happily mkdir -p the whole path without much ceremony, since they're gonna mkdir something anyway. All of this is fairly anecdotal but maybe still of some relevance.

3. If we consider the definition of these variables to constitute general instructions that clash with the permissions given to calc or the more general environment set-up, I believe it correct to error out.

4. Good grief... you're correct, there are quite a few considerations to make ;-) I'm rethinking even what I mean by "error out": I meant actually do nothing but exit with some message on the stderr, but that may seem like way overblown, suggesting that any and all possibly erroneous configuration to do with these mere "conventions" result in calc being unable to function... yet, I think that is still possibly very much what I would expect; from calc as well as everything else. Is that crazy? I think there's more thinking to do here.

5. Admittedly, I've barely started using calc, and my usage of it is quite likely far more mundane than that of most of its seasoned users. I am inordinately fond or how "cooperative" it is in delegating to/leveraging external tools (GNU readline) to, say, receive some input... I dared contribute some remarks more because I really enjoyed how the tool is built more than because I'd become familiar and comfortable enough with it that I'd reached its limits. I haven't had any glimpse yet of anything that would call for another variable, but I can imagine $XDG_CACHE_SOMETHING being possibly of some value?

6. Yes, that is most acceptable, I truly believe that somebody bothered enough to have their file organised in some manner wouldn't mind having these paths (perhaps even somewhat redundantly) systematically defined in their environment. I don't advocate for defaulting to the paths the XDG suggests, considering the previous statement together with the historical handling of these in calc.

[ccjmne]

Oh and yes, you're entirely correct, users can already define the various CALCPATH, CALCRC, and CALCHISTFILE to adhere to the XDG recommendation :-)
I think I should have maybe made that even clearer than I have already.

I would be happy to write something up that outlines how to set XDG Base Directory compliance for calc v2 in its README!

[lcn2]

Oh and yes, you're entirely correct, users can already define the various CALCPATH, CALCRC, and CALCHISTFILE to adhere to the XDG recommendation :-)
I think I should have maybe made that even clearer than I have already.

I would be happy to write something up that outlines how to set XDG Base Directory compliance for calc v2 in its README!

Thank you for your response, @ccjmne

Please consider an edit for the README.md file, and for a "bonus round", consider similar text for the calc.man ENVIRONMENT section of the man page. That would be helpful.

[lcn2]

In regards to GH issuecomment-3898531216, @ccjmne , we would like to get the support of XDR complete prior to calc going to version 3.0.1.0.

Please consider our request in the above comment. Based on how you document, we will modified the code base for calc v3.

[lcn2]

Thank you @ccjmnem for your recent PR #196

We will still need to modify the calcv3 branch to be "XDG" friendly by default. Perhaps the calc v3 code could first look for the XDG-related environment variables first, and if they are not found, OR if they are not valid (empty, paths do not exist, etc.) then fall back to using the older $HOME?

Please consider such a change for calcv3 by making a PR. We are currently off on other projects (while other look over the current calc v3 code base): so it may be faster / better if you make a commit for the calcv3 branch. (Just be sure your new PR is against the current calcv3 branch and not the master branch where calc v2 code current resides).

Thanks!

[lcn2]

PS: I'm not too sure how they're generated but it seems that the copyright history is missing the years. I had a quick look through their history and the only vaguely remarkable hint I came by was this curious replacement of 19xx by year in help/credit some time ago, in 9b6c308#diff-772e33e523d07c0ef8fb9912992a9bae5d74666a4c98caaae8b7d6b2d2ad99c5:

Copyright years change from time to time.

The sections you references are NOT types of copyright you will find. For example, in COPYING the text before the lines you reference reads:

    With the exception of the files listed below, Calc is covered under
    the following GNU Lesser General Public License Copyrights:

So the use of "Copyright (C) year" is a reference to whatever current years might be found in actual Copyrights.