Debian Codegraph @

doc/README

raw ◀ ▶
1 Debian patch touch this file
1 netrik 1.16.1 (beta)
2 >====================<
3
4
5 _What it is_ (INTRODUCTION)
6
7 Netrik is the ANTRIK Internet Viewer/Browser/Explorer/Navigator/whatever. (Tell
8 us which one you like best :-) )
9
10 Netrik is Free Software published under the GNU GPL; see LICENSE for details.
11
12 If you haven't already done so, you may want to take a look at the SourceForge
13 page at http://netrik.sourceforge.net , where you can read extensive
14 discussion on topics like: What it is all about; why it is there; how it
15 developes; what features are intended; why we consider it necessary etc.
16
17 For short, netrik intends to be a really fancy text mode WWW browser (somewhat
18 similar to lynx, links, w3m -- only better ;-) ). Well, that's the plan.
19 Presently it's rather simple; but has quite a number of unique features
20 regarding user interface, HTML presentation and others.
21
22
23 _What is new_ (CHANGES)
24
25 The 1.16 release adds the new command 'l'. This will enter a special mode, in
26 which every link on the active screen area gets a unique label (one or two
27 letters) assigned, and the user can then type these letters to immediately
28 follow the respective link. (The idea is borrowed from Vimperator, and
29 implemented in netrik by Evan M. Gates.)
30
31 Note that this feature is considered experimental: It might be changed or
32 entirely replaced by other commands for the same use case in the future.
33
34 1.16.1 uses ncursesw instead of ncurses, which makes utf8 work somewhat again.
35 (Not properly, but back to the partially-broken state it was in before.)
36
37 See NEWS for changes in previous releases.
38
39
40 _Where it runs_ (SYSTEM REQUIREMENTS)
41
42 Netrik is developed and tested under GNU/Linux and GNU Hurd. However, for now
43 it doesn't use a lot of stuff specific to GNU. It might require some tweaking,
44 but should not be too hard to make it work on other UNIX-like systems. There
45 are reports of running some older versions on FreeBSD and Solaris, for example.
46 In short: Good luck ;-)
47
48 Specifically, it depends on the ncurses library and GNU getopt. GNU readline
49 and history libraries can be used for fancy command prompt editing. See
50 TROUBLESHOOTING below for more details.
51
52 For viewing pages on FTP servers, or if you don't want to use the builtin HTTP
53 handling, you also need to have GNU Wget installed. (Of course you can replace
54 it with your favourite HTTP loader, by using --with-wget-call=... option to
55 configure.)
56
57 Viewing compressed (local) files requires gzip and/or bzip2 installed.
58
59
60 _How to use_ (INSTALL)
61
62 Installation is triggered by the typical command sequence:
63
64 ./configure && make && make install
65
66 in the netrik directory. (If you got netrik from CVS, you'll have to do
67 "autoreconf -i" first.)
68
69 In the case some of the commands fails without printing a useful diagnostic
70 message, please send a bug report. (See _Bugs_.)
71
72 All installation steps should work automatically; no user interaction is
73 necessary. However, you may want to set some options influencing important
74 features of the program. Use
75
76 ./configure --help
77
78 to find out what options are available.
79
80 Some details of the compiling process can also be influenced by make variables,
81 e.g.
82
83 CC=gcc-3.0 ./configure
84
85 Especially LDFLAGS and CPPFLAGS may be useful, to give the location of a
86 library and its headers if it resides in an unusual place.
87
88 The installation process should be straightforward, if you have all necessary
89 libraries installed. See _Why it fails_ below if you run into trouble.
90
91
92 For DEBIAN USERS, installation is even simpler: Just use the command
93
94 debuild -b -us -uc
95
96 in the unpacked source directory, and then install the resultig package with
97
98 dpkg -i ../netrik_*.deb
99
100 (Assuming you have no other .deb matching the wildcard already lying about;
101 use the shell's <tab>-completion feature to get the correct file name.)
102
103
104 _What you can do with it_ (USAGE)
105
106 Well, netrik implements most all basic browser functionality now, so you can do
107 the same as with any other browser -- read local HTML files, browse the web.
108 (There are some limitations however: No file save/download, no cookies, no
109 SSL.)
110
111 The most typical use would be invoking with just the name of some local file or
112 with some HTTP URL as argument (you can usually leave out the "http://"), which
113 will load the resource and startup in interactive browser mode.
114
115 Use 'j' and 'k' to scroll the page, up and down arrows (or uppercase 'J' and
116 'K') to select links, and the return key to follow a link. (There are many more
117 link selection commands; you may for example prefer using a combination of
118 '+'/'-' and <tab>/'p' instead of 'J' and 'K'. See doc/keys.html or doc/keys.txt
119 for a complete listing.)
120
121 See "man netrik" and/or the various documentation files in doc/ for other
122 invocation methods, command line options, and more browser commands.
123
124 Netrik may also be quite useful for a quick test of HTML files (using --debug)
125 -- it should complain about almost all syntax errors. (The man page has an
126 example.)
127
128
129 _Why it fails_ (TROUBLESHOOTING)
130
131 INSTALLATION (especially on non-GNU systems) often fails because some libries
132 are missing:
133
134 If you want to have fancy command line editing in netrik, you need a shared
•135 library version of the GNU Readline library, and the development files
136 (headers) going with it. If using GNU/Linux, your distribution should provide a
137 package named something like "libreadline-dev"; some distributions fail to do
138 so, however. In that case you can get the source (from your distribution or
139 from ftp://ftp.gnu.org/gnu/readline/ ) and compile it with "make shared" and
140 "make install-shared".
141
•142 You also need the ncurses development files. (These are mandatory.) Your
143 distribution should provide a "libncurses-dev" package (or something similar);
144 some distributions have only one "ncurses" package providing both the library
•145 and the development files.
146
147 On FreeBSD, the GNU Getopt port (libgnugetopt) needs to be installed.
148
149 STARTUP often causes trouble because of a wrong terminal setting: As netrik
150 normally uses text colors excessiveley, it complains if it can't use colors.
151 Thus, your $TERM environment variable needs to be set to some color terminal
152 type in order to run netrik; e.g. "linux", "xterm" or "ansi", but not "linux-m"
153 or "vt100".
154
155 Note: On some systems, the "xterm" terminal definition also doesn't contain the
156 color settings; if it fails with just "xterm", try "xterm-color" instead.
157
158 Netrik can also run in a (very crude) monochrome mode now. If you actually have
159 a monochrome terminal, you can avoid the warning about colors on each startup:
160 Use the --bw option on the command line, or put it into your ~/.netrikrc. (See
161 doc/config.txt or doc/config.html for details.)
162
163
164 _Keeping in Touch_ (MAILING LIST)
165
166 As of course you are very interested in netrik ;-), you may want to subscribe
167 to the mailing list. Probably not all messages will be of interest to you, but
•168 you will have a good overview on current netrik development.
169
170 To subscribe, either send a mail to
171 [email protected] with the word "subscribe" as
172 subject, or go to http://lists.sourceforge.net/lists/listinfo/netrik-general .
173
174 Again, you can go to the project homepage at http://netrik.sf.net and find
175 lots of information there. (Both topical and general.)
176
177
178 _How it works_
179
180 Netrik consists basically of three big modules: The layout engine, the
181 file/HTTP loader, and the pager. However, these aren't clearly separated, but
182 closely interlocked; especially the loader is coupled very tighly to the layout
183 engine, or one might say: built around it.
184
185 Of these three, the layouting is the biggest and probably most interesting part
186 -- while the others consist of bunch of specific solutions for all the
187 different aspects of their functionality, the layout engine has quite a clear
188 generic design:
189
190 The whole layouting is done by a series of simple processing steps applied one
191 after the other, each one generating a new data structure from the output of
192 the previous one.
193
194 The first step (parse-syntax.c) reads the input stream (using load.c), and
195 creates a syntax tree, which contains all the elements (HTML tags) as well as
196 the content (the text between the tags) assigned to each element.
197
198 The next step (parse-elements.c) looks up the element names -- which were
199 stored as strings up to now -- in a table, and assigns enumerated numbers to
200 each one, to faciliate further processing.
201
202 An additional pass is used now to fix the broken tree that is created by the
203 syntax parser with SGML documents. (Containing unclosed elements.)
204
205 The third step (parse-struct.c) is the central part of the process: The syntax
206 tree, which is a representation of the file stucture, is converted to a
207 structure tree, which is a representation of the page as it appears on the
208 screen. It contains one item for each thing visible on the page, like text
209 blocks, blank lines, boxes etc.
210
211 The fourth step (pre-render.c) places the items on the page. From the sizes of
212 the items it determines at which coordinates inside the page every single item
213 will be displayed. It also generates a page allocation map, allowing for fast
214 lookup which items are present at a certain page position.
215
216 After all these preparation passes, the interactive viewer (pager.c) is called.
217 Every time the visible page area changes, it uses render.c to display the new
218 region, according to the information from the item tree generated before.
219
220 See doc/hacking.txt or doc/hacking.html for a more in-depth discussion.
221
222
223 _Dumps_
224
225 If invoked with the "--debug" option, netrik prints lots of additional
226 information while loading/layouting the page, before the pager is (re)started.
227 Most every program part generates some messages, which are often (more or less)
228 self-explanatory; however, by far the most -- and most interesting -- dumps are
229 generated by the layout engine:
230
231 While parsing the syntax, every parsed character is dumped. If a parsing error
232 occurs (or something worse, like segmentation fault), the last character dumped
233 is the one which caused the problem. (The same is already done while parsing
234 the HTTP header, if loading by HTTP.)
235
236 After syntax parsing has finished, the whole parse tree is dumped. It may be a
237 bit confusing, as a node's text is printed *before* a node, not after it, as
238 one may expect. (The representation of the syntax tree is quite different from
239 W3C DOM: Instead of a mix of child element nodes and text nodes, a parent node
240 contains *only* a list of child nodes; the text content is always stored with
241 the next child node...) The reason is that the nodes stores the text that comes
242 before it in the document, not after it, so dumping it after it would be even
243 more confusing.
244
245 After parse-elements.c and sgml.c have finished, the tree is dumped again, but
246 this time the element and attribute names are not printed in their textual
247 representation from the document, but instead looked up from a table of known
248 facilities. Also, this second tree dump happens after the SGML fixing, as
249 opposed to the first. Dummy elements (for storing text content that can't be
250 assigned to any real child) are indicated by a question mark, and the global
251 element (tree top) by an exclamation mark.
252
253 After parse-struct.c and pre-render.c have finished, the resulting item tree is
254 dumped. The coordinates assigned by pre-render.c for each item are printed, and
255 the text strings of text items are dumped in the correct colours. Links and
256 anchors are also listed for each text item.
257
258 Again, see doc/hacking.txt for a more thorough description.
259
260
261 _Benchmarks_
262
263 I've decided that it's time to repeat the benchmarks, for at least three
264 reasons: First of all, much time has passed since I last compared, and many
265 browsers are available in new Versions. (Especially the graphical ones.)
266
267 Then, I realized that some browsers (links, and especially Netscape4) behave
268 considerably different when loading local files than when loading via HTTP.
269 This time I've compared HTTP speed, as this is more realistic...
270
271 Finally, to allow a more useful comparision between the text based and the
272 graphical browsers, I've removed all image references from the test files.
273
274 The most important obeservation was that links needs additional time to load
275 from HTTP. (The amount of time doesn't depend on the document contents, but
276 fluctuates.) For simple documents, this is quite considerable: The loading time
277 is up to about twice as long as for local files. That's why this time netrik,
278 w3m and links all had very similar results. (Sometimes links was faster,
279 sometimes netrik.) Lynx was still much slower. (It doesn't seem to scale well
280 with big files...)
281
282 The difference to the graphical browsers wasn't that big this time. When
283 loading local files, Netscape was nearly as fast as netrik/w3m/links, for most
284 files. (For files with tables, it was actually much faster then the
285 table-enabled text mode browsers links and w3m.)
286
287 However, it exposes a very strange behaviour when loading from HTTP: For very
288 simple HTML files, it gets *much* slower; but with the more complicated files,
289 it was still super-fast...
290
291 Opera is also gotten much better, and is sometimes nearly as fast as Netscape
292 with local files now. Due to Netscape's anomaly with simple files, it's
293 sometimes even faster over HTTP.
294
295 Mozilla is also gotten faster, but is still very much slower than Netscape or
296 even Opera.
297
298 Note: The tests were done with a couple of very large files (1 MB), so they
299 only measure pure HTML parsing (and HTTP loading) speed, but no response times
300 in realistic circumstances...
301
302
303 _Feedback_
304
305 If you just want to tell us that you love netrik (of course you do :-) ), or if
306 you think our code is inefficient, or if you do not like our arrogant tone, or
307 if you found some bug, or if you think netrik is ugly and useless, or if you
308 don't like our indentation, or if you found typos somewhere, or if you think
309 our comments are cryptic, or if you think something could be done better, or if
310 you have a suggestion for some feature, or if you want to know something, or if
311 your cat likes watching you using netrik -- in short, if ever you feel the
312 irresistable desire to tell us something: Do so! :-)
313
314 Send an e-mail to [email protected] . Keep in mind that this
315 is a public mailing list, and everyone can look at the archives. If you prefer
316 a more "personal" way, you can also mail the maintainer (which happens to be
317 me): [email protected]
318
319
320 _Contribute_
321
322 If you want the fame of participating in the greatest project of the new
323 millenium ;-), or if you just feel obliged to return something to netrik for
324 all the happy hours you spent with it :-), or maybe if you simply want to see
325 your favourite feature implemented as soon as possible: Start by subscribing to
326 the mailing list. (s.a., _Keeping in Touch_) It's that simple. Really. (You may
327 want to introduce yourself after subscribing -- but we don't insist :-) )
328
329 If you want to start hacking right away, a glance at the ToDo file should give
330 you some ideas.
331
332
333 _Bugs_
334
335 Netrik is still far from complete, and many things won't work. However, all
336 features that are implemented should work correcty -- so if you find some bug,
337 don't hesitate to report it; send an e-mail. Again, the address is
338 [email protected]