| 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 developement 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 developement 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 developement 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 developement. |
| 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] |