diff --git a/README.md b/README.md index a0bc3296..89b4a304 100644 --- a/README.md +++ b/README.md @@ -3,215 +3,12 @@ Imag is a CLI PIM suite with a nice API-ish commandline interface, so you can integrate it in your tools of coice (Editor, MUA, RSS reader, etc etc). -## Modules +For detailed information, please read [the documentation](./doc/) (You can +either read the Markdown files or compile it to HTML/PDF using +[pandoc](http://pandoc.org)). -All the modules have access to a shared store (which lives in `~/.imag/store/` -by default). Files are named after a schema: - - ~/.imag/store/--.imag - -Where module name is "bookmark" for example. The hashtype is "UUID" by default -and the "hash" is a UUID then. Other types are possible as well: - -- SHA1 -- SHA512 - -for example (though it might not be a good idea to use SHA hashes, -see [Linking](#Linking)) - -Some modules might not want to store content there, for example you don't want -to put your icalendar files in there. So the calendar module just crawls through -your ical files and puts only a link and some hashsums (for refinding on content -move) to the store. Changes are not tracked via this model. -If a (for example ical-)file gets removed, the store entry gets invalid and has -to be garbage-collected. - -### Linking - -The UUID/SHA hashes in the file names can be used to connect two store entries. -For example, an entry from the wiki could refer to a contact by a UUID, because -the file for the contact has a UUID in its name. These UUIDs are constant and -should not change. - -A link chain like this - - Wiki -> Shopping List -> Calendar Entry - | | - | v - | Contact -> Calendar Entry -> Bookmark - v - Wiki Entry -> Bookmark - -is totally possible. Scenario: You have a Wiki entry of a recipe you like to -cook. The recipe is linked to a shopping list, where you want to buy the -ingredients. Of course, you want to do this on a specific date (calendar entry). -And you want to do this with your Girlfriend, so she (as a contact) is linked to -the calendar entry. Her Birthday is linked to her Contact and for her Birthday, -you saw something on amazon, so you bookmarked it and linked it to the calendar -entry. -On the other hand, the Shopping list has links to some other Wiki entry, because -it contains Kiwi, and you have notes about Kiwi, how to cook them properly. You -saw this on some website, so you linked to the website from your wiki entry, of -course. - -### Header - -So each file in the store has a certain format: - - --- -
- --- - - -The header contains some structured data (either JSON or YAML), the module uses -to store data closely related to the content. - -For example, the bookmark-module will use the header only and store URL and tags -in some JSON format. The Wiki module might use the Header for storing some meta -information about the wiki article (tags, category, maybe even links to other -store entries) and the content is the wiki article content written down by the -user. - -The content is just text entered from the user. In the best case, the module -should't touch the content at all. - -Here is a short overview what are the modules like: - -| Module | Indexer | Header-Format | Content | Expl | Dep | -| :----------- | ------- | ------------- | ------- | ------- | ----------- | -| Bibliography | X | JSON | X | .bib | Notes | -| Bookmarks | | JSON | | | | -| Calendar | X | JSON | | | | -| Contacts | X | JSON | | | | -| Image | X | JSON | | | Notes | -| Mail | X | JSON | | | | -| Movie | X | JSON | | | Notes | -| Music | X | JSON | | | Notes | -| News | X | JSON | | | | -| Notes | | YAML | X | Content | | -| Shoppinglist | | YAML | | | Notes, Todo | -| Todo | | YAML | | | Notes | -| Wiki | | YAML | X | Content | | - -Explanation: - -- An "Indexer" Module does only index some data and stores only some information - on how to content -- "Header-Format": Which format is chosen for the header. Basically: YAML if the - user might want to edit the header, otherwise JSON (pretty). -- "Content" means that the content part of a store entry is used -- "Expl": What the content part of a file is used for. "Content" means simply - user content. -- "Dep" means that the module uses this other module as a dependency for - extending its own functionality - -### External Dependencies - -| Library | Optional | Module | -| :------------ | :------: | :------- | -| vcard | | Contacts | -| icalendar | | Calendar | -| XDG | X | Contacts | -| | X | Calendar | -| | X | Notes | -| | X | Mail | -| | X | Wiki | -| | X | Todo | -| | X | Shopping List | -| | X | BibMan | -| | X | Music | -| | X | Movie | -| | X | Image | -| Markdown | | Notes | -| | | Wiki | -| Maildir | | Mail | -| BibTex parsing | X | BibMan | -| git-annex | X | BibMan | -| | X | Music | -| | X | Movie | -| | X | Image | -| Exif | X | Image | -| id3 | X | Music | -| RSS/Atom | | News | - -(Optional means that these things are optional for the main functionality, but -should be implemented at some point to offer powerful functionality) - -### Bookmarks - -Bookmarks should be stored in a simple format: - -```json -{ "URL": "https://github.com", "TAGS": ["ducks", "r", "great"]} -``` - -| Required util feature | Purpose | -| :------------------------------------ | :------------ | -| XDG-open (Browser) | External program | - -### Contacts - -Contacts are just read and indexed by `imag`, to create an internal index of -them and to be able to refer to. - -### Calendar - -Calendar are just read and indexed by `imag`, to create an internal index of -them and to be able to refer to. - -### Notes - -Just plain text notes. - -### Mail - -`imag` should be able to index all your mail and make them accessible through -its interfaces, so you can link contacts, calendar entries, wiki pages, todo -notes, etc etc. to your mail. - -Some of these things (like linking contacts, calendar entries) should be -linked automatically. - -### Personal Wiki - -`imag` should contain a complete personal wiki software. It should contain of -simple markdown files which have a YAML header, nothing too special for the -first step. - -Some more ideas: - -- Extract URLs and put them into store as Bookmarks - -### Todo-List - -`imag` should also contain a full todo-tool. I'm thinking about integrating -taskwarrior through a wrapper here. - -### Shoppinglist - -Simply dot-and-tick lists, uses Todo and Notes in combination. - -### Bibliography management - -BibTex would be the first step, maybe we should be able to add the actual PDFs -here as well... didn't waste too much thoughts on this by now. If we have the -PDF data, we need git-annex. - -### News (RSS) - -Just indexing, reading news is not task of `imag` and so isn't syncing. - -### Image - -Just indexing photos. - -### Video - -Just indexing movies. - -### Music - -Just indexing music. +_Nothing here yet. This is about to be written as soon as there is a working +base implemented._ # License diff --git a/etc/cli.yml b/etc/cli.yml deleted file mode 100644 index 1ed39342..00000000 --- a/etc/cli.yml +++ /dev/null @@ -1,508 +0,0 @@ -name: imag -version: 0.1 -author: Matthias Beyer -about: PIM-Suite for the console -args: - - verbose: - short: v - long: verbose - help: Enable verbosity - required: false - - - debug: - short: d - long: debug - help: Sets the level of debugging information - required: false - - - report: - long: report - help: Print "Ok" on success, "Error" on failure (except hard errors) before exiting, regardless of verbosity - required: false - - - rtp: - short: r - long: runtimepath - help: Set the runtime path - required: false - takes_value: true - - - editor: - short: e - long: editor - help: Set editor, if not set $EDITOR of the system will be asked, else vim - required: false - takes_value: true - - - editor_opts: - long: editor-opts - help: Set editor options - required: false - takes_value: true - - - storename: - short: s - long: storename - help: Name of the store in the runtimepath. Defaults to "store" - required: false - -subcommands: - - cal: - about: Calendar module - version: 0.1 - author: Matthias Beyer - - - cont: - about: Contact module - version: 0.1 - author: Matthias Beyer - - - mail: - about: Mail module - version: 0.1 - author: Matthias Beyer - - - wiki: - about: Wiki module - version: 0.1 - author: Matthias Beyer - - - bm: - about: Bookmark module - version: 0.1 - author: Matthias Beyer - subcommands: - - add: - about: Add bookmark - version: 0.1 - author: Matthias Beyer - args: - - url: - short: u - long: url - help: Add a new URL as bookmark - required: true - takes_value: true - - - tags: - short: t - long: tags - help: Add these tags to the URL - required: false - takes_value: true - - - list: - about: List bookmarks - version: 0.1 - author: Matthias Beyer - args: - - pretty: - long: pretty - help: Print table with ASCII-border - required: false - takes_value: false - - - match: - short: m - long: match - help: Match for regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Filter for these tags - required: false - takes_value: true - - - open: - about: Open bookmarks - version: 0.1 - author: Matthias Beyer - args: - - id: - long: id - help: Open Bookmark with ID - required: false - takes_value: true - - - match: - short: m - long: match - help: Open links matching regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Open links with these tags - required: false - takes_value: true - - - remove: - about: Remove bookmark(s) - version: 0.1 - author: Matthias Beyer - args: - - id: - long: id - help: Delete Bookmark with ID - required: false - takes_value: true - - - match: - short: m - long: match - help: Match for regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Filter for these tags - required: false - takes_value: true - - - add_tags: - about: Add tags to bookmark(s) - version: 0.1 - author: Matthias Beyer - args: - - with_id: - long: with-id - help: Add tags to bookmark with ID - required: false - takes_value: true - - - with_match: - short: m - long: with-match - help: Add tags to bookmark(s) which match this regex - required: false - takes_value: true - - - with_tags: - long: with-tags - help: Add tags to bookmark(s) which have these tag(s) - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Add these tags - required: true - takes_value: true - - - rm_tags: - about: Remove tags from bookmark(s) - version: 0.1 - author: Matthias Beyer - args: - - with_id: - long: with-id - help: Remove tags from bookmark with ID - required: false - takes_value: true - - - with_match: - short: m - long: with-match - help: Remove tags from bookmark(s) which match this regex - required: false - takes_value: true - - - with_tags: - long: with-tags - help: Remove tags from bookmark(s) which have these tag(s) - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Remove these tags - required: true - takes_value: true - - - set_tags: - about: Set tags in bookmark(s) - version: 0.1 - author: Matthias Beyer - args: - - to_id: - long: to-id - help: Set tags in bookmark with this id - required: false - takes_value: true - - - to_match: - short: m - long: to-match - help: Set tags in bookmark(s) which match this regex - required: false - takes_value: true - - - to_tags: - long: to-tags - help: Set tags in bookmark(s) which have these tag(s) - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Set these tags - required: true - takes_value: true - - - todo: - about: Todo module - version: 0.1 - author: Matthias Beyer - - - news: - about: News module - version: 0.1 - author: Matthias Beyer - - - notes: - about: Notes module - version: 0.1 - author: Matthias Beyer - subcommands: - - add: - about: Add Note - version: 0.1 - author: Matthias Beyer - args: - - name: - short: n - long: name - help: Add a name to the note - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Add these tags to the note - required: false - takes_value: true - - - edit: - about: Edit Note - version: 0.1 - author: Matthias Beyer - args: - - id: - long: id - help: Edit Note with this ID - required: false - takes_value: true - - - namegrep: - short: n - long: name - help: Edit notes where the name matches this regex - required: false - takes_value: true - - - grep: - short: g - long: grep - help: Edit notes where the content matches this regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Edit notes with these tags - required: false - takes_value: true - - - show: - about: Show note(s) - version: 0.1 - author: Matthias Beyer - args: - - plain: - long: plain - short: p - help: Show notes plain (like with 'cat') - required: false - takes_value: false - - - id: - long: id - help: Open note with this ID - required: false - takes_value: true - - - namegrep: - short: n - long: name - help: Open where name matches this regex - required: false - takes_value: true - - - grep: - short: g - long: grep - help: Open where grep with regex finds something - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Open all notes with these tags - required: false - takes_value: true - - - open: - about: Open notes as HTML page in browser (via XDG-open) - version: 0.1 - author: Matthias Beyer - args: - - onepage: - long: onepage - short: o - help: Open notes as one page - required: false - takes_value: false - - - id: - long: id - help: Open note with this ID - required: false - takes_value: true - - - namegrep: - short: n - long: name - help: Open where name matches this regex - required: false - takes_value: true - - - grep: - short: g - long: grep - help: Open where grep with regex finds something - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Open all notes with these tags - required: false - takes_value: true - - - list: - about: List notes - version: 0.1 - author: Matthias Beyer - args: - - pretty: - long: pretty - help: Print table with ASCII-border - required: false - takes_value: false - - - namegrep: - short: n - long: name - help: Filter for name which matches this regex - required: false - takes_value: true - - - grep: - short: g - long: grep - help: grep with regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Filter for these tags - required: false - takes_value: true - - - links: - about: List links in notes - version: 0.1 - author: Matthias Beyer - args: - - internal: - short: i - long: intern - help: List only links to imag content - required: false - takes_value: false - - - external: - short: e - long: extern - help: List only links to outside of imag - required: false - takes_value: false - - - id: - long: id - help: Delete Note by ID - required: false - takes_value: true - - - namegrep: - short: n - long: name - help: Filter for name which matches this regex - required: false - takes_value: true - - - grep: - short: g - long: grep - help: grep with regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Filter for these tags - required: false - takes_value: true - - - remove: - about: Remove note(s) - version: 0.1 - author: Matthias Beyer - args: - - id: - long: id - help: Delete Note by ID - required: false - takes_value: true - - - match: - short: m - long: match - help: Match for regex - required: false - takes_value: true - - - tags: - short: t - long: tags - help: Filter for these tags - required: false - takes_value: true -