iconv: Bail out of the loop when an illegal sequence of bytes occurs.
[elinks/elinks-j605.git] / doc / marks.txt
blobe02e2fe0b58f4ecc3ffcbc347a6be44f4396657a
1 Marks (the lite edition)
2 ------------------------
4 So, were you ever reading this huge 300-pages specification heavily
5 cross-referencing itself, jumping around and getting a headache when looking
6 for the place where you stopped reading the last time?
8 Were you doing something similar in C code, but praising *vi* for document
9 marks?
11 ELinks can do them, too! For vim non-users:
14 What it is?
15 ~~~~~~~~~~~
17 When you place a "document mark" (just "mark" from now on), you place an
18 _invisible_ anchor at the current position in the document. You can place
19 several such marks --- each mark is identified by a single character (any
20 reasonable character will do). Then, you can just happily browse around
21 aimlessly (but see below) and when in the same document again, you can
22 return to any of the marks in the file again. That will restore your
23 position in the file at the time of placing the mark.
25 You can place a mark by the "m" key followed by the mark character. You can
26 go to a mark by the "'" (apostrophe) key followed by the mark character.
27 E.g., you can place a mark named "a" in the file by pressing "ma", then
28 return to it anytime later by typing "'a". You can of course change those
29 shortcuts at any time to anything you wish in the keybindings manager.
31 Short summary: you can place a mark (e.g. 'z') in a document by pressing
32 "mz" and then go back to it anytime later by pressing "'z".
35 Restrictions
36 ~~~~~~~~~~~~
38 Currently, only A-Za-z characters are valid marks.
40 Only one mark named "a" (or anything else) may exist at a time, so if one
41 puts a mark "a" in a first document and set another mark "a" in a second
42 document, ELinks will simply replace the former one.
44 ALL the document marks are always local to the document. I.e. the vim text
45 editor has an extension that makes the capital-letter marks to be global to
46 the whole program and going to such a mark will make it to open the right
47 document. This is not implemented in ELinks _yet_.
49 Contrary to vim, ELinks doesn't support numbered marks (jumping to the last
50 n documents in history) nor the special "'" mark (jumping to the last mark).
51 Yet.
53 There is no way to get a listing of all marks set in a document.  Yet.
56 Marks lifespan
57 ~~~~~~~~~~~~~~
59 I already hinted something about another restriction regarding aimless
60 browsing. The lifespan of document marks depends on rather ill-defined and
61 (for an average mortal) mostly non-deterministic technical conditions.
63 Generally, marks _always_ survive when not moving away from the document or
64 when moving only in the session history (and unhistory). That means, if you
65 go back and the "unback" to the document, you will find your marks safely in
66 place. If you follow a link from the document (or typed an address to the
67 Goto URL dialog) and then go back (by pressing the right arrow or through
68 the File menu), your marks are safe too. These are in fact by far the most
69 common usage cases for the marks, so most of the time it will just work as
70 you expect.  That's a good news.
72 The bad news is that in all other cases, nothing is guaranteed.  It might
73 work if you get back to the document by any other means (by following some
74 link or typing its address to the Goto URL dialog), or it might not. It
75 might be possible to achieve two instances of the document inside a single
76 ELinks, each with its own set of marks. However, again, generally it will
77 work as expected - this paragraph serves only as a disclaimer in cases it
78 doesn't.  Don't rely on it.
80 Marks never survive over ELinks restarts. If you quit your ELinks completely
81 and run it again, the marks you placed will be no more. No exceptions. Well.
82 In some cases, it *might* appear that they survived, but that just means you
83 did not quit your ELinks _completely_ --- if you run multiple ELinks
84 instances under a single user on a single system, they "join" together and
85 you must quit (or kill) them all to get rid of the damn thing.  But that's a
86 different story.