doc/bookmarks.txt

   1 The Ultimate Bookmarks Guide
   2 ----------------------------
   3
   4 Glad to see you again, mortal. Now, we are going to learn about bookmarks -
   5 how to use them, how to maintain them, and also something more about the file
   6 formats and maybe even about the code structure later. But don't fear, we
   7 won't burden you with it, just stop reading when you already know enough.
   8
   9 In order to read this, you need some common sense, the ability to start ELinks
  10 and some idea about what's a Web document, a URL address and knowledge like
  11 that.
  12
  13 If we ever mention some keys here, please note that you can rebind almost any
  14 action to another key which you like more - then you must obviously imagine
  15 your own key in place of that. Below, we will list all actions, options and so
  16 on related to bookmarks. We won't tell you how to rebind the keys, though;
  17 another document will take on that.
  18
  19 Somewhat out-of-order, a very frequent FAQ: In order to move bookmarks around,
  20 you need to mark them first - press 'Insert' or '*' (if you use the default
  21 keymap) to do that.
  22
  23
  24 The Bookmark Manager
  25 ~~~~~~~~~~~~~~~~~~~~
  26
  27 Basically, almost everything is going on in the so-called bookmark manager.
  28 That's a special dialog window, which contains a listing of all the bookmarks
  29 you ever told ELinks to remember and it lets you to do with them anything you
  30 would ever want to do with them.
  31
  32 You launch the bookmark manager by pressing the 's' key in standby (standard)
  33 mode. You should see a big empty space (bookmarks will slowly appear there as
  34 you will add them) and couple of buttons shriveling at the bottom. So, as a
  35 start, move with the right (or left; both will do) arrow to the button *Add
  36 bookmark* and fill in the input fields it offers to you. I mean, you can type
  37 something like "ELinks homepage" to the first field, then move down by e.g.
  38 the down arrow and fill "http://elinks.cz/" to the second field. Then,
  39 bravely press enter and watch the bookmark popping up at the top of the vast
  40 area reserved for bookmarks.
  41
  42 Repeat this step few times. Now, you can move between bookmarks by the up and
  43 down arrow, jump to the location any of them points to by the Goto button,
  44 change it by the Edit button, delete it with the Delete button and so on. When
  45 you'll become bored, press the escape button and you're free again!
  46
  47
  48 The Ancient Forests
  49 ~~~~~~~~~~~~~~~~~~~
  50
  51 It's not very convenient to have all the bookmarks mixed up - soon, you will
  52 get lost in them. Thus, in ELinks you can categorize them to various folders,
  53 subfolders, subsubfolders and so on, then you can expand and back enfold them
  54 and so on.
  55
  56 In order to create your first folder, use the button *Add folder* and fill the
  57 first input field. You can safely ignore the URL field, ELinks will do the
  58 same. *POOF* and you see it - it has that strange `[+]` or `[-]` thing there.
  59 If it has `[+]` near, it's enfolded, while when it has `[-]` near, it is
  60 expanded, while you can change that by pressing the spacebar.
  61
  62 In order to add a bookmark into a folder, move on the item of the folder (it
  63 must be expanded) or onto any bookmark inside of the folder and simply do the
  64 usual *Add bookmark* job. You can also move the bookmarks around, obviously.
  65 Before pressing the *Move* button, you need to first mark all the bookmarks
  66 (or even folders) you want to move using the 'Insert' or '*' key--asterisk
  67 will appear near of all marked bookmarks--and then move to where you want to
  68 have the stuff moved to.
  69
  70 Separators can be inserted as well, using *Add separator* button, or by
  71 entering a special bookmark with "-" as title and no url.
  72
  73
  74 Searching for a needle in the haystack
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 Of course, you can search in the bookmarks. Just use the *Find* button  - for
  78 convenience, you have the current document's URL and title pre-filled there,
  79 and for convenience only up-up-enter-down-down sequence is enough to have the
  80 playground clean. Then, just fill a substring of what you are looking for, and
  81 the bookmarks will be filtered so that only the matching ones are shown.
  82 (Actually, currently it will not be filtered but the cursor will only jump to
  83 the first matching bookmark below the current cursor position - and it will
  84 *NOT* wrap around. The exact behaviour changes time by time and hasn't been
  85 stabilized yet.)
  86
  87 File formats
  88 ~~~~~~~~~~~~
  89
  90 ELinks supports two bookmark formats: the native format and a generic bookmark
  91 exchange format called XBEL. Each of those formats has its pros and cons,
  92 which we shall discuss below. You can switch between then by changing the
  93 option 'bookmarks.file_format'.
  94
  95 However, first please note that ELinks 'CANNOT' read Links bookmarks directly.
  96 Importing Links-0.9x (or Links-1.x) bookmarks is easy - it is just matter of
  97 changing all the '|' (pipe) characters to tabs.  There is a script for that in
  98 the contrib/conv/ directory. Importing Links-2.xx bookmarks is not so easy; in
  99 fact, the scribe knows of no way of doing that at the time of writing this, so
 100 this is up to you to figure out (if you do, please tell us so that we can add
 101 it here).  Perhaps you might find a way to convert Links2 bookmarks to the
 102 XBEL format, which can then be loaded in ELinks.
 103
 104 Native file format
 105 ^^^^^^^^^^^^^^^^^^
 106
 107 This is the preferred bookmarks format, which is also used by default.  The
 108 bookmarks file is `~/.elinks/bookmarks`, in a simple format:
 109
 110         <name> '\t' <url> [ '\t' <depth> ['\t' <flags>] ] '\n'
 111
 112 '\t' represents a tab character, '\n' represents a newline character.  [Square
 113 brackets] denote optional parts. The '<name>' and '<url>' fields should be
 114 obvious.  '<depth>' contains the depth level of the entry - by that, ELinks
 115 can unambiguously figure out the bookmarks hierarchy:
 116
 117         Bookmarks structure:                                Depth:
 118          ,-- The Pasky's C Bestiary                         0
 119         [-]- Wonderful things                               0
 120          |    |-- Christmas Carol in l33tsp34k by L.M.      1
 121          |   [-]- Beautiful Potato Camera Shots             1
 122          |   [-]- Gallery of Scary Images of Jonas Fonseca  1
 123          |         |-- Jonas torturing gdb                  2
 124          |        [-]- Urgh                                 2
 125          |         |    `-- Jonas consuming Tofu            3
 126          |         `-- Jonas with crashed ELinks            2
 127          |-- Slides from Witek's hack-patch show            0
 128          `-- Miciah's English Grammar Spellbook             0
 129
 130 '<flags>' is a string of characters. Currently, two flags are supported:
 131
 132 `-------`---------------------------------------------------------------------
 133 Flag    Description
 134 ------------------------------------------------------------------------------
 135 E       This folder is currently expanded. (No effect for non-folders.)
 136 F       This entry is a folder. The <url> part is usually empty.
 137 ------------------------------------------------------------------------------
 138
 139 Separators: these are special bookmarks with "-" as title and no url.
 140
 141 Pros::
 142         Naturally, ELinks handles the native format the best, easiest and most
 143         reliably.
 144
 145 Cons::
 146         It is unlikely that you could use the native format anywhere else than
 147         in ELinks.
 148
 149 To use the native format, set 'bookmarks.file_format' = 0.
 150
 151 XBEL file format
 152 ^^^^^^^^^^^^^^^^
 153
 154 The XBEL file format support was added at some point during the 0.4
 155 development by Fabio Boneli. It has never been complete and has plenty of
 156 troubles, but generally, it works at the basic level. The bookmarks file is
 157 `~/.elinks/bookmarks.xbel` (thanks to a different filename, you can have both
 158 XBEL and native bookmarks saved in your `~/.elinks` directory).
 159
 160 We shall not describe the XBEL file format here,
 161
 162         http://pyxml.sourceforge.net/topics/xbel/
 163
 164 is the authoritative resource on that. It also contains list of some of the
 165 applications supporting the format.  Basically, you will be probably able to
 166 convert from/to the XBEL format to/from most of the other widely used formats,
 167 so this way you can import your bookmarks to ELinks from basically anything.
 168
 169 Pros::
 170         XBEL is the gateway to the rest of the bookmarks world.
 171
 172 Cons::
 173         The support for XBEL is incomplete and there are known bugs.
 174         Especially, national character sets are basically not supported, so
 175         ELinks will most likely get it wrong if you have any non-ASCII
 176         characters in your bookmarks.  Generally, the XBEL support should be
 177         considered experimental and you shouldn't rely on it. It *could* trash
 178         your XBEL bookmarks file so make regular backups.
 179
 180 To use the XBEL format, set 'bookmarks.file_format' to 1.
 181
 182 Usage hints
 183 ^^^^^^^^^^^
 184
 185 As already noted above, probably the best usage pattern is to use XBEL for
 186 importing/exporting your bookmarks to/from ELinks and the native format for
 187 regular operation. Of course, if you want to synchronize your bookmarks in
 188 ELinks and some other XBEL-supporting gadget and you are brave, you can use
 189 XBEL as your exclusive bookmark format - the choice is upon you.
 190
 191 Regarding the bookmarks synchronization, there is one important note. ELinks
 192 saves your bookmarks each time you added one through the 'a' shortcut
 193 (add-bookmark action) or when closing the bookmarks manager if you made any
 194 changes or when quitting ELinks. However, ELinks reads your bookmarks only
 195 *ONCE*, during the startup. This behaviour may change in the future (tell us
 196 if you need a way for ELinks to re-read the bookmarks file), but this is how
 197 it is done now.
 198
 199 Actually, you may now ask "So how do I convert bookmarks between the two
 200 formats?".  It is quite easy.  ELinks simply follows the current value of
 201 'bookmarks.file_format' whenever loading/saving the bookmarks.
 202
 203 So, e.g. if you normally use the native format but you want the bookmarks to
 204 be saved in the XBEL format once, change 'bookmarks.file_format' to 1, then
 205 cause the bookmarks to be resaved (e.g. by doing some simple change, like
 206 adding a trailing space to some bookmark's title or so), then change the
 207 'bookmarks.file_format' value back to 0.
 208
 209 It is a little more complicated if you normally use the native format but you
 210 want to import bookmarks from the XBEL format once. You again change
 211 'bookmarks.file_format' to 1, then cause the bookmarks to be reloaded.  That
 212 involves saving the configuration, quitting ELinks _completely_ (that means
 213 closing/killing all instances of it you have running), then restarting it and
 214 changing 'bookmarks.file_format' to 0. Then save the configuration again and
 215 cause ELinks to resave the bookmarks.
 216
 217 Agreed, this all strange dances are quite clumsy, likely some simple
 218 wizard-like interface for switching the bookmarks formats will be introduced
 219 in the future. So far, we have had no reports from our users that anyone wants
 220 to switch their bookmarks format frequently, so this is not too high on our
 221 TODO list. So be sure to tell us if you would like this process to be
 222 simplified rather sooner than later.