From 493149942d119c83fe0056c889e34c8886cf822b Mon Sep 17 00:00:00 2001 From: Arun Prakash Jana Date: Fri, 20 May 2016 23:56:01 +0530 Subject: [PATCH] Update help. --- README.md | 90 ++++++++++++++++++++++++++++++++++--------------------- buku | 10 ++++--- buku.1 | 27 +++++++++++------ 3 files changed, 80 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 0470ebc..0cb7975 100644 --- a/README.md +++ b/README.md @@ -105,28 +105,32 @@ Shell completion scripts for Bash, Fish and Zsh can be found in respective subdi **NOTE:** If you are using `buku` v1.9 or below please refer to the installed man page or program help. - usage: buku [-a URL [tags ...]] [-u [N [URL tags ...]]] - [-t [...]] [-c [...]] [-d [N]] [-h] + usage: buku [-a URL [tags ...]] [-u [N]] [-d [N]] + [--url keyword] [--tag [...]] [-t [...]] [-c [...]] [-s keyword [...]] [-S keyword [...]] [--st [...]] [-k [N]] [-l [N]] [-p [N]] [-f N] - [-r oldtag [newtag ...]] [-j] [-o N] [-z] + [-r oldtag [newtag ...]] [-j] [-o N] [-z] [-h] A private command-line bookmark manager. Your mini web! general options: -a, --add URL [tags ...] bookmark URL with comma-separated tags - -u, --update [N [URL tags ...]] - update fields of bookmark at DB index N + -u, --update [N] update fields of bookmark at DB index N refresh all titles, if no arguments - if URL omitted and -t is unused, update - title of bookmark at index N from web - -t, --title [...] manually set title, works with -a, -u - do not set title, if no arguments - -c, --comment [...] description of the bookmark, works with - -a, -u; clears comment, if no arguments + refresh title of bookmark at N, if only + N is specified without any update modifiers + to change url, tag or comment -d, --delete [N] delete bookmark at DB index N delete all bookmarks, if no arguments + --url keyword specify url, works with -u + --tag [...] specify comma-separated tags, works with -u + clears tag, if no arguments + -t, --title [...] manually set title, works with -a, -u + if no arguments: + -a: do not set title, -u: clear title + -c, --comment [...] description of the bookmark, works with + -a, -u; clears comment, if no arguments -h, --help show this information search options: @@ -171,6 +175,10 @@ Shell completion scripts for Bash, Fish and Zsh can be found in respective subdi - It's advisable to copy URLs directly from the browser address bar, i.e., along with the leading `http://` or `https://` token. `buku` looks up title data (found within tags of HTML) from the web ONLY for fully-formed HTTP(S) URLs. - If the URL contains characters like `;`, `&` or brackets they may be interpreted specially by the shell. To avoid it, add the URL within single or double (`'`/`"`) quotes. - URLs are unique in DB. The same URL cannot be added twice. You can update tags and re-fetch title data. +- Update operation: + - if --title, --tag or --comment is passed without argument, clear the corresponding field from DB + - if --url is passed (and --title is omitted), update the title from web using the URL + - if index number is passed without any other options (--url, --title, --tag and --comment), read the URL from DB and update title from web - Search works in mysterious ways: - Case-insensitive. - Substrings match (`match` matches `rematched`) for URL, title and tags. @@ -185,9 +193,15 @@ Shell completion scripts for Bash, Fish and Zsh can be found in respective subdi # Examples 1. **Add** a bookmark with **tags** `linux news` and `open source`, **comment** `Informative website on Linux and open source`, **fetch page title** from the web: - $ buku -a http://tuxdiary.com linux news, open source -c Informative website on Linux and open source - Title: [TuxDiary | Linux, open source and a pinch of leisure.] - Added at index 15012014 + $ buku -a https://tuxdiary.com linux news, open source -c Informative website on Linux and open source + Title: [TuxDiary – Linux, open source, command-line, leisure.] + Added at index 336 + + 336. https://tuxdiary.com + > TuxDiary – Linux, open source, command-line, leisure. + + Informative website on Linux and open source + # linux news,open source +where, >: title, +: comment, #: tags 2. **Add** a bookmark with tags `linux news` and `open source` & **custom title** `Linux magazine`: $ buku -a http://tuxdiary.com linux news, open source -t 'Linux magazine' @@ -196,60 +210,68 @@ Note that URL must precede tags. 3. **Add** a bookmark **without a title** (works for update too): $ buku -a http://tuxdiary.com linux news, open source -t -4. **Update** existing bookmark at index 15012014 with new URL and tags, fetch title from the web: +4. **Update** existing bookmark at index 15012014 with new URL, tags and comments, fetch title from the web: - $ buku -u 15012014 http://tuxdiary.com/ linux news, open source, magazine - Title: [TuxDiary | Linux, open source and a pinch of leisure.] - Updated index 15012014 -Tags are updated too. Original tags are removed. -5. **Update** or refresh **full DB** with page titles from the web: + $ buku -u 15012014 --url http://tuxdiary.com/ --tag linux news, open source, magazine -c site for Linux utilities +5. Fetch and **update only title** for bookmark at 15012014: + + $ buku -u 15012014 +6. Update only comment for bookmark at 15012014: + + $ buku -u 15012014 -c this is a new comment +Applies to --url, --title and --tag too. +7. 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. +8. **Update** or refresh **full DB** with page titles from the web: $ buku -u -This operation does not modify the indexes, URLs or tags. Only title is refreshed if fetched title is non-empty. -6. **Delete** bookmark at index 15012014: +This operation does not modify the indexes, URLs, tags or comments. Only title is refreshed if fetched title is non-empty. +9. **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. -7. **Delete all** bookmarks: +10. **Delete all** bookmarks: $ buku -d -8. **Search** bookmarks for **ANY** of the keywords `kernel` and `debugging` in URL, title or tags: +11. **Search** bookmarks for **ANY** of the keywords `kernel` and `debugging` in URL, title or tags: $ buku -s kernel debugging -9. **Search** bookmarks with **ALL** the keywords `kernel` and `debugging` in URL, title or tags: +12. **Search** bookmarks with **ALL** the keywords `kernel` and `debugging` in URL, title or tags: $ buku -S kernel debugging -10. **Search** bookmarks with **tag** `general kernel concepts`: +13. **Search** bookmarks with **tag** `general kernel concepts`: $ buku --st general kernel concepts Note the commas (,) before and after the tag. Comma is the tag delimiter in DB. -11. List **all unique tags** alphabetically: +14. List **all unique tags** alphabetically: $ buku --st -12. **Encrypt or decrypt** DB with **custom number of iterations** (15) to generate key: +15. **Encrypt or decrypt** DB with **custom number of iterations** (15) to generate key: $ buku -l 15 $ buku -k 15 The same number of iterations must be used for one lock & unlock instance. Default is 8. -13. **Show details** of bookmark at index 15012014: +16. **Show details** of bookmark at index 15012014: $ buku -p 15012014 -14. **Show all** bookmarks with real index from database: +17. **Show all** bookmarks with real index from database: $ buku -p $ buku -p | more -15. **Replace tag** 'old tag' with 'new tag': +18. **Replace tag** 'old tag' with 'new tag': $ buku -r 'old tag' new tag -16. **Delete tag** 'old tag' from DB: +19. **Delete tag** 'old tag' from DB: $ buku -r 'old tag' -17. **Open URL** at index 15012014 in browser: +20. **Open URL** at index 15012014 in browser: $ buku -o 15012014 -18. More **help**: +21. More **help**: $ buku $ man buku diff --git a/buku b/buku index 4dd8c0c..c31052d 100755 --- a/buku +++ b/buku @@ -1263,17 +1263,19 @@ argparser = ExtendedArgumentParser( general_group = argparser.add_argument_group(title="general options", description='''-a, --add URL [tags ...] bookmark URL with comma-separated tags --u, --update [N] - update fields of bookmark at DB index N +-u, --update [N] update fields of bookmark at DB index N refresh all titles, if no arguments refresh title of bookmark at N, if only - N is specified + N is specified without any update modifiers + to change url, tag or comment -d, --delete [N] delete bookmark at DB index N delete all bookmarks, if no arguments --url keyword specify url, works with -u --tag [...] specify comma-separated tags, works with -u clears tag, if no arguments --t, --title [...] manually set title, works with -a, -u; do not +-t, --title [...] manually set title, works with -a, -u + if no arguments: + -a: do not set title, -u: clear title set (-a) or clear (-u) title, if no arguments -c, --comment [...] description of the bookmark, works with -a, -u; clears comment, if no arguments diff --git a/buku.1 b/buku.1 index 010ea5f..dcd5da5 100644 --- a/buku.1 +++ b/buku.1 @@ -3,15 +3,15 @@ buku \- A private command-line bookmark manager. Your mini web! .SH SYNOPSIS .B buku -[-a URL [tags ...]] [-u [N [URL tags ...]]] +[-a URL [tags ...]] [-u [N]] [-d [N]] .br - [-t [...]] [-c [...]] [-d [N]] [-h] + [--url keyword] [--tag [...]] [-t [...]] [-c [...]] .br [-s keyword [...]] [-S keyword [...]] [--st [...]] .br [-k [N]] [-l [N]] [-p [N]] [-f N] .br - [-r oldtag [newtag ...]] [-j] [-o N] [-z] + [-r oldtag [newtag ...]] [-j] [-o N] [-z] [-h] .SH DESCRIPTION .B buku is a command-line tool to save, tag and search bookmarks. @@ -31,6 +31,11 @@ It's advisable to copy URLs directly from the browser address bar, i.e., along w If the URL contains characters like ';', '&' or brackets they may be interpreted specially by the shell. To avoid it, add the URL within single or double ('/") qoutes. .PP URLs are unique in DB. The same URL cannot be added twice. You can update tags and re-fetch title data. +.pp +Update operation: + - if --title, --tag or --comment is passed without argument, clear the corresponding field from DB + - if --url is passed (and --title is omitted), update the title from web using the URL + - if index number is passed without any other options (--url, --title, --tag and --comment), read the URL from DB and update title from web .PP Search works in mysterious ways: - Case-insensitive. @@ -51,14 +56,18 @@ Bookmark .I URL along with comma-separated tags. A tag can have multiple words. .TP -.BI \-u " " \--update " [N [URL tags ...]]" +.BI \-u " " \--update " [N]" Update fields of the bookmark at index .I N -in DB. If URL is omitted (and -t is not used) the title of entry at index +in DB. If .I N -is refreshed from the web. If -.I N -is omitted, all titles are refreshed from the web. +and other options are omitted, all titles are refreshed from the web. Works with update modifiers for the fields url, title, tag and comment. If only N is passed without any update modifiers, title is fetched and updated (if not empty). +.TP +.BI \--url " [...]" +Manually specify the URL. Fetches and updates title if --title is not used. +.TP +.BI \--tag " [...]" +Specify comma separated tags. Clears the tags, if no arguments passed. .TP .BI \-t " " \--title " [...]" Manually specify the title, works with -a, -u. Omits or clears the title, if no arguments passed. @@ -200,7 +209,7 @@ Tags are updated too. Original tags are removed. .EE .PP .IP "" 4 -This operation does not modify the indexes, URLs or tags. 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. .PP .IP 6. 4 \fBDelete\fR bookmark at index 15012014: