Update, reorder, align help and examples.

README.md

@@ -21,10 +21,10 @@
 - [Features](#features)
 - [Installation](#installation)
   - [Dependencies](#dependencies)
+  - [Installing with a package manager](#installing-with-a-package-manager)
   - [Installing from this repository](#installing-from-this-repository)
     - [Running as a standalone utility](#running-as-a-standalone-utility)
     - [Debian package](#debian-package)
-  - [Installing with a package manager](#installing-with-a-package-manager)
 - [Shell completion](#shell-completion)
 - [Usage](#usage)
   - [Cmdline options](#cmdline-options)
@@ -83,19 +83,26 @@ There are several [projects](#related-projects) based on `buku`, including a bro
 | Import browser exported html | beautifulsoup4 |
 | Shorten URL, check latest release | requests |
 
-To install package dependencies, run:
+To install package dependencies using pip3, run:
 
     $ sudo pip3 install urllib3 cryptography beautifulsoup4 requests
 or on Ubuntu:
 
     $ sudo apt-get install python3-urllib3 python3-cryptography python3-bs4 python3-requests
 
+### Installing with a package manager
+
+- [PyPi](https://pypi.python.org/pypi/buku/) (`$ pip3 install buku`)
+- [AUR](https://aur.archlinux.org/packages/buku/)
+- [Homebrew](http://braumeister.org/formula/buku)
+- [Debian](https://packages.debian.org/search?keywords=buku&searchon=names&exact=1)
+- [Ubuntu](http://packages.ubuntu.com/search?keywords=buku&searchon=names&exact=1)
+- [Ubuntu PPA](https://launchpad.net/~twodopeshaggy/+archive/ubuntu/jarun/)
+- [Void Linux](https://github.com/voidlinux/void-packages/tree/master/srcpkgs/buku) (`$ sudo xbps-install -S buku`)
+
 ### Installing from this repository
 
-If you have git installed, run:
+If you have git installed, clone this repository. Otherwise download the latest [stable release](https://github.com/jarun/Buku/releases/latest) or [development version](https://github.com/jarun/Buku/archive/master.zip) (*risky*).
-
-    $ git clone https://github.com/jarun/Buku/
-or download the latest [stable release](https://github.com/jarun/Buku/releases/latest) or [development version](https://github.com/jarun/Buku/archive/master.zip) (*risky*).
 
 Install to default location (`/usr/local`):
 
@@ -121,16 +128,6 @@ If you are on a Debian (including Ubuntu) based system visit [the latest stable
 
 Please substitute `$version` with the appropriate package version.
 
-### Installing with a package manager
-
-- [PyPi](https://pypi.python.org/pypi/buku/) (`$ pip install buku`)
-- [AUR](https://aur.archlinux.org/packages/buku/)
-- [Homebrew](http://braumeister.org/formula/buku)
-- [Debian](https://packages.debian.org/search?keywords=buku&searchon=names&exact=1)
-- [Ubuntu](http://packages.ubuntu.com/search?keywords=buku&searchon=names&exact=1)
-- [Ubuntu PPA](https://launchpad.net/~twodopeshaggy/+archive/ubuntu/jarun/)
-- [Void Linux](https://github.com/voidlinux/void-packages/tree/master/srcpkgs/buku) (`$ sudo xbps-install -S buku`)
-
 ## Shell completion
 
 Shell completion scripts for Bash, Fish and Zsh can be found in respective subdirectories of [auto-completion/](https://github.com/jarun/Buku/blob/master/auto-completion). Please refer to your shell's manual for installation instructions.
@@ -174,7 +171,7 @@ EDIT OPTIONS:
                            '+' appends to, '-' removes from tagset
       --title [...]        bookmark title; if no arguments:
                            -a: do not set title, -u: clear title
-      -c, --comment [...]  description of the bookmark
+      -c, --comment [...]  notes or description of the bookmark
                            clears description, if no arguments
       --immutable N        disable title fetch from web on update
                            N=0: mutable (default), N=1: immutable
@@ -210,15 +207,14 @@ POWER TOYS:
                            -1 shows the bookmark with highest index
       -f, --format N       limit fields in -p or Json search output
                            N=1: URL, N=2: URL and tag, N=3: title
-      --replace oldtag [newtag ...]
-                           replace oldtag with newtag everywhere
-                           delete oldtag, if newtag not specified
       -j, --json           Json formatted output for -p and search
       --nc                 disable color output
       --np                 do not show the prompt, run and exit
       -o, --open [...]     browse bookmarks by indices and ranges
                            open a random bookmark, if no arguments
       --oa                 browse all search results immediately
+      --replace old new    replace old tag with new tag everywhere
+                           delete old tag, if new tag not specified
       --shorten index|URL  fetch shortened url from tny.im service
       --expand index|URL   expand a tny.im shortened url
       --tacit              reduce verbosity
@@ -319,7 +315,7 @@ and check the entry.
 - If you want to tag these bookmarks, look them up later using:
 
         $ buku -S blank
-Use option `-u` to tag these bookmarks.
+  Use option `-u` to tag these bookmarks.
 
 ### Import bookmarks to browser
 
@@ -361,12 +357,11 @@ NOTE: This flexibility is not exposed in the program.
 
 ## Examples
 
-
 1. **Edit and add** a bookmark from editor:
 
         $ buku -w
         $ buku -w 'macvim -f' -a https://ddg.gg search engine, privacy
-The first command picks editor from the environment variable `EDITOR`. The second command will open macvim with option -f and the URL and tags populated in template.
+    The first command picks editor from the environment variable `EDITOR`. The second command will open macvim with option -f and the URL and tags populated in template.
 2. **Add** a bookmark with **tags** `search engine` and `privacy`, **comment** `Search engine with perks`, **fetch page title** from the web:
 
         $ buku -a https://ddg.gg search engine, privacy -c Search engine with perks
@@ -374,21 +369,21 @@ The first command picks editor from the environment variable `EDITOR`. The secon
         > DuckDuckGo
         + Alternative search engine with perks
         # privacy,search engine
-where, >: title, +: comment, #: tags
+    where, >: title, +: comment, #: tags
 3. **Add** a bookmark with tags `search engine` & `privacy` and **immutable custom title** `DDG`:
 
         $ buku -a https://ddg.gg search engine, privacy --title 'DDG' --immutable 1
         336. https://ddg.gg (L)
         > DDG
         # privacy,search engine
-Note that URL must precede tags.
+    Note that URL must precede tags.
 4. **Add** a bookmark **without a title** (works for update too):
 
         $ buku -a https://ddg.gg search engine, privacy --title
 5. **Edit and update** a bookmark from editor:
 
         $ buku -w 15012014
-This will open the existing bookmark's details in the editor for modifications. Environment variable `EDITOR` must be set.
+    This will open the existing bookmark's details in the editor for modifications. Environment variable `EDITOR` must be set.
 6. **Update** existing bookmark at index 15012014 with new URL, tags and comments, fetch title from the web:
 
         $ buku -u 15012014 --url http://ddg.gg/ --tag web search, utilities -c Private search engine
@@ -398,12 +393,12 @@ This will open the existing bookmark's details in the editor for modifications.
 8. **Update only comment** for bookmark at 15012014:
 
         $ buku -u 15012014 -c this is a new comment
-Applies to --url, --title and --tag too.
+    Applies to --url, --title and --tag too.
 9. **Export** bookmarks tagged `tag 1` or `tag 2` to HTML and markdown:
 
         $ buku -e bookmarks.html --tag tag 1, tag 2
         $ buku -e bookmarks.md --tag tag 1, tag 2
-All bookmarks are exported if --tag is not specified.
+    All bookmarks are exported if --tag is not specified.
 10. **Import** bookmarks from HTML and markdown:
 
         $ buku -i bookmarks.html
@@ -411,17 +406,17 @@ All bookmarks are exported if --tag is not specified.
 11. **Delete only comment** for bookmark at 15012014:
 
         $ buku -u 15012014 -c
-Applies to --title and --tag too. URL cannot be deleted without deleting the bookmark.
+    Applies to --title and --tag too. URL cannot be deleted without deleting the bookmark.
 12. **Update** or refresh **full DB** with page titles from the web:
 
         $ buku -u
         $ buku -u --tacit (show only failures and exceptions)
-This operation does not modify the indexes, URLs, tags or comments. Only title is refreshed if fetched title is non-empty.
+    This operation does not modify the indexes, URLs, tags or comments. Only title is refreshed if fetched title is non-empty.
 13. **Delete** bookmark at index 15012014:
 
         $ buku -d 15012014
         Index 15012020 moved to 15012014
-The last index is moved to the deleted index to keep the DB compact.
+    The last index is moved to the deleted index to keep the DB compact.
 14. **Delete all** bookmarks:
 
         $ buku -d
@@ -444,7 +439,7 @@ The last index is moved to the deleted index to keep the DB compact.
         $ buku --stag
 20. Run a **search and update** the results:
 
-        $ buku -s kernel debugging -u --tag + newtag
+        $ buku -s kernel debugging -u --tag + linux kernel
 21. Run a **search and delete** the results:
 
         $ buku -s kernel debugging -d
@@ -452,7 +447,7 @@ The last index is moved to the deleted index to keep the DB compact.
 
         $ buku -l 15
         $ buku -k 15
-The same number of iterations must be specified for one lock & unlock instance. Default is 8, if omitted.
+    The same number of iterations must be specified for one lock & unlock instance. Default is 8, if omitted.
 23. **Show details** of bookmarks at index 15012014 and ranges 20-30, 40-50:
 
         $ buku -p 20-30 15012014 40-50
@@ -462,7 +457,7 @@ The same number of iterations must be specified for one lock & unlock instance.
         $ buku -p | more
 25. **Replace tag** 'old tag' with 'new tag':
 
-        $ buku --replace 'old tag' new tag
+        $ buku --replace 'old tag' 'new tag'
 26. **Delete tag** 'old tag' from DB:
 
         $ buku --replace 'old tag'

buku.1

@@ -115,7 +115,7 @@ Specify comma separated tags, works with --add, --update. Clears the tags, if no
 Manually specify the title, works with --add, --update. Omits or clears the title, if no arguments passed.
 .TP
 .BI \-c " " \--comment " [...]"
-Add comment or description on the bookmark, works with --add, --update. Clears the comment, if no arguments passed.
+Add notes or description of the bookmark, works with --add, --update. Clears the comment, if no arguments passed.
 .TP
 .BI \--immutable " N"
 Set the title of a bookmark immutable during updates. Works with --add, --update. N=1 sets the immutable flag, N=0 removes it. If omitted, bookmarks are added with N=0.
@@ -188,17 +188,6 @@ Show selective monochrome output with specific fields. Works with --print. Searc
 .I N
 = 3, show only title.
 .TP
-.BI \--replace " oldtag [newtag ...]"
-Replace
-.I oldtag
-with
-.I newtag
-if both are passed; delete
-.I oldtag
-if
-.I newtag
-is omitted.
-.TP
 .BI \-j " " \--json
 Output data formatted as json, works with --print output and search results.
 .TP
@@ -214,6 +203,17 @@ Open bookmarks by DB indices or ranges in browser. Open a random index if argume
 .BI \--oa
 Open all search results immediately in the browser. Works best with --np. When used along with --update or --delete, URLs are opened in the browser first and then modified or deleted.
 .TP
+.BI \--replace " old new"
+Replace
+.I old
+tag with
+.I new
+tag if both are passed; delete
+.I old
+tag if
+.I new
+tag is not specified.
+.TP
 .BI \--shorten " index|URL"
 Shorten the URL at DB
 .I index
@@ -264,7 +264,7 @@ Run a regular expression search.
 .BI "t" " [...]"
 Search bookmarks by a tag. List all tags alphabetically, if no arguments. The index of a tag from the tag list can be used to search all bookmarks having the tag. Note that multiple indices and/or ranges do not work in this case.
 .TP
-.BI "w" " [index|editor]"
+.BI "w" " [editor|index]"
 Edit and add or update a bookmark.
 .TP
 .BI "?"
@@ -489,7 +489,7 @@ Run a \fBsearch and update\fR the results:
 .PP
 .EX
 .IP
-.B buku -s kernel debugging -u --tag + newtag
+.B buku -s kernel debugging -u --tag + linux kernel
 .EE
 .PP
 .IP 21. 4
@@ -535,7 +535,7 @@ The same number of iterations must be specified for one lock & unlock instance.
 .PP
 .EX
 .IP
-.B buku --replace 'old tag' new tag
+.B buku --replace 'old tag' 'new tag'
 .EE
 .PP
 .IP 26. 4

buku.py

@@ -1636,7 +1636,7 @@ keys:
   d                    match substrings ('pen' matches 'opened')
   r expression         run a regex search
   t [...]              search bookmarks by a tag or show tag list
-  w [index|editor]     edit and add or update a bookmark
+  w [editor|index]     edit and add or update a bookmark
                        (tag list index fetches bookmarks by tag)
   ?                    show this help
   q, ^D, double Enter  exit buku
@@ -2570,7 +2570,7 @@ POSITIONAL ARGUMENTS:
                          '+' appends to, '-' removes from tagset
     --title [...]        bookmark title; if no arguments:
                          -a: do not set title, -u: clear title
-    -c, --comment [...]  description of the bookmark
+    -c, --comment [...]  notes or description of the bookmark
                          clears description, if no arguments
     --immutable N        disable title fetch from web on update
                          N=0: mutable (default), N=1: immutable''')
@@ -2636,15 +2636,14 @@ POSITIONAL ARGUMENTS:
                          -1 shows the bookmark with highest index
     -f, --format N       limit fields in -p or Json search output
                          N=1: URL, N=2: URL and tag, N=3: title
-    --replace oldtag [newtag ...]
-                         replace oldtag with newtag everywhere
-                         delete oldtag, if newtag not specified
     -j, --json           Json formatted output for -p and search
     --nc                 disable color output
     --np                 do not show the prompt, run and exit
     -o, --open [...]     browse bookmarks by indices and ranges
                          open a random bookmark, if no arguments
     --oa                 browse all search results immediately
+    --replace old new    replace old tag with new tag everywhere
+                         delete old tag, if new tag not specified
     --shorten index|URL  fetch shortened url from tny.im service
     --expand index|URL   expand a tny.im shortened url
     --tacit              reduce verbosity
@@ -2658,12 +2657,12 @@ POSITIONAL ARGUMENTS:
     addarg('-m', '--merge', nargs=1, help=HIDE)
     addarg('-p', '--print', nargs='*', help=HIDE)
     addarg('-f', '--format', type=int, default=0, choices={1, 2, 3}, help=HIDE)
-    addarg('--replace', nargs='+', help=HIDE)
     addarg('-j', '--json', action='store_true', help=HIDE)
     addarg('--nc', action='store_true', help=HIDE)
     addarg('--np', action='store_true', help=HIDE)
     addarg('-o', '--open', nargs='*', help=HIDE)
     addarg('--oa', action='store_true', help=HIDE)
+    addarg('--replace', nargs='+', help=HIDE)
     addarg('--shorten', nargs=1, help=HIDE)
     addarg('--expand', nargs=1, help=HIDE)
     addarg('--tacit', action='store_true', help=HIDE)