fleshed out the README.md

README.md

@@ -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.

dirnotes-cli.md

@@ -76,7 +76,6 @@ Other programs can also be coerced into perserving _xattr_ properties:
 Not all file systems support xattr properties (vfat/exfat does not). 
 
 The current implementation of _sshfs_ and _scp_ do not support the copy of _xattr_ properties. 
-If you are using _sshfs_, you can use the 'dirnotes' programs to copy a file, and the database comments will work properly.
 If you want to copy files to a remote machine and include the _xattr_ comments, use _rsync_ with the _-X_ option. Or _tar_ of course.
 
 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.
@@ -94,6 +93,7 @@ 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.
 
+If you are using _sshfs_, you can use the 'dirnotes' programs to copy a file, and the database comments will work properly.
 
 # OPTIONS