TO REBASE CHANGELOG.md, USAGE.md
This commit is contained in:
parent
4aef3c42c2
commit
82cb6f76fa
@ -1,9 +1,10 @@
|
||||
# looqs: Release notes
|
||||
|
||||
|
||||
## 2022-0X-XX - v0.1
|
||||
## 2022-06-XX - v0.1
|
||||
The first release comes with basic functionality. It's a start that can be considered useful to some degree.
|
||||
|
||||
looqs is still at an early stage and may exhibit some weirdness and contain bugs.
|
||||
|
||||
Tested architectures: amd64.
|
||||
|
||||
CHANGES:
|
||||
@ -12,10 +13,10 @@ CHANGES:
|
||||
- General: Add multi-threaded indexing of all files (paths, mtime)
|
||||
- General: Generate sqlite based full-text search index for: .pdf,.odt,.ods, text files
|
||||
- General: Sandboxed content processing
|
||||
- GUI: Sandboxied IPC sub-process to render previews.
|
||||
- GUI: Sandboxed IPC sub-process to render previews.
|
||||
- GUI: Add previews for pdf: Render the page the search keywords were found. Highlight the keywords when rendering the page.
|
||||
- GUI: Add previews for plaintext files: Extract snippets. Highlight the keywords when rendering the page.
|
||||
- General: Add basic filters for query.
|
||||
- Add packages: Ubuntu 22.04
|
||||
|
||||
Thanks: All those who provided feedback (and endured bugs) at various stages. You know who you are, thx!
|
||||
Thanks to all those who provided feedback (and endured bugs) at various stages. You know who you are, thx!
|
||||
|
||||
59
USAGE.md
59
USAGE.md
@ -1,25 +1,26 @@
|
||||
# looqs - User guide
|
||||
This document is still work in progress.
|
||||
|
||||
# General points
|
||||
## General points
|
||||
Please consult the [README](README.md) for a description of what looqs is and on how to obtain it.
|
||||
|
||||
# Current Limitations and things to know
|
||||
looqs is still at an early stage and may exhibit some weirdness and contain bugs.
|
||||
|
||||
## Current Limitations and things to know
|
||||
You should be aware of the following:
|
||||
|
||||
- It may seem naturally, but the GUI and CLI operate on the same database, so if you add files using the CLI, the GUI will search them too.
|
||||
- It may seem natural, but the GUI and CLI operate on the same database, so if you add files using the CLI, the GUI will search them too.
|
||||
|
||||
- If a file is listed in the "Search results" tab, it does not imply that a preview will be available in the "Previews" tab, as looqs can search more file formats than it can generate previews for currently.
|
||||
|
||||
- Database paths are stored inefficiently, not deduplicated to simplify queries. This may add up quickly. Also, each PDF text is stored twice. Each page separately + the whole document to simplify queries.
|
||||
|
||||
At the time this section was written, 167874 files were in my index. A FTS index was built for 14280 of those, of which 4146 were 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.
|
||||
To give you some idea: At the time this section was written, 167874 files were in my index. A FTS index was built for 14280 of those, of which 4146 were 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 had a size of 1.6 GB.
|
||||
|
||||
- Existing files are considered modified when the mtime has changed. looqs currently does not check whether the content
|
||||
has changed.
|
||||
|
||||
## Config
|
||||
It's in `$HOME/.config/quitesimple.org/looqs.conf`. It will be created on first execution of the CLI or GUI
|
||||
The config file is in `$HOME/.config/quitesimple.org/looqs.conf`. It will be created on first execution of the CLI or GUI
|
||||
interface. The GUI has a menu entry to quickly open this config file. This is to be considered temporary and will be removed once the GUI itself can edit all settings.
|
||||
|
||||
Database default path: `$HOME/.local/share/quitesimple.org/looqs/looqs.sqlite`. If this does not work for
|
||||
@ -27,26 +28,26 @@ you, move it and adjust 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.
|
||||
The GUI is minimal at this point. Depending on what you want to do, you may need to open the config file and change the settings there. Chances are that you may not need to do that.
|
||||
|
||||
### First run
|
||||
You will be presented with an empty list. Go to the "Index" tab, add some directories and click "Start indexing".
|
||||
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.
|
||||
only be reprocedded when necessary. Note that cancellation itself may take a moment as files finish processing.
|
||||
|
||||
### Search
|
||||
The text field at the top is where you type your query. It can be selected quickly using CTRL + L. Filters are avalable,
|
||||
see the document below. By default, both the full path and the content are searched. Path names take precedence.
|
||||
The text field at the top is where you type your query. It can be selected quickly using **CTRL + L**. Filters are avalable,
|
||||
see this document at the end. By default, both the full path and the content are searched. Path names take precedence.
|
||||
|
||||
### 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 of the ' pdfviewer=' config entry yourself if it doesn't do something you
|
||||
It tries to auto detect some common viewers. You must set the value of the ```pdfviewer=``` config entry yourself if it doesn't do something you
|
||||
like, such as not opening your favorite viewer. In the command line options, "%f" represents the filepath, "%p" the page number.
|
||||
|
||||
### Preview tab
|
||||
@ -54,8 +55,7 @@ The preview tab shows previews. It marks your search keywords too. Click on a pr
|
||||
A right click on a preview allows you to copy the file path, or to open the containing folder. Hovering tells you which file the preview originates from.
|
||||
|
||||
### Syncing index
|
||||
Over time, files get deleted or their content changes. Go to 'looqs' -> 'Sync index'. looqs will reindex the content of files which have been changed.
|
||||
Files that cannot be found anymore will be removed from the index.
|
||||
Over time, files get deleted or their content changes. Go to **looqs** -> **Sync index**. looqs will reindex the content of files which have been changed. Files that cannot be found anymore will be removed from the index.
|
||||
|
||||
Reindexing a path using the "Index" tab will index new files and update existing ones. Currently however, this does not deal with deleted files.
|
||||
|
||||
@ -68,7 +68,7 @@ The CLI command "looqs" comes with helptext. This documentation is incomplete at
|
||||
There is no point in using the "search" command on the first run. Add some files if not done so already.
|
||||
|
||||
### Adding files
|
||||
To add files to the index, run ``looqs add [path]```, where 'path' can be a directory or a single file.
|
||||
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. If it has changed, the index content will be updated.
|
||||
@ -106,7 +106,7 @@ looqs delete --pattern '*.java'
|
||||
|
||||
Delete never removes anything from the file system, it only operates on the database.
|
||||
|
||||
The equivalent of the GUI sync command is probably something like:
|
||||
The equivalent of the GUI sync command is:
|
||||
```
|
||||
looks update -v --continue --delete
|
||||
```
|
||||
@ -125,7 +125,7 @@ Those files still exist, but the content that has been indexed it out of date. T
|
||||
looqs update
|
||||
```
|
||||
|
||||
This will not add new files, you must run `looqs add` for this. For this reason, most users
|
||||
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.
|
||||
|
||||
|
||||
@ -149,24 +149,25 @@ So typing "lh recipes" searchs the current dir and its subdirs for a file contai
|
||||
## Query syntax / Search filters
|
||||
A number of search filters are available.
|
||||
|
||||
The most important ones are:
|
||||
- path.contains:(term), short: p:(term) - Pretty much a SQL LIKE '%term%' conditions, just searches the path string
|
||||
- path.ends:(term), short: pe:(term) - Filters path ending with the specified term, e. g.: pe:(.ogg)
|
||||
- path.begins:(term), short: pb:(term) - Filters path beginning with the specified term.
|
||||
- contains:(terms), short: c:(terms) - Full-text search, also understands quotes.
|
||||
| Filter (long) | Filter (short) | Explanation |
|
||||
| ----------- | ----------- |----------- |
|
||||
| path.contains:(term) | p:(term) | Pretty much a SQL LIKE '%term%' conditions, just searches the path string |
|
||||
| path.ends:(term) | pe:(term) | Filters path ending with the specified term, e. g.: pe:(.ogg) |
|
||||
| path.begins:(term) | pb:(term) | Filters path beginning with the specified term |
|
||||
| contains:(terms) | c:(terms) | ull-text search, also understands quotes |
|
||||
|
||||
Filters can be combined. The booleans AND and OR are supported. Negations can be applied too, except for c:().
|
||||
The AND boolean is implicit and thus entering it strictly optional.
|
||||
|
||||
Examples:
|
||||
|
||||
pe:(.ogg) p:(marley) - Finds files that end with .ogg and contain 'marley'. May be a reasonable attempt to find songs by Bob Marley in your musics collection.
|
||||
p:(slides) support vector machine - Performs a content search for 'support vector machine' in all paths containing 'slides'
|
||||
p:(notes) (pe:(odt) OR pe:(docx)) - Finds files such as notes.docx, notes.odt but also any .docs and .odt when the path contains the string 'notes'.
|
||||
|
||||
memcpy !(pe:(.c) OR pe:(.cpp))- Performs a FTS search for 'memcpy' but excludes .cpp and .c files.
|
||||
|
||||
c:("I think, therefore") - Performs a FTS search for the phrase "I think, therefore".
|
||||
| Query | Explanation |
|
||||
| ----------- | ----------- |
|
||||
|pe:(.ogg) p:(marley)| Finds paths that end with .ogg and contain 'marley' (case-insensitive)
|
||||
|p:(slides) support vector machine |Performs a content search for 'support vector machine' in all paths containing 'slides'|
|
||||
|p:(notes) (pe:(odt) OR pe:(docx)) |Finds files such as notes.docx, notes.odt but also any .docs and .odt when the path contains the string 'notes'|
|
||||
|memcpy !(pe:(.c) OR pe:(.cpp))| Performs a FTS search for 'memcpy' but excludes .cpp and .c files.
|
||||
|c:("I think, therefore")|Performs a FTS search for the phrase "I think, therefore".
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user