mirror of
https://github.com/rkd77/elinks.git
synced 2024-12-04 14:46:47 -05:00
d061c554cf
... also drop comment about hacking.txt being extended gradually. AsciiDoc burps on it and it really is kind of a boot message.
223 lines
10 KiB
Plaintext
223 lines
10 KiB
Plaintext
The Ultimate Bookmarks Guide
|
|
----------------------------
|
|
|
|
Glad to see you again, mortal. Now, we are going to learn about bookmarks -
|
|
how to use them, how to maintain them, and also something more about the file
|
|
formats and maybe even about the code structure later. But don't fear, we
|
|
won't burden you with it, just stop reading when you already know enough.
|
|
|
|
In order to read this, you need some common sense, the ability to start ELinks
|
|
and some idea about what's a Web document, a URL address and knowledge like
|
|
that.
|
|
|
|
If we ever mention some keys here, please note that you can rebind almost any
|
|
action to another key which you like more - then you must obviously imagine
|
|
your own key in place of that. Below, we will list all actions, options and so
|
|
on related to bookmarks. We won't tell you how to rebind the keys, though;
|
|
another document will take on that.
|
|
|
|
Somewhat out-of-order, a very frequent FAQ: In order to move bookmarks around,
|
|
you need to mark them first - press 'Insert' or '*' (if you use the default
|
|
keymap) to do that.
|
|
|
|
|
|
The Bookmark Manager
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Basically, almost everything is going on in the so-called bookmark manager.
|
|
That's a special dialog window, which contains a listing of all the bookmarks
|
|
you ever told ELinks to remember and it lets you to do with them anything you
|
|
would ever want to do with them.
|
|
|
|
You launch the bookmark manager by pressing the 's' key in standby (standard)
|
|
mode. You should see a big empty space (bookmarks will slowly appear there as
|
|
you will add them) and couple of buttons shriveling at the bottom. So, as a
|
|
start, move with the right (or left; both will do) arrow to the button *Add
|
|
bookmark* and fill in the input fields it offers to you. I mean, you can type
|
|
something like "ELinks homepage" to the first field, then move down by e.g.
|
|
the down arrow and fill "http://elinks.or.cz/" to the second field. Then,
|
|
bravely press enter and watch the bookmark popping up at the top of the vast
|
|
area reserved for bookmarks.
|
|
|
|
Repeat this step few times. Now, you can move between bookmarks by the up and
|
|
down arrow, jump to the location any of them points to by the Goto button,
|
|
change it by the Edit button, delete it with the Delete button and so on. When
|
|
you'll become bored, press the escape button and you're free again!
|
|
|
|
|
|
The Ancient Forests
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
It's not very convenient to have all the bookmarks mixed up - soon, you will
|
|
get lost in them. Thus, in ELinks you can categorize them to various folders,
|
|
subfolders, subsubfolders and so on, then you can expand and back enfold them
|
|
and so on.
|
|
|
|
In order to create your first folder, use the button *Add folder* and fill the
|
|
first input field. You can safely ignore the URL field, ELinks will do the
|
|
same. *POOF* and you see it - it has that strange `[+]` or `[-]` thing there.
|
|
If it has `[+]` near, it's enfolded, while when it has `[-]` near, it is
|
|
expanded, while you can change that by pressing the spacebar.
|
|
|
|
In order to add a bookmark into a folder, move on the item of the folder (it
|
|
must be expanded) or onto any bookmark inside of the folder and simply do the
|
|
usual *Add bookmark* job. You can also move the bookmarks around, obviously.
|
|
Before pressing the *Move* button, you need to first mark all the bookmarks
|
|
(or even folders) you want to move using the 'Insert' or '*' key--asterisk
|
|
will appear near of all marked bookmarks--and then move to where you want to
|
|
have the stuff moved to.
|
|
|
|
Separators can be inserted as well, using *Add separator* button, or by
|
|
entering a special bookmark with "-" as title and no url.
|
|
|
|
|
|
Searching for a needle in the haystack
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Of course, you can search in the bookmarks. Just use the *Find* button - for
|
|
convenience, you have the current document's URL and title pre-filled there,
|
|
and for convenience only up-up-enter-down-down sequence is enough to have the
|
|
playground clean. Then, just fill a substring of what you are looking for, and
|
|
the bookmarks will be filtered so that only the matching ones are shown.
|
|
(Actually, currently it will not be filtered but the cursor will only jump to
|
|
the first matching bookmark below the current cursor position - and it will
|
|
*NOT* wrap around. The exact behaviour changes time by time and hasn't been
|
|
stabilized yet.)
|
|
|
|
File formats
|
|
~~~~~~~~~~~~
|
|
|
|
ELinks supports two bookmark formats: the native format and a generic bookmark
|
|
exchange format called XBEL. Each of those formats has its pros and cons,
|
|
which we shall discuss below. You can switch between then by changing the
|
|
option 'bookmarks.file_format'.
|
|
|
|
However, first please note that ELinks 'CANNOT' read Links bookmarks directly.
|
|
Importing Links-0.9x (or Links-1.x) bookmarks is easy - it is just matter of
|
|
changing all the '|' (pipe) characters to tabs. There is a script for that in
|
|
the contrib/conv/ directory. Importing Links-2.xx bookmarks is not so easy; in
|
|
fact, the scribe knows of no way of doing that at the time of writing this, so
|
|
this is up to you to figure out (if you do, please tell us so that we can add
|
|
it here). Perhaps you might find a way to convert Links2 bookmarks to the
|
|
XBEL format, which can then be loaded in ELinks.
|
|
|
|
Native file format
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
This is the preferred bookmarks format, which is also used by default. The
|
|
bookmarks file is `~/.elinks/bookmarks`, in a simple format:
|
|
|
|
<name> '\t' <url> [ '\t' <depth> ['\t' <flags>] ] '\n'
|
|
|
|
'\t' represents a tab character, '\n' represents a newline character. [Square
|
|
brackets] denote optional parts. The '<name>' and '<url>' fields should be
|
|
obvious. '<depth>' contains the depth level of the entry - by that, ELinks
|
|
can unambiguously figure out the bookmarks hierarchy:
|
|
|
|
Bookmarks structure: Depth:
|
|
,-- The Pasky's C Bestiary 0
|
|
[-]- Wonderful things 0
|
|
| |-- Christmas Carol in l33tsp34k by L.M. 1
|
|
| [-]- Beautiful Potato Camera Shots 1
|
|
| [-]- Gallery of Scary Images of Jonas Fonseca 1
|
|
| |-- Jonas torturing gdb 2
|
|
| [-]- Urgh 2
|
|
| | `-- Jonas consuming Tofu 3
|
|
| `-- Jonas with crashed ELinks 2
|
|
|-- Slides from Witek's hack-patch show 0
|
|
`-- Miciah's English Grammar Spellbook 0
|
|
|
|
'<flags>' is a string of characters. Currently, two flags are supported:
|
|
|
|
`-------`---------------------------------------------------------------------
|
|
Flag Description
|
|
------------------------------------------------------------------------------
|
|
E This folder is currently expanded. (No effect for non-folders.)
|
|
F This entry is a folder. The <url> part is usually empty.
|
|
------------------------------------------------------------------------------
|
|
|
|
Separators: these are special bookmarks with "-" as title and no url.
|
|
|
|
Pros::
|
|
Naturally, ELinks handles the native format the best, easiest and most
|
|
reliably.
|
|
|
|
Cons::
|
|
It is unlikely that you could use the native format anywhere else than
|
|
in ELinks.
|
|
|
|
To use the native format, set 'bookmarks.file_format' = 0.
|
|
|
|
XBEL file format
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
The XBEL file format support was added at some point during the 0.4
|
|
development by Fabio Boneli. It has never been complete and has plenty of
|
|
troubles, but generally, it works at the basic level. The bookmarks file is
|
|
`~/.elinks/bookmarks.xbel` (thanks to a different filename, you can have both
|
|
XBEL and native bookmarks saved in your `~/.elinks` directory).
|
|
|
|
We shall not describe the XBEL file format here,
|
|
|
|
http://pyxml.sourceforge.net/topics/xbel/
|
|
|
|
is the authoritative resource on that. It also contains list of some of the
|
|
applications supporting the format. Basically, you will be probably able to
|
|
convert from/to the XBEL format to/from most of the other widely used formats,
|
|
so this way you can import your bookmarks to ELinks from basically anything.
|
|
|
|
Pros::
|
|
XBEL is the gateway to the rest of the bookmarks world.
|
|
|
|
Cons::
|
|
The support for XBEL is incomplete and there are known bugs.
|
|
Especially, national character sets are basically not supported, so
|
|
ELinks will most likely get it wrong if you have any non-ASCII
|
|
characters in your bookmarks. Generally, the XBEL support should be
|
|
considered experimental and you shouldn't rely on it. It *could* trash
|
|
your XBEL bookmarks file so make regular backups.
|
|
|
|
To use the XBEL format, set 'bookmarks.file_format' to 1.
|
|
|
|
Usage hints
|
|
^^^^^^^^^^^
|
|
|
|
As already noted above, probably the best usage pattern is to use XBEL for
|
|
importing/exporting your bookmarks to/from ELinks and the native format for
|
|
regular operation. Of course, if you want to synchronize your bookmarks in
|
|
ELinks and some other XBEL-supporting gadget and you are brave, you can use
|
|
XBEL as your exclusive bookmark format - the choice is upon you.
|
|
|
|
Regarding the bookmarks synchronization, there is one important note. ELinks
|
|
saves your bookmarks each time you added one through the 'a' shortcut
|
|
(add-bookmark action) or when closing the bookmarks manager if you made any
|
|
changes or when quitting ELinks. However, ELinks reads your bookmarks only
|
|
*ONCE*, during the startup. This behaviour may change in the future (tell us
|
|
if you need a way for ELinks to re-read the bookmarks file), but this is how
|
|
it is done now.
|
|
|
|
Actually, you may now ask "So how do I convert bookmarks between the two
|
|
formats?". It is quite easy. ELinks simply follows the current value of
|
|
'bookmarks.file_format' whenever loading/saving the bookmarks.
|
|
|
|
So, e.g. if you normally use the native format but you want the bookmarks to
|
|
be saved in the XBEL format once, change 'bookmarks.file_format' to 1, then
|
|
cause the bookmarks to be resaved (e.g. by doing some simple change, like
|
|
adding a trailing space to some bookmark's title or so), then change the
|
|
'bookmarks.file_format' value back to 0.
|
|
|
|
It is a little more complicated if you normally use the native format but you
|
|
want to import bookmarks from the XBEL format once. You again change
|
|
'bookmarks.file_format' to 1, then cause the bookmarks to be reloaded. That
|
|
involves saving the configuration, quitting ELinks _completely_ (that means
|
|
closing/killing all instances of it you have running), then restarting it and
|
|
changing 'bookmarks.file_format' to 0. Then save the configuration again and
|
|
cause ELinks to resave the bookmarks.
|
|
|
|
Agreed, this all strange dances are quite clumsy, likely some simple
|
|
wizard-like interface for switching the bookmarks formats will be introduced
|
|
in the future. So far, we have had no reports from our users that anyone wants
|
|
to switch their bookmarks format frequently, so this is not too high on our
|
|
TODO list. So be sure to tell us if you would like this process to be
|
|
simplified rather sooner than later.
|