|
|
@@ -1,19 +1,23 @@
|
|
|
----
|
|
|
-title:
|
|
|
-title-meta: Dirnotes README
|
|
|
-note: run this with pandoc -T "Dirnotes README" -s README.md -t html > README.html
|
|
|
----
|
|
|
-
|
|
|
+# Dirnotes
|
|
|
|
|
|
+Table of Contents
|
|
|
+----------------
|
|
|
|
|
|
-# Dirnotes
|
|
|
+ * [SYNOPSIS](#synopsis)
|
|
|
+ * [USAGE](#usage)
|
|
|
+ * [INSTALLATION](#installation)
|
|
|
+ * [CONFIG FILE](#config-file)
|
|
|
+ * [LIMITATIONS](#limitations)
|
|
|
+ * [PROGRAMMER NOTES](#programmer-notes)
|
|
|
+ * [MacOS](#macos)
|
|
|
+ * [DEVELOPMENT STATUS](#status)
|
|
|
|
|
|
-### SYNOPSIS
|
|
|
+## 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
|
|
|
+ * 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.]
|
|
|
|
|
|
@@ -25,19 +29,78 @@ The <code>**dirnotes-tui**</code> is a very similar app, but uses the _curses_ f
|
|
|
|
|
|
The <code>**dirnotes-cli**</code> is a command line tool, which may be handy for scripting.
|
|
|
|
|
|
-### USAGE
|
|
|
+## 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,
|
|
|
+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
|
|
|
+## INSTALLATION
|
|
|
+
|
|
|
+Each of the 3 apps in the family is self contained.
|
|
|
+The <code>**dirnotes**</code> app requires _Python3_ and the _Qt5_ framework.
|
|
|
+The <code>**dirnotes-tui**</code> and <code>**dirnotes-cli**</code> apps simply require _Python3_.
|
|
|
+
|
|
|
+### CONFIG FILE
|
|
|
+
|
|
|
+By default, the file **~/.dirnotes.conf** will be used to load the user's config.
|
|
|
+This is a JSON file, with three attributes that are important:
|
|
|
+
|
|
|
+> * xattr_tag (default: <code>usr.xdg.comment</code>)
|
|
|
+> * database (default: <code>~/.dirnotes.db</code>)
|
|
|
+> * start_mode (_xattr_ or _db_ priority)
|
|
|
+
|
|
|
+[_not fully implemented_]
|
|
|
+
|
|
|
+## LIMITATIONS
|
|
|
+
|
|
|
+
|
|
|
+The file comments are located in two locations: a database, and in the
|
|
|
+xattr properties of the file. Each of these storage locations has its
|
|
|
+own benefits and limitations:
|
|
|
+
|
|
|
+### xattr
|
|
|
+
|
|
|
+Comments stored in the xattr properties can be copied/moved with the file, if you
|
|
|
+use the correct options for <code>**cp**</code>. The <code>**mv**</code> utility
|
|
|
+automatically preserves _xattr_. Other programs can also be coerced into
|
|
|
+perserving _xattr_ properties:
|
|
|
+
|
|
|
+* <code>**rsync**</code>
|
|
|
+* <code>**tar**</code>
|
|
|
+* <code>**mksquashfs**</code>
|
|
|
+
|
|
|
+Not all file systems support xattr properties (vfat/exfat does not).
|
|
|
+
|
|
|
+The current implementation of <code>**sshfs**</code> and <code>**scp**</code>
|
|
|
+do not support the copy of _xattr_ properties.
|
|
|
+If you want to copy files to a remote machine and include the _xattr_ comments, use <code>**rsync**</code> with the _-X_ option. Or <code>**tar**</code>.
|
|
|
+
|
|
|
+Some editing apps (like _vim_) will create a new file when saving the data, which orphans the _xattr_ comments. For these apps, use the _database_ system.
|
|
|
|
|
|
-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.
|
|
|
+## database
|
|
|
+
|
|
|
+Comments stored in the database work for all filesystem types (including vfat/exfat/sshfs)
|
|
|
+
|
|
|
+Comments are personalized to the _current user_.
|
|
|
+Another user on the same system will not see these comments.
|
|
|
+
|
|
|
+Files are indexed by their complete path name. Removable filesystems should be
|
|
|
+mounted in a consistent way, so that the complete path name is reproducable.
|
|
|
+
|
|
|
+Comments stored in the database do not travel with the files when
|
|
|
+they are moved or copied, unless using the **dirnotes** family of tools.
|
|
|
+
|
|
|
+
|
|
|
+## PROGRAMMER NOTES
|
|
|
+
|
|
|
+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
|
|
|
|
|
|
@@ -73,20 +136,40 @@ The comments are stored in an Sqlite3 database, usually located at "~/.dirnotes.
|
|
|
|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'.
|
|
|
|
|
|
+As comments are editted or appended, new records are added to the database. Older records are are not purged. This gives you a history of the comments, but it means that fetching the most recent comment involves something like
|
|
|
+
|
|
|
+~~~~
|
|
|
+ SELECT * FROM dirnotes WHERE name=? ORDER BY comment_date DESC
|
|
|
+~~~~
|
|
|
+
|
|
|
+and just fetch the first record.
|
|
|
+
|
|
|
### 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
|
|
|
+ * in the xattr properties of the file
|
|
|
+ * using a different xattr-tag (<code>com.apple.metadata:kMDItemFinderComment</code>)
|
|
|
+ * the comment string is wrapped in a <code>pList</code>
|
|
|
+ * 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.
|
|
|
+
|
|
|
+## DEVELOPMENT STATUS{#status}
|
|
|
+
|
|
|
+Each app is a standalone file. That means there is a lot of redundancy between the tthree apps. And there _may_ be some inconsistency.
|
|
|
+
|
|
|
+2022-10-04
|
|
|
+: All three apps are functioning and usable.
|
|
|
+ The _config_file_ is fully implemented.
|
|
|
+ Themes are not implemented.
|
|
|
+ Comments are intended to be _utf-8_, but are _strings_ in some places.
|
|
|
+ MacOS code is not written yet.
|
|
|
+ The _help_ dialogs in <code>**dirnotes-tui**</code> are meagre.
|
