From 4cbc982d88497816fa6c40aa5765a1bed801dec4 Mon Sep 17 00:00:00 2001 From: Arun Prakash Jana Date: Sun, 13 Aug 2017 14:33:06 +0530 Subject: [PATCH] Update documentation, help --- README.md | 33 +++++++++++++++++---------------- buku.1 | 31 ++++++++++++++++--------------- buku.py | 24 +++++++++++++----------- 3 files changed, 46 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 85cfc26..bc5236a 100644 --- a/README.md +++ b/README.md @@ -64,14 +64,15 @@ PRs are welcome. Please visit [#174](https://github.com/jarun/Buku/issues/174) f - Lightweight, clean interface - Flexible text editor integration -- Fetch page title, add tags and comments -- Multiple search modes (e.g. `deep`, `regex`) +- Fetch, edit page title; add tags and notes +- Powerful search modes including regex, substring - Continuous search at prompt, on the fly mode switch - Open bookmarks and search results in browser -- Import/export in HTML (FF, Chrome compatible) or Markdown +- Manual encryption support +- Auto-import Firefox and Google Chrome bookmarks +- Import/export bookmarks from/to HTML or Markdown - Shorten and expand URLs -- Smart tag editing with >>, > or << symbols at prompt -- Password protection (manual) +- Smart tag management using redirection (>>, >, <<) - Portable, merge-able database to sync between systems - Multithreaded full DB refresh - Shell completion scripts, man page with handy examples @@ -179,9 +180,9 @@ EDIT OPTIONS: N=0: mutable (default), N=1: immutable SEARCH OPTIONS: - -s, --sany find records with ANY search keyword + -s, --sany find records with ANY matching keyword this is the default search option - -S, --sall find records with ALL search keywords + -S, --sall find records matching ALL the keywords special keywords - "blank": entries with empty title/tag "immutable": entries with locked title @@ -197,14 +198,13 @@ ENCRYPTION OPTIONS: hash iterations to generate key POWER TOYS: + --ai auto-import from Firefox and Chrome -e, --export file export bookmarks in Firefox format html export markdown, if file ends with '.md' format: [title](url), 1 entry per line use --tag to export only specific tags -i, --import file import Firefox or Chrome bookmarks html import markdown, if file ends with '.md' - --ai auto-import bookmarks - works with Firefox and Google Chrome -m, --merge file add bookmarks from another buku DB file -p, --print [...] show record details by indices, ranges print all bookmarks, if no arguments @@ -234,19 +234,20 @@ SYMBOLS: + comment # tags -keys: +PROMPT KEYS: 1-N browse search result indices and/or ranges a open all results in browser s keyword [...] search for records with ANY keyword S keyword [...] search for records with ALL keywords d match substrings ('pen' matches 'opened') r expression run a regex search - t [...] search bookmarks by a tag or show tag list - g [...][>>|>|<<][...] append, remove tags to/from indices and/or ranges - o [...] browse bookmarks by indices and/or ranges - p [...] print bookmarks by indices and/or ranges - w [editor|index] edit and add or update a bookmark - (tag list index fetches bookmarks by tag) + t [...] search bookmarks by a tag or show taglist + list index after a tag listing shows records with the tag + o id|range [...] browse bookmarks by indices and/or ranges + p id|range [...] print bookmarks by indices and/or ranges + g [taglist id|range ...] [>>|>|<<] record id|range [...] + append, set, remove (all or specific) tags + w [editor|id] edit and add or update a bookmark ? show this help q, ^D, double Enter exit buku ``` diff --git a/buku.1 b/buku.1 index baf8ae4..4958b20 100644 --- a/buku.1 +++ b/buku.1 @@ -11,14 +11,15 @@ is a command-line utility to store, tag, search and organize bookmarks. .PP * Lightweight, clean interface * Flexible text editor integration - * Fetch page title, add tags and comments - * Multiple search modes (e.g. \fIdeep\fR, \fIregex\fR) + * Fetch, edit page title; add tags and notes + * Powerful search modes including regex, substring * Continuous search at prompt, on the fly mode switch * Open bookmarks and search results in browser - * Import/export in HTML (FF, Chrome compatible) or Markdown + * Manual encryption support + * Auto-import Firefox and Google Chrome bookmarks + * Import/export bookmarks from/to HTML or Markdown * Shorten and expand URLs - * Smart tag editing with >>, > or << symbols at prompt - * Password protection (manual) + * Smart tag management using redirection (>>, >, <<) * Portable, merge-able database to sync between systems * Multithreaded full DB refresh * Shell completion scripts, man page with handy examples @@ -168,6 +169,9 @@ Decrypt (unlock) the DB file with (> 0, default 8) hash passes to generate key. .SH POWER OPTIONS .TP +.BI \--ai +Auto-import bookmarks from Firefox and Google Chrome. +.TP .BI \-e " " \--export " file" Export bookmarks to Firefox bookmarks formatted HTML. Works with --tag to export only specific tags. Markdown is used if .I file @@ -180,9 +184,6 @@ Import bookmarks exported from Firefox or Google Chrome as HTML. .I file is considered Markdown (compliant with --export format) if it has '.md' extension. .TP -.BI \--ai -Auto-import bookmarks from Firefox and Google Chrome. -.TP .BI \-m " " \--merge " file" Add bookmarks from another buku database file. .TP @@ -281,18 +282,18 @@ Toggle deep search to match substrings ('pen' matches 'opened'). Run a regular expression search. .TP .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. +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 with this key. .TP -.BI "g" " [...][>>|>|<<][...]" -Append, remove tags to/from indices and/or ranges. -.TP -.BI "o" " [...]" +.BI "o" " id|range [...]" Browse bookmarks by indices and/or ranges. .TP -.BI "p" " [...]" +.BI "p" " id|range [...]" Print bookmarks by indices and/or ranges. .TP -.BI "w" " [editor|index]" +.BI "g" " [taglist id|range ...] [>>|>|<<] record id|range [...]" +Append, set, remove specific or all tags by indices and/or ranges to bookmark indices and/or ranges (see \fBEXAMPLES\fR section below). +.TP +.BI "w" " [editor|id]" Edit and add or update a bookmark. .TP .BI "?" diff --git a/buku.py b/buku.py index b1b63ae..6cbeb1b 100755 --- a/buku.py +++ b/buku.py @@ -2035,19 +2035,20 @@ Webpage: https://github.com/jarun/Buku @staticmethod def prompt_help(file=sys.stdout): file.write(''' -keys: +PROMPT KEYS: 1-N browse search result indices and/or ranges a open all results in browser s keyword [...] search for records with ANY keyword S keyword [...] search for records with ALL keywords d match substrings ('pen' matches 'opened') r expression run a regex search - t [...] search bookmarks by a tag or show tag list - g [...][>>|>|<<][...] append, remove tags to/from indices and/or ranges - o [...] browse bookmarks by indices and/or ranges - p [...] print bookmarks by indices and/or ranges - w [editor|index] edit and add or update a bookmark - (tag list index fetches bookmarks by tag) + t [...] search bookmarks by a tag or show taglist + list index after a tag listing shows records with the tag + o id|range [...] browse bookmarks by indices and/or ranges + p id|range [...] print bookmarks by indices and/or ranges + g [taglist id|range ...] [>>|>|<<] record id|range [...] + append, set, remove (all or specific) tags + w [editor|id] edit and add or update a bookmark ? show this help q, ^D, double Enter exit buku @@ -3092,9 +3093,9 @@ POSITIONAL ARGUMENTS: search_grp = argparser.add_argument_group( title='SEARCH OPTIONS', - description=''' -s, --sany find records with ANY search keyword + description=''' -s, --sany find records with ANY matching keyword this is the default search option - -S, --sall find records with ALL search keywords + -S, --sall find records matching ALL the keywords special keywords - "blank": entries with empty title/tag "immutable": entries with locked title @@ -3129,7 +3130,8 @@ POSITIONAL ARGUMENTS: power_grp = argparser.add_argument_group( title='POWER TOYS', - description=''' -e, --export file export bookmarks in Firefox format html + description=''' --ai auto-import from Firefox and Chrome + -e, --export file export bookmarks in Firefox format html export markdown, if file ends with '.md' format: [title](url), 1 entry per line use --tag to export only specific tags @@ -3161,9 +3163,9 @@ POSITIONAL ARGUMENTS: -V check latest upstream version available -z, --debug show debug information and verbose logs''') addarg = power_grp.add_argument + addarg('--ai', action='store_true', help=HIDE) addarg('-e', '--export', nargs=1, help=HIDE) addarg('-i', '--import', nargs=1, dest='importfile', help=HIDE) - addarg('--ai', action='store_true', help=HIDE) addarg('-m', '--merge', nargs=1, help=HIDE) addarg('-p', '--print', nargs='*', help=HIDE) addarg('-f', '--format', type=int, default=0, choices={1, 2, 3, 4}, help=HIDE)