doc/README

   1
   2                     Bookmarks Database and Internet Robot
   3
   4    A set of classes, libraries, programs and plugins I use to manipulate my
   5 bookmarks.html - check for updates, find expired URLs and so on.
   6
   7    These programs are intended to run as follows.
   8 1. bkmk2db converts bookmarks.html to bookmarks.db.
   9 2. check_urls (Internet robot) runs against bookmarks.db, checks every URL and
  10    saves results in check.db.
  11 3. db2bkmk converts bookmarks.db back to bookmarks.html.
  12    Then I use this bookmarks file and...
  13 4. bkmk2db converts bookmarks.html to bookmarks.db.
  14 5. check_urls (Internet robot) runs against bookmarks.db, checks every URL and
  15    saves results in check.db (old file copied to check.old).
  16 6. (An yet unnamed program) will compare check.old with check.db and generate
  17 detailed report. For example:
  18    this URL is unchanged
  19    this URL is changed
  20    this URL is unavailable due to: host not found...
  21
  22 AUTHOR
  23    Oleg Broytman <phd@phdru.name>
  24
  25 COPYRIGHT and LEGAL ISSUES
  26    Copyright (C) 1997-2014 PhiloSoft Design
  27 All sources protected by GNU  GPL.  Programs are provided "as-is", without
  28 any kind of warranty. All usual blah-blah-blah.
  29
  30    #include <disclaimer>
  31
  32 LICENSE
  33    GPL
  34
  35 ------------------------------ environ ------------------------------
  36
  37    These programs use the following environment variables:
  38
  39 BKMK_STORAGE - use this storage plugin; default is pickle storage.
  40 BKMK_WRITER  - use this writer plugin; default is HTML writer.
  41 BKMK_ROBOT   - use this robot plugin; default is forking robot.
  42
  43
  44 ------------------------------ bkmk2db ------------------------------
  45    NAME
  46       bkmk2db.py - script to convert bookmarks.html to a database.
  47
  48    SYNOPSIS
  49       bkmk2db.py [-is] [/path/to/bookmarks.html]
  50
  51    DESCRIPTION
  52       bkmk2db.py splits given file (or ./bookmarks.html) into a database
  53       (using storage plugin).
  54
  55       Options:
  56       -i
  57          Inhibit progress bar. Default is to display progress bar if
  58          stderr.isatty()
  59
  60       -s
  61          Suppress output of statistics at the end of the program. Default
  62          is to write how many lines the program read and how many URLs
  63          parsed. Also suppress some messages during run.
  64
  65    BUGS
  66       Aliases are not supported (yet).
  67
  68
  69 ------------------------------ db2bkmk ------------------------------
  70    NAME
  71       db2bkmk.py - script to reconstruct bookmarks.html back from a
  72       database.
  73
  74    SYNOPSIS
  75       db2bkmk.py [-s] [-p prune] [-o output_file] [-t dict.db [-r]]
  76
  77    DESCRIPTION
  78       db2bkmk.py reads bookmarks.db and creates two HTML files -
  79
  80       Options:
  81       -s
  82          Suppress output of statistics at the end of the program. Default is
  83          to write how many records the program proceed and how many URLs
  84          created. Also suppress some messages during run.
  85
  86       -p prune
  87          Prune bookmarks tree if encounter a folder with this name.
  88
  89       -o output_file
  90          Put output into different file.
  91
  92       -t dict.db
  93          For most tasks, if someone need to process bookmarks.db in a
  94          regular way (for example, replace all "gopher://gopher." with
  95          "http://www."), it is easy to write special program, processing
  96          every DB record. But there are cases when someone need to process
  97          bookmarks.db in a non-regular way: one URL must be changed
  98          in one way, another URL - in second way, etc. The -t option allows to
  99          use external dictionary for such translation. The dictionary itself
 100          is FLAD database, where every record have two keys - URL1 and
 101          URL2. With -t option in effect, db2bkmk generates translated
 102          version of bookmarks.html, where every URL1 is replaced with
 103          corresponding URL2 from the translation dictionary. (See koi2win.db
 104          for example of translation dictionary)
 105
 106       -r
 107          Reverse the effect of -t option - translate from URL2 to URL1.
 108
 109
 110 ------------------------------ check_urls -----------------------------
 111    NAME
 112       check_urls.py - Internet robot
 113
 114    SYNOPSIS
 115       check_urls.py [-ise]
 116
 117    DESCRIPTION
 118       check_urls.py runs a robot plugin against every URL. Additional field
 119       Error appeared in records that have not been checked by some reasons;
 120       the reason is a content of Error field.
 121
 122       Options:
 123       -i
 124          Inhibit progress bar. Default is to display progress bar if
 125          stderr.isatty()
 126
 127       -s
 128          Suppress output of statistics at the end of the program. Default is
 129          to write how many records the program proceed and how many URLs
 130          checked. Also suppress some messages during run.
 131
 132       -e
 133          Check only those URLs that has "error" mark in DB.
 134
 135    BUGS
 136       Ugly mechanism to catch welcome message from FTP server (from urllib).
 137
 138
 139 ------------------------------ convert_st -----------------------------
 140    NAME
 141       convert_st.py - convert between storages.
 142
 143    SYNOPSIS
 144       conver_st.py [-s] new_format.
 145
 146    DESCRIPTION
 147       convert_st.py converts the database from one format to another.
 148
 149       Options:
 150       -s
 151          Suppress output of statistics at the end of the program. Default is
 152          to write how many records the program proceed and how many URLs
 153          checked. Also suppress some messages during run.
 154
 155
 156 ------------------------------ sort_db -----------------------------
 157    NAME
 158       sort_db.py - sort DB.
 159
 160    SYNOPSIS
 161       sort_db.py [-savmr]
 162
 163    DESCRIPTION
 164       sort_db.py sorts the database according to one of the time
 165       fields and dump sorted list of bookmarks.
 166
 167       Options:
 168       -s
 169          Suppress output of statistics at the end of the program. Default is
 170          to write how many records the program proceed and how many URLs
 171          checked. Also suppress some messages during run.
 172
 173       -a
 174          Sort by add_date.
 175
 176       -v
 177          Sort by last_visit.
 178
 179       -m
 180          Sort by last_modified.
 181
 182       -r
 183          Reverse sort.
 184
 185
 186 ------------------------------ check_dups -----------------------------
 187    NAME
 188       check_dups.py - check duplicated URLs in the DB.
 189
 190    SYNOPSIS
 191       check_dups.py [-s] [-l logfile]
 192
 193    DESCRIPTION
 194       check_dups.py prints out a list of duplicated URLs (if any).
 195
 196       Options:
 197       -s
 198          Suppress output of statistics at the end of the program. Default is
 199          to write how many records the program proceed and how many URLs
 200          checked. Also suppress some messages during run.
 201
 202       -l logfile
 203          Save the list of dups in the logfile.
 204
 205
 206 ------------------------------ bkmk-add -----------------------------
 207    NAME
 208       bkmk-add - add a bookmark to the DB.
 209
 210    SYNOPSIS
 211       bkmk-add [-s] [-t title] url
 212
 213    DESCRIPTION
 214       bkmk-add adds a bookmark to the DB.
 215
 216       Options:
 217       -s
 218          Suppress output of statistics at the end of the program. Default is
 219          to write how many records the program proceed and how many URLs
 220          checked. Also suppress some messages during run.
 221
 222       -t title
 223          Force title of the bookmark.