completed docs(todo: fix link in readme.md)

Author: sudormrfbin

CHANGELOG.md

@@ -4,8 +4,11 @@ CHANGELOG
 v0.7.0
 ------
 
+- [ ] Create docs
+- [ ] Add unit tests
 - [x] Batch tag files
 - [ ] Customizable keybindings
+- [ ] Refactor the whole codebase
 - [ ] Autocomplete in genre tag field
 - [x] Filename field in tag editing view
 - [ ] Short description of preferences option in status line

README.md

@@ -1,40 +1,13 @@
 # clid
 
-Clid is a command line app written in Python3 for command-line lovers to edit mp3 files' ID3 tags. This app is different from other
-command line tools to edit tags, as you can edit tags in a graphical interface.(It's like [cmus](https://github.com/cmus/cmus),
-without the player and with a tag editor)
-
-Made with a lot of help from
-
-- [npyscreen](https://bitbucket.org/npcole/npyscreen), a Python wrapper around ncurses.
-- [stagger](https://github.com/lorentey/stagger), an ID3v1/ID3v2 tag manipulation package written in pure Python 3
-- [configobj](https://github.com/DiffSK/configobj), a Python 3+ compatible port of the configobj library
-- and a laptop with 512 MB RAM(Yeah. I know.)
-
-## Changelog
-
-### v0.6.3
-
-- [x] Vi keybindings
-- [x] Added option for smooth scroll
-- [x] Preferences are now saved when updating the app
-- [x] Validators for `smooth_scroll` and `preview_format`
-- [x] Display a "What's New" Popup when app is run after an update
-
-### v0.6.2
-
-- [x] Fix: Issue #1 in Github
-- [x] Added key-binding(`u`) for reloading `music_dir`
-- [x] Fix: All option are now aligned properly in preferences view
-- [x] Added validators for preferences(Error message is shown if an error occurs)
+Clid is a command line app for editing tags of mp3 files. Clid is different from other
+command line tools to edit tags, as you can edit tags in a curses based ui.
 
+![clid main window](main.png "Main Window")
 
 ## Installation
 
-> Note: You should have Python 3 installed, not Python 2, to install and use clid.
-
-> Note: You will have to install pip manually if the Python version is < 3.4
-
+See wiki for detailed installation instructions.<!--link-->
 
 ### Using pip
 
@@ -50,53 +23,54 @@ $ cd clid
 $ [sudo] python3 setup.py install
 ```
 
-You can then launch the app by entering `clid` in the command line.
-
+### Updating
 
-## Usage
+To update the app, run
 
-### Viewing Files
+```shell
+$ [sudo] pip install -U clid
+```
 
-The main window will show the mp3 files you have in `~/Music`. The interface is similar to that of cmus:
+You can launch the app by entering `clid` in the command line.
 
-![clid main window](./img/main.png  "Main Window")
+## Usage
 
-You will have a command line at the bottom of the window, to recieve commands. You will also see a live preview of the
-common tags of the file under the cursor.
+### Quick Start
 
-> Note: The status line shows the tags in `artist - album - track_number title` format by default; you can change it in preferences
+1. Move with arrow keys or `j` and `k`.
+2. <kbd>Enter</kbd> to select a file.
+3. Edit the tags.
+4. `OK` to save the tags or `Cancel` to abort edit.
+5. Type `:q` at main window to quit.
 
-### Editing Tags
+See the [wiki](#docs/docs/index.md) for documentation and additional details.
+<!--Real link-->
 
-To edit the tags of a file, simply hit <kbd>Enter</kbd>(or <kbd>Return</kbd>). You will see a new window:
+## Changelog
 
-![clid tag edit](./img/edit.png  "Tag Editing Window")
+### v0.6.3
 
-Use the arrow keys to move through the tags; edit them if needed and hit `OK`(or <kbd>Ctrl</kbd> + <kbd>S</kbd>) when you're done. `Cancel`(<kbd>Ctrl</kbd> + <kbd>Q</kbd>) will discard changes.
+- [x] Vi keybindings
+- [x] Added option for smooth scroll
+- [x] Preferences are now saved when updating the app
+- [x] Validators for `smooth_scroll` and `preview_format`
+- [x] Display a "What's New" Popup when app is run after an update
 
+### v0.6.2
 
-### Editing Preferences
+- [x] Fix: Issue #1 in Github
+- [x] Added key-binding(`u`) for reloading `music_dir`
+- [x] Fix: All option are now aligned properly in preferences view
+- [x] Added validators for preferences(Error message is shown if an error occurs)
 
-To edit preferences, press `2`. Then hit <kbd>Enter</kbd> on the highlighted setting to edit it (it will be then shown
-at the bottom of the screen; edit it and hit <kbd>Enter</kbd> again).
+## Thanks
 
-![clid preferences](./img/pref.png "Preferences Window") 
+I couldn't have made this app without these amazing libraries...
 
-| Option | Description | Default Value|
-|--------|-------|---------|
-| `music_dir` | Directory in which the app will search for mp3 files | `~/Music` |
-| `preview_format` | Format in which a preview of the file under cursor will be shown | `%a - %l - %n. %t` |
-| `smooth_scroll` | Enable or disable smooth scroll | `true` |
-| `vim_mode` | Enable or disable Vim keybindings when editing metadata | `false` |
+- [npyscreen](https://bitbucket.org/npcole/npyscreen), a Python wrapper around ncurses.
+- [stagger](https://github.com/lorentey/stagger), an ID3v1/ID3v2 tag manipulation package written in pure Python 3
+- [configobj](https://github.com/DiffSK/configobj), a Python 3+ compatible port of the configobj library
 
-#### Supported Format Specifiers
+...And my dear laptop with 512 MB RAM ;)
 
-| Format Specifier | Expands to... |
-|:----------------:|:-------------:|
-| %t | Title |
-| %a | Artist |
-| %l | Album |
-| %n | Track Number |
-| %c | Comment |
-| %A | Album Artist |
-| %y | Date |
+Enjoy!

clid/base.py

@@ -14,14 +14,9 @@ class ClidActionController(npy.ActionControllerSimple):
     """Base class for the command line at the bottom of the screen"""
 
     def create(self):
-        self.add_action('^:q$', self.exit_app, live=False)   # quit with ':q'
+        self.add_action('^:q$', lambda *args, **kwargs: exit(), live=False)   # quit with ':q'
         self.add_action('^:set .+', self.change_setting, live=False)
 
-
-    def exit_app(self, command_line, widget_proxy, live):
-        """Exit the app with ':q'"""
-        exit()   # args are used internally by npyscreen
-
     def change_setting(self, command_line, widget_proxy, live):
         """Change a setting in the ini file"""
         pass   # different for main and pref view; defined in respective files

clid/main.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-__version__ = '0.6.3'
+__version__ = '0.7.0'
 
 import os
 import curses
@@ -32,7 +32,6 @@ def change_setting(self, command_line, widget_proxy, live):
         setting = command_line[5:].split(sep='=')
         pref_form = self.parent.parentApp.getForm("SETTINGS")
         pref_form.value.change_setting(setting[0], setting[1])   # writes to the ini file
-        pref_form.value.when_changed[setting[0]]()
 
         pref_form.load_pref()
         pref_form.wMain.display()
@@ -119,6 +118,7 @@ def h_cursor_page_up(self, char):
     @special_handler
     def h_cursor_page_down(self, char):
         super().h_cursor_page_down(char)
+        self.parent._resize()
 
     @special_handler
     def h_cursor_line_up(self, char):
@@ -268,6 +268,7 @@ class ClidApp(npy.NPSAppManaged):
             settings(configobj.ConfigObj):
                 object used to read and write preferences
     """
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.current_files = []   # changed when a file is selected in main screen

docs/docs/batch_tag_edit.png

@@ -1,7 +1,7 @@
 # clid
 
-Clid is an app for those whose home is the terminal and can't live without a well organized music collection :)
-With clid, you can edit the metadata(tags) of mp3 files, right from the terminal. Awesome ? Let's get started !
+Clid is an app for editing metadata(tags) of mp3 files without leaving the coziness of the terminal ;)
+Clid differs from other command line tools to edit tags, as it provides a curses based ui.
 
 ## Installation
 
@@ -29,50 +29,71 @@ $ cd clid
 $ [sudo] python3 setup.py install
 ```
 
+### Updating
+
+To update the app, run
+
+```shell
+$ [sudo] pip install -U clid
+```
+
 ## Launching The App
 
-Enter `clid` in the command line to start the app:
+Type `clid` in the command line to start the app(and `:q` in the main window to quit):
 
 ![clid main window](main.png "Main Window")
 
-What do ya think, eh ?
-
 ## Quick Start
 
-The basics are simple:
 1. Move with arrow keys or `j` and `k`.
 2. <kbd>Enter</kbd> to select a file.
 3. Edit the tags.
 4. `OK` to save the tags or `Cancel` to abort edit.
+5. Type `:q` at main window to quit.
 
 ## Main Window
 
 Main window has 3 parts:
 
 ![clid main annnotated](main_annotated.png)
 
-<!--link-->
-1. File viewer, showing files in `~/Music` by default,
-2. Status line , showing live preview of tags of file under cursor,
-3. Command line, which accepts commands.
-
+1. [File viewer](#file-viewer), showing files in `~/Music` by default,
+2. [Status line](#status-line), showing live preview of tags of file under cursor,
+3. [Command line](#command-line), which accepts commands.
 
 ### File Viewer
 
-You can see the mp3 files in the selected directory<!--link--> in the main window. You can use <kbd>UpArrow</kbd>,
-<kbd>DownArrow</kbd>, <kbd>j</kbd>, <kbd>k</kbd>, <kbd>Home</kbd>, <kbd>PageUp</kbd>, etc to move around.
-Hit <kbd>Enter</kbd> when you've found the file you want to edit, or batch tag files<!--link-->. You can also search
-for files<!--link-->.
+You can see the mp3 files in the [selected directory](#list-of-available-options) in the main window.
+Files are read every time the app is started. You can use <kbd>UpArrow</kbd>, <kbd>DownArrow</kbd>,
+<kbd>j</kbd>, <kbd>k</kbd>, <kbd>Home</kbd>, <kbd>PageUp</kbd>, etc to move around. Hit <kbd>Enter</kbd>
+when you've found the file you want to edit, or [batch tag files](#tagging-multiple-files-at-once).
+You can also [search for files](#searching-for-files).
+
+#### Searching For Files
+
+You can search for files by pressing <kbd>/</kbd>. Note that this is only a basic search - it doesn't search the tags
+of every file, only the filename is checked.
+
+1. Press <kbd>/</kbd>.
+2. Enter the search term. Results are shown as you type.
+3. Press <kbd>Enter</kbd> to terminate search and navigate search results.
+4. Press <kbd>Esc</kbd> to return to normal view.
+
+Your selections for batch tagginf(if any) are kept intact when searching.
+[See a note](#esc-key) on the <kbd>Esc</kbd> key.
 
 ### Status Line
 
-The status line shows a live preview of metadata of file under cursor in the specified format<!--link-->.
-The default format is `artist - album - track_number title`.
+![tag preview](tag_preview_default.png)
+
+The status line shows a live preview of metadata of file under cursor in the
+[specified format](#customizing-tag-preview-format). The default format is
+`artist - album - track_number title`.
 
 ### Command Line
 
-You can execute commands and perform searches from here. Press `:` to enter commands<!--link--> and
-`/` to search<!--link--> for files
+You can execute commands and perform searches from here. Press `:` to enter [commands](#available-commands)
+and `/` to [search for files](#searching-for-files).
 
 ## Editing Tags
 
@@ -91,16 +112,102 @@ saving tags is <kbd>Ctrl</kbd> + <kbd>S</kbd> and canceling is <kbd>Ctrl</kbd> +
 You can batch tag files in clid:
 
 1. Select and deselect files with <kbd>Space</kbd> and press <kbd>Enter</kbd> to edit the files. *Note that 
-pressing <kbd>Enter</kbd> will also add the file currently under the cursor to list of files that will be edited*.
+pressing <kbd>Enter</kbd> will also add the file currently under the cursor to list of files that will be edited*. You can also search for files and then add them to the list of files to be edited.
+
+> Note: Press <kbd>Esc</kbd> to discard selections. [See a note](#esc-key) on the <kbd>Esc</kbd> key.
+
+![clid batch tag selecting](batch_tag_main.png)
 
 2. You will see a window with blank tag fields. Only the tag fields which you modify here will be saved to the
 files, that is, if this is what you have,
 
 ![clid batch tagging](batch_tag_edit.png)
 
-then 
+then since Album and Artist are the only fields with text, only those will be written to the selected mp3 files.
 
 3. You can save or cancel as mentioned above.
 
+## Editing Preferences
+
+> Config file is located at `~/.config/clid/clid.ini`.
+
+You can edit preferences by pressing <kbd>2</kbd>.
+
+1. Select the option you want to edit and press <kbd>Enter</kbd>.
+2. There will be a prompt in the command line; edit the option and press <kbd>Enter</kbd>.
+3. If you gave an invalid value, an error message will be shown.
+
+### List Of Available Options
+
+| Option | Description | Default Value | Acceptable Values |
+|:--------:|-------|:---------:|----------|
+| `music_dir` | Directory in which the app will search for mp3 files recursively | `~/Music` | Any valid path
+| `preview_format` | Format in which a preview of the file under cursor will be shown | `%a - %l - %n. %t` | See [list of valid format specifiers](#customizing-tag-preview-format)
+| `smooth_scroll` | Enable or disable smooth scroll | `true` | `true` / `false`
+| `vim_mode` | Enable or disable Vim style keybindings | `false` | `true` / `false`
+
+#### Vim Mode
+
+Vim style keybindings can be enabled, which currently supports basic stuff like adding, inserting and deleting text.
+[See a note](#esc-key) on the <kbd>Esc</kbd> key.
+
+#### Customizing Tag Preview Format
+
+The preview format can be edited using format specifiers:
+
+| Format Specifier | Expands to... |
+|:----------------:|:-------------:|
+| %t | Title |
+| %a | Artist |
+| %l | Album |
+| %n | Track Number |
+| %c | Comment |
+| %A | Album Artist |
+| %y | Date |
+
+Example: `%a - %l [%n] %t (%y)` expands to `Artist - Album [Track Number] Title (Date)`
+
+## Default Keybindings
+
+| Action | Key | Context |
+|:------|:---:|:-------|
+| Move Up | `k`, `UpArrow` | Preferences / Main View |
+| Move Down | 'j', `DownArrow` | Preferences / Main View |
+| Select file for editing / select option to be edited | `Enter`, `x` | Preferences / Main View |
+| Switch to Main View | `1` | Preferences |
+| Select files | `Space` | Main View |
+| Switch to Preferences | `2` | Main View |
+| Reload mp3 files in current directory | `u` | Main View |
+| Discard selection | `Esc` | Main View(after selecting for batch tagging) |
+| Discard search results and show all files | `Esc` | Main View(after searching) |
+| Save changes | `Ctrl + S` | Meta Editing Window |
+| Discard changes | `Ctrl + Q` | Meta Editing Window |
+
+## Available Commands
+
+Press `:` to start entering commands
+
+`set <option name>=<value>`  
+    Set the option(from preferences) to value
+
+`q`  
+    Quit the app
+
+## Miscellaneous
+
+### Esc Key
+
+The `Esc` key is a bit sluggish. It seems to be a problem with one of the dependencies.
+When `vim_mode` is enabled, pressing `Esc` after editing text to enter Normal mode
+will take some time(just a bit).
+
+Discarding search results and selection are both bound to the `Esc`. When `Esc` is pressed
+in Main View, clid first checks if there are any search results being displayed. If there are
+any, that is cleared *first* and no further actions are taken. If there are no search results,
+*then* file selections are discarded. This ensures that you can search for files, add them
+to file selection list, and return to Main View with the selection list intact.
 
+### What's New
 
+When clid is updated a "What's New" window is shown. Contents of `~/.config/clid/NEW` are
+shown in it.