Begin USAGE.md, CHANGELOG.md

CHANGELOG.md

@@ -0,0 +1,22 @@
+# looqs: Release notes
+
+
+## 2022-0X-XX - v0.1
+The first release comes with basic functionality. It's a start that can be considered useful to some degree.
+
+Tested architectures: amd64.
+
+CHANGES: 
+- CLI command "looqs" to add/update/delete and search 
+- GUI: "looqs-gui" to search, render previews, and add files
+to index 
+- General: Add multi-threaded indexing of all files (paths, mtime)
+- General: sqlite based full-text search for: .txt,.pdf,.odt,.ods,.html...
+- General: Sandboxed content processing
+- GUI: Sandboxed GUI process, with privileged IPC daemon to allow launching external programs such as pdf viewers.
+- GUI: Add previews for pdf: Render the page the search keywords were found. Highlight the keywords when rendering the page. 
+- GUI: Add previews for plaintex tfiles: Extract snippets. Highlight the keywords when rendering the page. 
+- General: Add basic filters for query.
+- Add packages: Ubuntu 22.04
+
+Thanks: All who provided feedback (and endured bugs). You know who you are, thx!

USAGE.md

@@ -0,0 +1,120 @@
+# looqs - User guide
+This document is still work in progress.
+
+# General points
+Please consult the [README](README.md) for a description of what looqs is and on how to obtain it.
+
+The GUI and CLI operate on the same database, so if you add files using the CLI, the GUI will search
+them too.
+
+
+
+# Limitations
+You should be aware of the following:
+
+- Database paths are stored inefficiently, not deduplicated to
+simplify queries. This adds up quickly. Also, each PDF text is stored twice. Each page separately + the whole document to simplify queries.
+
+I currently have 167874 files in the index. A FTS index is built for 14280 of those, of which 4146 are PDF documents. The PDFs take around 10GB storage space on the filesystem. All files for which an FTS has been built are around 7GB in size on the filesystem.
+
+The looqs database has a size of 1.6 GB.
+
+
+## Config
+It's in `$HOME/.config/quitesimple.org/looqs.conf`. It will be created on first execution of the CLI or GUI
+interface.
+
+Database default path: `$HOME/.local/share/quitesimple.org/looqs/looqs.sqlite`. If this does not work for
+you, move it, but you must adjust the path in the config file.
+
+
+## GUI
+It's minimal at this point, therefore some settings must be performed by editing the config file.
+
+### First run
+You will be presented with an empty list. Go to the "Index" tab, add some directories and click "Start indexing".
+
+For large directories the progress bar is essentially just decoration. As long as you see the counters
+increase, everything is fine even if it seems the progress bar is stuck.
+
+The indexing can be stopped. If you run it again you do not start from scratch, because looqs knows
+which files have been modified or not since they have been added to the index. Thus, files will
+only be reprocedded when necessary.
+
+### Configuring PDF viewer
+It's most convenient if, when you click on a preview, the PDF reader opens the page you clicked. For that, looqs needs to know which viewer you want to launch.
+
+It tries to auto detect some common viewers. You must set the value yourself if it doesn't do something you
+like, such as not opening your favorite viewer. "%f" represents the filepath, "%p" the page number.
+
+### Preview tab
+The preview tab shows previews. It marks you search keywords too. Click on a preview to open the file.
+You can click right to copy the file path, or open the containing folder. Hovering tells you which file
+the preview originates from.
+
+## CLI
+The CLI command "looqs" has helptext provided. This documentation is incomplete at the moment.
+
+### First run
+There is no point in using the "search" command on the first run. Add some files.
+
+
+### Adding files
+To add files to the index, run ``looqs add [path]```, where 'path' can be a directory or a single file.
+If the path is a directory, the directory will be recursively descended, and all files in there added.
+
+"Skipped" implies the file has not been changed since it has been added to the index.
+
+### Searching files
+Of course the CLI will not render any previews, but it can show you the paths where search results
+have been found.
+
+```
+looqs search [terms...]
+```
+
+There is an implicit "AND" condition, meaning if you search for "photo" and "mountain", only paths
+will be shown containing both terms, but not either alone.
+
+
+
+### Deletion and Fixing Out of sync index
+You sometimes delete files, to get rid of those from the index too:
+
+```
+looqs delete --deleted --dry-run
+```
+
+This commands lists all files which are indexed, but which cannot be found anymore.
+
+Remove them using:
+```
+looqs delete --deleted --verbose
+```
+
+You can also delete by pattern:
+
+```
+looqs delete --pattern '*.java'
+```
+
+Delete never removes anything from the file system, it only operates on the database.
+
+### Updating files
+The content and metadata index for files can be updated:
+
+```
+looqs update -n
+```
+
+Those files still exist, but the content that has been indexed it out of date. This can be corrected with
+
+```
+looqs update
+```
+
+This will not add new files, you must run `looqs add` for this. For this reason, most users
+will probably seldomly use the 'update' command alone.
+
+
+