Debian Codegraph @

doc/hacking-pager.html

raw
1 <html>
2 <head>
3 <title>netrik hacker's manual: pager</title>
4 </head>
5 <body>
6
7 <h1 align="center">netrik hacker's manual<br />>========================&lt;</h1>
8
9 <p>
10 [This file contains a description of the viewer module. See hacking.txt or
11 <a href="hacking.html">hacking.html</a> for an overview of the manual.]
12 </p>
13
14 <h2>Pager Operation</h2>
15
16 <p>
17 As the pager doesn't just follow a static algorithm, but has to react to
18 certain events (keyboard input), the structure is somewhat harder to retrace.
19 </p>
20
21 <p>
22 The central pager function is <a href="#display">display()</a>,
23 which contains the main loop (keyboard dispatcher) which performs some
24 action(s) on each keypress, as well as the interface to main().
25 </p>
26
27 <p>
28 These actions directly performed by the keyboard commands mostly do not have a
29 direct visible effect; instead, they alter the pager state, which becomes
30 visible with the next screen update -- this is performed in each main loop
31 iteration before waiting for the next keypress. Some actions also require
32 temporarily exiting the pager and returning to main(), which is fairly easy and
33 transparent, as the pager state is stored directly in the
34 <a href="hacking-page.html#pageStruct">page structure</a> and the
35 screen contents thus can be easily restored when reentering the pager.
36 </p>
37
38 <p>
39 The pager state consists of three basic components: "pager_pos" is the line
40 number (in page) of the first line visible on the screen. "active_link"
41 contains the link number of the currently selected link. (Or -1 if none.)
42 "cursor_x" and "cursor_y" tell where the cursor is on the page. (Not the
43 screen!) The additional "sticky_cursor" flag allows keeping the cursor in its
44 place while scrolling (if possible), instead of moving it to the screen top.
45 </p>
46
47 <p>
48 Each of the major parameters is manipulated chiefly by one function:
49 <a href="#scrollTo">scroll_to()</a> sets "pager_pos",
50 <a href="#activateLink">activate_link()</a> sets "active_link",
51 and <a href="#setCursor">set_cursor()</a> sets the cursor position
52 (and also manages the "sticky_cursor" status). The variables aren't
53 independent, however -- scroll_to() may need to deactivate the active link if
54 it moved off the screen, and often move the cursor; activate_link may need to
55 scroll if the link is presently not an the screen, and always has to set the
56 cursor position; set_cursor() has to deactivate any previously active link, and
57 also scroll if the desired cursor position is outside the current screen. This
58 interrelation requires the functions calling each other in a quite complicated
59 manner, sometimes even recursively... Maybe we should try to write a generic
60 function for updating all the states at once by a single request.
61 </p>
62
63 <p>
64 Note that scroll_to() and activate_link() do not only set the state, but also
65 (re)render the visible page part (using
66 <a href="hacking-layout.html#render">render()</a>, which is
67 described in hacking-layout.*). Probably it would be better to do this in the
68 main loop also. Moreover, activate_link() even modifies the page, which was a
69 very bad idea and surely will be changed in the future.
70 </p>
71
72 <a name="display" id="display">
73
74 <h2>display()</h2>
75
76 <p>
77 The viewer basically consists of a keyboard dispatcher that loops until some
78 command was given that requires some action by main(). These include the quit
79 command, link following, history commands, entering the command prompt, or text
80 search.
81 </p>
82
83 <p>
84 display() tells main() what action is required, by the return value which is an
85 "enum Pager_ret".
86 </p>
87
88 <p>
89 After main() has done it's work, display() will be called again; it will then
90 continue just where it stopped, which is possible because the important pager
91 state information (postion of the currently visible page part, cursor position,
92 currently selected link) are stored in the
93 <a href="hacking-page.html#pageStruct">page structure</a>, which is
94 described under <a href="hacking-page.html#pageList">Page List
95 Handling</a> in hacking-page.*. Thus the way over main() is quite
96 seemless; to the user it usually looks as if he was in the pager all the time.
97 </p>
98
99 <p>
100 To allow for this, display() needs to do some work to restore the state upon
101 startup.
102 </p>
103
104 <p>
105 First, the page is scrolled to the previous position, using
106 <a href="#scrollTo">scroll_to()</a>. "old_line" is set to
107 PAGE_INVALID (meaning the pager presently displays nothing) before scrolling,
108 so that the screen contents always will be drawn completely anew.
109 </p>
110
111 <p>
112 Afterwards, the cursor position is set to the saved one using
113 <a href="#setCursor">set_cursor()</a>. Note that the position
114 has to be stored before scroll_to(), as this function might move it out of the
115 screen and adjust the cursor, in case a new cursor position was requested. (By
116 a text search.)
117 </p>
118
119 <p>
120 Finally, if there is a selected link, it is (re)activated with
121 <a href="hacking-links.html#activateLink">activate_link()</a>
122 (described in hacking-links.*). The active link also has to be saved before
123 scroll_to(), as the link position may have changed in the meantime, causing
124 scroll_to() to deactivate the previouly selected link if it is no longer on the
125 screen.
126 </p>
127
128 <p>
129 Reactivating the link is omitted when the pager is restarted after a text
130 search command ("search.type" is set) -- in this case the cursor position has
131 higher priority and is not to be overwritten.
132 </p>
133
134 <p>
135 Initialization is slightly different if an anchor was activated, which is
136 indicated by "page->active_anchor" being set. In this case, instead of callig
137 scroll_to() directly,
138 <a href="hacking-links.html#activateAnchor">activate_anchor()</a>
139 (also described in hacking-links.*) is used. This one also scrolls (but to the
140 anchor position, not the previous pager position), and additionally draws the
141 anchor marks.
142 </p>
143
144 <p>
145 After completing these initalizations, the keyboard input loop is entered,
146 which reads one character in each iteration (note that the mvgetch() fuction
147 used for that also updates the curses screen), and then dispatches to the
148 requested command in a big switch.
149 </p>
150
151 <p>
152 The cursor position (passed to mvgetch()) is determined from
153 "page->cursor_[xy]", which are page coordinates, and have to be transformed to
154 screen coordinates first.
155 </p>
156
157 </a> <!-- display -->
158
159 <h2>Scrolling Commands</h2>
160
161 <p>
162 The scrolling commands are all implemented by simple calls to scroll_to() with
163 different parameters. All relative movement commands can simply add or subtract
164 a constant number of lines to move, as scroll_to() checks for the page
165 boundaries.
166 </p>
167
168 <a name="scrollTo" id="scrollTo">
169
170 <h3>scroll_to()</h3>
171
172 <p>
173 This function scrolls the visible page area to the desired position. It moves
174 (or deletes) the screen content, and repaints newly visible areas using
175 <a href="hacking-layout.html#render">render()</a> (see
176 hacking-layout.*).
177 </p>
178
179 <p>
180 It is called with the desired new position as argument. This position is
181 described by the line number, of that line of the output page which is
182 displayed in the first screen line.
183 </p>
184
185 <p>
186 First the desired new position is checked to be in the valid range.
187 </p>
188
189 <p>
190 If it is greater than the page length minus one screenwidth, it is set to that
191 value. (The last page line can't move above the bottom screen line this way.)
192 </p>
193
194 <p>
195 If smaller then zero, it is set to zero. (The page top can't move below the
196 screen top.) Note that this will undo the above check, if the output page is
197 smaller than one screenfull -- in this case, the page end is always above the
198 screen end.
199 </p>
200
201 <p>
202 Now that we know the real destination position, the difference to the present
203 position (stored in the static "old_line") is calculated.
204 </p>
205
206 <p>
207 If the absolute value of that difference is not more than a screenfull,
208 scrolling is used. This is done by the insdelln() curses function, called with
209 the cursor being in the first screen line. (Called with a negative value it
210 deletes lines, causing the screen contents to scroll up; called with a positive
211 argument, it inserts lines, causing the screen contents to scroll down.)
212 </p>
213
214 <p>
215 After scrolling, the new lines revealed at the top or bottom of the screen need
216 to be rendered. After scrolling down (negative "scroll_lines"), the first
217 "scroll_lines" of the screen have to be repainted. This is done by calling
218 render() with "scroll_lines" as the height, 0 as the screen position (the first
219 lines of the screen are repainted), and "new_line" as page position.
220 ("new_line" contains the page position of the first screen line.)
221 </p>
222
223 <p>
224 After scrolling up, the last screen lines have to be repainted. This is done
225 similar. The hight is "-scroll_lines" ("scroll_lines" is negative when
226 scrolling up), the screen position is the screen end minus "-sroll_lines", and
227 the page position is the page position of the first screen line ("new_line")
228 plus the screen position of the rendered area.
229 </p>
230
231 <p>
232 If the difference is too big for scrolling, the whole screen is erased and
233 repainted.
234 </p>
235
236 <p>
237 The first time this function is called, "old_line" has the value PAGE_INVALID
238 (defined as the biggest possible positive int value), indicating that the
239 screen contains nothing valid yet. There is no special handling necessary for
240 this case -- "scroll_lines" gets a very big value, and thus the whole screen is
241 always repainted.
242 </p>
243
244 <p>
245 Finally, the cursor position is updated, if necessary. If the cursor is no
246 longer on the screen (more exactly, inside the active screen area), it is set
247 to the home position with <a href="#setCursor">set_cursor()</a>.
248 If the "sticky_cursor" flag is not set, the cursor is always homed.
249 </p>
250
251 </a> <!-- scrollTo -->
252
253 <h2>Cursor Movement Commands</h2>
254
255 <p>
256 Just like the scrolling commands, the cursor movement commands are all
257 implemented by single calls to a specific function (set_cursor()) with the
258 desired new position, which is calculated from the current one.
259 </p>
260
261 <a name="setCursor" id="setCursor">
262
263 <h3>set_cursor()</h3>
264
265 <p>
266 set_cursor() is responsible for setting the cursor to some desired page
267 position (not screen position!). It also sets the "sticky_cursor" flag, so that
268 the cursor will stay in it's place (again, page position) until reset.
269 </p>
270
271 <p>
272 If called with -1 as x and y position, the "sticky_cursor" flag is cleared instead,
273 and the cursor set to the home position -- which is column 0 in the first line
274 inside the active screen area.
275 </p>
276
277 <p>
278 If the requested new position is outside the present active screen area, the
279 page first needs to be scrolled. If the position is before the active screen
280 area, we scroll as many lines back as the position is outside; if it is behind
281 the active area, we scroll as many lines forward.
282 </p>
283
284 <p>
285 Now we test whether the requested position is on the screen, and truncate if
286 not. The y position is actually tested against the page boundaries (after
287 scrolling, those should be equal in case the requested position is outside);
288 only the x position is tested against the screen boundaries, as there is
289 presently no x scrolling.
290 </p>
291
292 <p>
293 Finally, we test whether there is some link at the new cursor position. If
294 there is one, and it wasn't already active, we activate it now. (Using
295 <a href="hacking-links.html#activateLink">activate_link()</a>,
296 see hacking-links.*.) If there was a link active up to now, but there is no
297 link at the new position, the old one is deactivated. (activate_link() does
298 this automatically, as -1 will be passed as the link number in this situation.)
299 </p>
300
301 <p>
302 Only now the cursor is set to the new position, and the sticky status set. (Or
303 reset, if homing.)
304 </p>
305
306 </a> <!-- setCursor -->
307
308 <a name="select" id="select">
309
310 <h2>Link Selection Commands</h2>
311
312 <p>
313 As explained under <a href="#display">display()</a> above, the
314 pager keeps track of the current active link by the "active_link" variable in
315 the "page" struct. (-1 means no link is active.)
316 </p>
317
318 <p>
319 All link selection commands are implemented using a generic link search
320 function to find out which link to activate, and then just activating it with
321 <a href="hacking-links.html#activateLink">activate_link()</a> (see
322 hacking-links.*).
323 </p>
324
325 <a name="findLink" id="findLink">
326
327 <h3>find_link()</h3>
328
329 <p>
330 Finding the link to activate is done with the find_link() function. This
331 function is flexible enough to implement almost all link selection commands
332 with only one invocation.
333 </p>
334
335 <p>
336 find_link() looks for the first link or the last link (depending on
337 "match_type") inside a desired range.
338 </p>
339
340 <p>
341 The search area is primarily specified by the coordinates "start_x", "start_y"
342 and "end_x", "end_y", enclosing a part of the page inside which the links to be
343 considered have to *start*. (As usual, the start coordinates give the first
344 allowed positin, while the end coordinates give the first invalid position.)
345 Note that regardless of the beginning and end positions being given by
346 coordinate pairs, the range is actually linear: It spanns from the start
347 position to the end of the line, includes (in whole) the following lines till
348 "end_y", and concludes with the beginning of the line "end_y" before the end
349 position.
350 </p>
351
352 <p><pre>
353 line zero
354
355 line one with &lt;zeroth link> in it
356
357 line two with &lt;firST LINK> IN IT &lt;-- start_y
358 ^start_x
359 LINE THREE WITH &lt;SECOND LINK> IN IT
360
361 LINE FOUR
362
363 LINE FIVE WITH &lt;THIRD LInk> in it &lt;-- end_y
364 ^end_x
365 line six with &lt;fourth link> in it
366 </pre></p>
367
368 <p>
369 (The second and third links are inside the area, the zeroth, first, and fourth
370 not.)
371 </p>
372
373 <p>
374 There is one additional parameter limiting the search area: "end_line" limits
375 the range where links can *end*. (As usual, it gives the first invalid line.)
376 This is necessary as some commands only activate links that are already inside
377 the screen completely.
378 </p>
379
380 <p>
381 "end_line" or "end_x" and "end_y" can be specified alternatively, or both --
382 only links inside both ranges will be considered.
383 </p>
384
385 <p>
386 If any of the y paramaters ("start_y", "end_y", "end_line") is given as "-1",
387 it is ignored, i.e. the range extends to the end beginning/end of the page. For
388 the x parameters, the behaviour is more complicated: "-1" actually means that
389 the range starts/ends *before* the beginning of the line; thus, "start_x" being
390 -1 means the whole "start_y" line is inside the range, but "end_x" being -1
391 means the whole line is *outside* the range, i.e. only links ending *before*
392 "end_y" are accepted. (Just as with "end_line" and other range ends.) This may
393 look confusing at first, but it is consistent: Giving "end_x" means that the
394 beginning of the "end_y" line is inside the range *additionally* to the lines
395 before "end_y", just as "start_x" means the beginning of the "start_x" line is
396 not inside. If this isn't clear, take another look at the figure above, and
397 imagine what happens when "start_x" and/or "start_y" are moved to the beginning
398 of the line.
399 </p>
400
401 <p>
402 The implemetation of find_link() is actually fairly small, though not simple.
403 </p>
404
405 <p>
406 First, two macros are defined: INSIDE_START() testing whether "link" starts
407 behind the beginning of the range (i.e. whether "start_x" and "start_y" are
408 fulfilled), and INSIDE_END(), which tests the end of the area -- both the end
409 of the link start range ("end_x" and "end_y") and the link end ("end_line").
410 </p>
411
412 <p>
413 The first step is finding the candidate link -- when "match_type" is
414 FIND_FIRST, this is the first link starting after the beginning of the range,
415 and with FIND_LAST the last link before the end of the range.
416 </p>
417
418 <p>
419 The candidate located using a binary search. (Note that "first" and "last" are
420 really only helper variables for the search, just like "mid". The fact that,
421 depending on "match_type", one of those is actually the result, is only a side
422 effect of the search algorithm; but the respective other one is only garbage.
423 You should *not* confuse them for always being the first and last link inside
424 the area -- only one of the bounds is checked in this search!)
425 </p>
426
427 <p><pre>
428 link0 link1 link2 link3 link4
429 start =>| ^candidate
430 </pre></p>
431
432 <p>
433 Now we test whether the candidate is actually a valid link (inside the link
434 number range), i.e. there are *any* links inside the boundary.
435 </p>
436
437 <p>
438 Finally, the other boundary has to be tested.
439 </p>
440
441 <p><pre>
442 link0 link1 link2 link3 link4
443 =>| ^ |&lt;= end
444 |------------->|
445 candidate &lt; end => OK
446 </pre></p>
447
448 <p>
449 (If there are no links inside the range, still a candidate matching the first
450 bound may have been found.)
451 </p>
452
453 <p><pre>
454 link0 link1 link2 link3 link4
455 =>| |&lt;= ^
456 |&lt;----|
457 candidate > end => nothing in range
458 </pre></p>
459
460 <p>
461 If no link matching the criteria was found, find_link() returns -1.
462 </p>
463
464 </a> <!-- findLink -->
465
466 <h3>active_start() and active_end()</h3>
467
468 <p>
469 Cheking whether a link is (or would be) inside the valid screen area for active
470 links, primarily during link selection but also in a few other places, is done
471 using the active_start() and active_end() functions. These simply return the
472 bounds of the valid area (in page coordinates, not screen coordinates!).
473 </p>
474
475 <p>
476 Normally, the area starts in the line that shows up at the screen top (i.e.
477 "pager_pos") plus "cfg.link_margin" -- this is one line below the screen top
478 with the default setting. The end is the last line on screen minus the link
479 margin, accordingly. (But note that active_end returns the number of the *first
480 invalid* line, i.e. *after* the end of the valid area, as all end coordinates
481 are specfied this way!)
482 </p>
483
484 <p>
485 An exception is the pager being at the top (for active_start()) or bottom (for
486 active_end()) of the page -- in this case the valid area includes the first or
487 last page lines, as these can never move into the normal valid area. (The page
488 top can't ever move below the screen top; same for bottom.)
489 </p>
490
491 <p>
492 The "pos" parameter allows specifying some other pager position (relative to
493 the current "page->pager_pos") to check; 0 means using the current position.
494 </p>
495
496 <h3>Command Implementations</h3>
497
498 <p>
499 Thanks to the powerful <a href="#findLink">find_link()</a>
500 function, the commands are actually very simple. Most commands just consist of
501 one call to find_link() to find the new link, and a call to
502 <a href="hacking-links.html#activateLink">activate_link()</a> with
503 the new link number to activate it.
504 </p>
505
506 <p>
507 The simplest commands are those independant of the current cursor position.
508 ('H', 'L', 'M') These just pass a range of line numbers (aquired with
509 active_start() and active_end()) to find_link().
510 </p>
511
512 <p>
513 Many commands however search forward or backward starting from the current
514 cursor position. These just pass the cursor position as the start (for those
515 searching forward) or the end of the search range, respectively. There is one
516 little complication when searching forward: If a link is active already
517 (implying the cursor is at the link start), a search starting with the cursor
518 position will always give the active link again. Thus, "x_start" needs to be
519 incremented by one in this case.
520 </p>
521
522 <p>
523 The other end of the range depends on how far the specific command searches:
524 Some (&lt;tab>, 'p') search till the end of the document, while others ('J', 'K',
525 and also '+' and '-') only to the end of the active screen area, optionally
526 with scrolling one line.
527 </p>
528
529 <p>
530 The latter also have to test whether a link was actually found in the desired
531 area, and just scroll one line with
532 <a href="#scrollTo">scroll_to()</a> otherwise.
533 </p>
534
535 <p>
536 Some commands ('+', '-', '^', ' and '0') do not directly search from the
537 cursor position, but in a range relative to the cursor line. Those are very
538 similar. Two of them are more complicated however:
539 </p>
540
541 <p>
542 '-' is complicated, because it has to find the first link in some range (the
543 previous line having any links), but the beginning of that range isn't fixed --
544 there might be already links in the previous line, but we might also have to go
545 a few lines back. Before we can search for the desired link, we have to find
546 out the line where to search. This is done with another invocation of
547 find_link(), looking for the last link starting before the current line; as
548 this link is obviously in the previous line having links, we can use this
549 link's starting line as the beginning of our search range.
550 </p>
551
552 <p><pre>
553 a line with the &lt;first link>
554
555 a line with the &lt;second link> and the &lt;third link> &lt;-- start_y=new_link->y_start
556 ~~~~~~~~~~~~~goal ^^^^^^^^^^^^new_link (helper)
557 a line with no links
558
559 another line with no links
560
561 a line with the &lt;fourth link> &lt;-- page->cursor_y
562 ^cursor position
563 another line
564 </pre></p>
565
566 <p>
567 '0' is complicated, because -- opposite to all other commands -- it has to find
568 a link *ending* in or after some given line. find_link() has no provision for
569 that; extending it in this way just for this single command would be stupid.
570 </p>
571
572 <p>
573 Thus, we have to use a trick: We first search for the last link ending *before*
574 the current line (so we can use the existing "end_line" parameter), and then
575 just look for the next link -- which is obviosly the first one ending in or
576 after the current line.
577 </p>
578
579 </a> <!-- select -->
580
581 <h2>History Commands</h2>
582
583 <p>
584 The history commands all work alike:
585 </p>
586
587 <p>
588 'b' goes back to the previous page by setting the current position in the
589 history one backwards (decrementing). The page is then (re)loaded by quitting
590 the pager with "RET_HISTORY" -- main() then invokes the necessary actions for
591 loading the page, before restarting display().
592 (<a href="hacking-page.html#loadPage">load_page()</a> and
593 <a href="hacking-load.html#initLoad">init_load()</a> take care for
594 correct loading of pages from history.)
595 </p>
596
597 <p>
598 'f' goes forward in the same manner (incrementing "pos").
599 </p>
600
601 <p>
602 'B' searches the history backwards, until it finds some page that is followed
603 either by one with the "absolute" flag set or by an internal page (the internal
604 page is treated like a new site). If nothing is found the search stops at the
605 first entry in the history, and that one is taken.
606 </p>
607
608 <p>
609 'F' searches forwards, also looking for a page followed by an absoulte URL. The
610 last entry is taken if nothing was found.
611 </p>
612
613 <p>
614 '^r' causes the current page to be reloaded, by returning RET_HISTORY, but not
615 changing the position in the page list. Thus it is not really a history command
616 from the user's point of view -- but technically, it is.
617 </p>
618
619 <p>
620 'r' searches backwards for a page with "mark" set. It also takes the first page
621 if nothing was found; 'R' does the same forwards.
622 </p>
623
624 <p>
625 The marks are set by the 's' command. This one simply sets the "mark" flag of
626 the current "page" structure.
627 </p>
628
629 <h2>Link Following</h2>
630
631 <p>
632 When a link is followed by typing &lt;return>, "RET_LINK" is returned, and the
633 main program follows the current "active_link". This process is described under
634 <a href="hacking-links.html#followLink">main()</a> in
635 hacking-links.*.
636 </p>
637
638 <h2>URL commands</h2>
639
640 <p>
641 The 'u' command causes display() to return "RET_LINK_URL"; main() then shows
642 the URL of the currently active link.
643 </p>
644
645 <p>
646 'c' returns "RET_URL", and main() shows the current page URL.
647 </p>
648
649 <p>
650 'U' returns "RET_ABSOLUTE_URL", causing main() to print the absolute link
651 target URL which is used when the link is actually followed.
652 </p>
653
654 <h2>Other Commands</h2>
655
656 <p>
657 When 'q' is typed the pager simply returns with "RET_QUIT", indicating that the
658 main program should quit also.
659 </p>
660
661 <p>
662 When ':' is typed the pager quits too, but returns "RET_COMMAND"; this means
663 that the main program should enter command mode.
664 </p>
665
666 <p>
667 '/' is very similar: "pager_ret" is set to "RET_SEARCH"; additionally,
668 "search.type" is set to "SEARCH_FORWARD".
669 </p>
670
671 </body>
672 </html>