doc/README

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