Update, reorder, align help and examples.
This commit is contained in:
Arun Prakash Jana
parent
7fae7b47b7
commit
fc5ee94b86
67
README.md
67
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:
|
||||
|
||||
$ 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*).
|
||||
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*).
|
||||
|
||||
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
|
||||
@ -270,7 +266,7 @@ SYMBOLS:
|
||||
- All lines beginning with "#" will be stripped. Then line 1 will be treated as the URL, line 2 will be the title, line 3 will be comma separated tags, and the rest of the lines will be parsed as descriptions.
|
||||
- **Proxy** support: environment variable *https_proxy*, if defined, is used to tunnel data for both http and https connections. The supported format is:
|
||||
|
||||
http[s]://[username:password@]proxyhost:proxyport/
|
||||
http[s]://[username:password@]proxyhost:proxyport/
|
||||
|
||||
## GUI integration
|
||||
|
||||
@ -293,7 +289,7 @@ The following steps explore the procedure on Linux with Ubuntu as the reference
|
||||
|
||||
xsel | buku -a
|
||||
|
||||
`-a` is the option to add a bookmark.
|
||||
`-a` is the option to add a bookmark.
|
||||
3. Make the script executable:
|
||||
|
||||
$ chmod +x bukuadd
|
||||
@ -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'
|
||||
|
||||
30
buku.1
30
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
|
||||
|
||||
11
buku.py
11
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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user