|
|
@@ -0,0 +1,89 @@
|
|
|
+---
|
|
|
+title:
|
|
|
+title-meta: Dirnotes README
|
|
|
+note: run this with pandoc -T "Dirnotes README" -s README.md -t html > README.html
|
|
|
+---
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+# Dirnotes
|
|
|
+
|
|
|
+### SYNOPSIS
|
|
|
+
|
|
|
+The **dirnotes** family of apps allows you to add a descriptive comment to a file. The descriptions are stored in two places:
|
|
|
+
|
|
|
+ * in the xattr properties of the file
|
|
|
+ * in a database located in the user's home directory
|
|
|
+
|
|
|
+[The [MacOS](#macos) stores its comments in a similar way.]
|
|
|
+
|
|
|
+The <code>**dirnotes**</code> app is a GUI app, using the Qt5 framework. At startup, it displays the contents of the current directory, and the comments associated with any of the files or directories.
|
|
|
+Simple mouse clicks allow you to tunnel down into directories, or rise up the file system.
|
|
|
+You can create/edit comments and choose whether the _xattr_ or _database_ version of the comments take priority,
|
|
|
+
|
|
|
+The <code>**dirnotes-tui**</code> is a very similar app, but uses the _curses_ framework to display its activity in a terminal window. This can be handy if you have to work across a network, or if terminal apps are you preference.
|
|
|
+
|
|
|
+The <code>**dirnotes-cli**</code> is a command line tool, which may be handy for scripting.
|
|
|
+
|
|
|
+### USAGE
|
|
|
+
|
|
|
+The <code>**dirnotes**</code> program displays usage and keystoke info when you press _F1_. The <code>**dirnotes-tui**</code> program display onscreen usage when you press the 'h' key, or _F1_.
|
|
|
+The <code>**dirnotes-cli**</code> program has a man page.
|
|
|
+
|
|
|
+In short, you navigate <code>**dirnotes**</code> and <code>**dirnotes-tui**</code> by using the up/down arrow keys, <enter> to enter into a directory. The **-tui** version accepts _e_ for edit,
|
|
|
+_s_ for sort, _M_ to change between xattr/database priority.
|
|
|
+
|
|
|
+The **<code>dirnotes-cli</code>** has options for _-l_ list and _-c_ create a comment.
|
|
|
+
|
|
|
+### Direct Access
|
|
|
+
|
|
|
+Instead of an API, here is how you can get directly at the underlying comment data. If you intend to use the **dirnotes** apps, try to keep the two versions of the comments in sync.
|
|
|
+
|
|
|
+ * xattr
|
|
|
+
|
|
|
+Use the commands
|
|
|
+
|
|
|
+ xattr -l [filename]
|
|
|
+
|
|
|
+to display the comments/author/date on a file. For example:
|
|
|
+
|
|
|
+ $ xattr -l /etc/fstab
|
|
|
+ user.xdg.comment: controls the default mount bindings
|
|
|
+ user.xdg.comment.author: patb
|
|
|
+ user.xdg.comment.date: 2022-09-29 08:07:42
|
|
|
+
|
|
|
+The other options on the **xattr** command line tool allow you to write (*xattr -w*) or delete (*xattr -d*) the comments.
|
|
|
+
|
|
|
+ * database
|
|
|
+
|
|
|
+The comments are stored in an Sqlite3 database, usually located at "~/.dirnotes.db". The database itself is contained within that file, and its schema is this:
|
|
|
+
|
|
|
+~~~~
|
|
|
+ CREATE TABLE dirnotes (name TEXT, date DATETIME, size INTEGER, comment TEXT, comment_date DATETIME, author TEXT)
|
|
|
+~~~~
|
|
|
+
|
|
|
+field usage example
|
|
|
+------ ------- ---------
|
|
|
+name the long filename, using python's os.path.abspath() /home/patb/projects/dirnotes/README.md |
|
|
|
+date the file's modified date 2020-01-13 09:25:40
|
|
|
+size the byte count of the file 145
|
|
|
+comment a utf-8 string the readme for the GIT page
|
|
|
+comment_date the date of the comment itself 2020-10-03 22:30:19
|
|
|
+author the system name of the user who created the comment patb
|
|
|
+
|
|
|
+The 'date' and 'size' fields reflect the file's modification date and size at the time of the last edit of the file comment, which is also 'comment_date'.
|
|
|
+
|
|
|
+### MacOS {#macos}
|
|
|
+
|
|
|
+The **MacOS** inherently supports file comments. The Finder app manages most of the user activity. It handles file comments in a similar manner to **Dirnotes**. Comments are stored in two places:
|
|
|
+
|
|
|
+ * in the xattr properties of the file
|
|
|
+ ** using a different xattr-tag
|
|
|
+ * in a database located in each directory
|
|
|
+ ** in the .DS-Store file
|
|
|
+
|
|
|
+The user can examine the file comments by opening the GetInfo dialog, and scrolling down to "Comment"
|
|
|
+
|
|
|
+If the Finder is used to copy/move files, the comments are moved properly to both destinations. If you use the os to copy/move the files, you can ask that the xattr properties get moved, but the .DS-Store file will not be updated. That means the Finder will not see file comments on the destination file.
|
|
|
+
|
|
|
+**MacOS** has AppleScript, by which you can ask the Finder to perform the file copy/move. In this case, the comments are moved properly.
|
