  netrik 0.15
>=============<

_What it is_

Netrik is the ANTRIK Internet Viewer/Browser/Explorer/Navigator/whatever. (Tell
us which one you like best :-) )

Netrik is Free Source Software published under the GNU GPL; see LICENSE for
details.

If you haven't already done so, you may want to take a look at the SourceForge
page at http://netrik.sourceforge.net/ , where you can read extensive
discussion on topics like: What it is all about; why it is there; how it
developes; what features are intended; why we consider it necessary etc.

For short, netrik is a really fancy text mode WWW browser (somewhat similar to
lynx, links, w3m -- only better :-) ), having all possible features making
sense in text mode -- including multi-windowing and JavaScript; and with a
really nice UI. Well, strictly speaking, it will be...

_What is new_

Most form control types are now supported. ("textarea" and "file" are still
missing, though.) A couple of big and little bugs has been fixed also.

All in all, the form support can be considered really useful now :-) Major
problem is that still no "POST" submit method is implemented.

See NEWS for changes in previous releases.

_Where it runs_

Netrik is developed and tested under GNU/Linux. It doesn't use anything
specific for Linux, though; thus it should also compile on any other Unix-like
operating system. However, you may need to get some libraries that aren't
typically available on non-GNU systems; some changes/enhancements to
configure.in may also be necessary. Just try it out and let us know if it works
:-)

For viewing pages on FTP servers, or if you don't want to use the builtin HTTP
handling, you also need to have GNU Wget installed. (Of course you can replace
it with your favourite HTTP loader, by changing the command in configure.in)

Netrik used to work on FreeBSD; this will need to be re-implemented for the new
build system, however. (Your help is welcome :-) )

_How to use_

Installation is triggered by the typical command sequence:

   ./configure
   make
   make install

in the netrik directory. (If you got netrik from CVS, you'll have to do
"aclocal && autoheader && autoconf && automake -a" first.)

In the case some of the commands fails without printing a useful diagnostic
message, please send a bug report. (See _Bugs_.)

All installation steps should work automatically; no user interaction is
necessary. However, you may want to set some options influencing important
features of the program. Use

   ./configure --help

to find out what options are available.

If using a terminal with dark background (or any terminal if using the
--force-colors option), you probably want to copy colors.default.c to colors.c.
(These colors look better on dark background, but they are unusable on light
background.)

Some details of the compiling process can also be influenced by make variables,
e.g.

   CC=gcc-3.0 ./configure

Especially LDFLAGS and CPPFLAGS may be useful, to give the location of a library
and its headers if it resides in an unusual place.

If you want to have fancy command line editing in netrik, you need a shared
library version of the GNU Readline library, and the developement files
(headers) going with it. If using GNU/Linux, your distribution should provide a
package named something like "libreadline-dev"; some distributions fail to do
so, however. In that case you can get the source (from your distribution or
from ftp://ftp.gnu.org/gnu/readline/ ) and compile it with "make shared" and
"make install-shared".

You also need the ncurses developement files. (These are mandatory.) Your
distribution should provide a "libncurses-dev" package (or something similar);
some distributions have only one "ncurses" package providing both the library
and the developement files.

On FreeBSD, the GNU Getopt port (libgnugetopt) needs to be installed.

After installing, simply run netrik with the file name or HTTP URL of an HTML
file as argument.

Note: As netrik doesn't support monochrome terminals yet, your $TERM
environment variable needs to be set to some color terminal type in order to
run netrik; e.g. "linux", "xterm" or "ansi", but not "linux-m" or "vt100".

_What you can do with it_

You can run:

   netrik <url>

where <url> is a local file or an HTTP URL. (When no "http://" is given, but no
local file with the given name is found, HTTP is automatically assumed.)

The page is loaded and displayed in the builtin pager. (See doc/keys.txt or
doc/keys.html for instructions on using the pager.) Alternatively, you can dump
the whole page without using the pager, by giving the "--dump" option upon
invocation.

You can select the links in the page using capital "J" and "K" (or cursor
keys), and follow the selected link by pressing <return>. The new page is
loaded and displayed in the pager. See the files in doc/ for more usage
instructions.

Netrik is quite nice for browsing local documentation. With the new error
handling, it is also already useful for web browsing; however, this is still
limited due to missing features. (Especially form handling.)

It may also be quite useful for a quick test of HTML files (using --debug) --
it should complain about almost all syntax errors.

_Keeping in Touch_

As of course you are very interested in netrik ;-), you may want to subscribe
to the mailing list. Probably not all messages will be of interest to you, but
you will have a good overview on current netrik developement.

To subscribe, either send a mail to
netrik-general-request@lists.sourceforge.net with the word "subscribe" as
subject, or go to http://lists.sourceforge.net/lists/listinfo/netrik-general .

Again, you can go to the project homepage at http://netrik.sf.net/ and find
lots of information there. (Both topical and general.)

_How it works_

To faciliate fast developement and easy changes, the structure is kept very
simple for now. The whole layouting is done by a series of simple processing
steps applied one after the other, each one generating a new data structure
from the output of the previous one.

The first step (parse-syntax.c) reads the input stream (using load.c), and
creates a syntax tree, which contains all the elements (HTML tags) as well as
the content (the text between the tags) assigned to each element.

The next step (parse-elements.c) looks up the element names -- which were stored
as strings up to now -- in a table, and assigns enumerated numbers to each one,
to faciliate further processing.

An additional pass is used now to fix the broken tree that is created for SGML
documents. (Containing unclosed elements.)

The third step (parse-struct.c) is the central part of the process: The syntax
tree, which is a representation of the file stucture, is converted to a
structure tree, which is a representation of the page as it appears on the
screen. It contains one item for each thing visible on the page, like text
blocks, blank lines, boxes etc.

The fourth step (pre-render.c) places the items on the page. From the sizes of
the items it calculates at which coordinates inside the page every single item
will be displayed. It also generates a page allocation map, allowing for fast
lookup which items are present at a certain page position.

After all these preparation passes, the interactive viewer (pager.c) is called.
Every time the visible page area changes, it uses render.c to display the new
region.

See doc/hacking.txt or doc/hacking.html for a more in-depth discussion.

_Dumps_

If invoked with the "--debug" option, before the final page is displayed there
are some additional dumps:

While parsing the syntax, every parsed character is dumped. If a parsing error
occurs (or something worse, like segmentation fault), the last character dumped
is the one which caused the problem.

After syntax parsing has finished, the whole parse tree is dumped. It may be a
bit confusing, as a node's text is printed *before* a node, not after it, as
one may expect. This however makes sense, because it's actually the content
occuring *in front of* the element. It's probably less confusing than as if it
would be printed after the node, although it was in front of the node in the
HTML file...

After parse-elements.c and sgml.c have finished, the tree is dumped again, but
this time the element and attribute names are looked up from a table by the
assigned enum numbers. Dummy elements are indicated by a question mark, and the
global element (tree top) by an exclamation mark.

After parse-struct.c and pre-render.c have finished, the resulting item tree is
dumped. The coordinates assigned by pre-render.c for each item are printed, and
the text strings of text items are dumped in the correct colours. Links are also
listed for each text item.

Again, see doc/hacking.txt for a more thorough description.

_Benchmarks_

Feeding netrik and other browsers with five different HTML-files of about 1 MB
each, exhibited some very intersting results: Even in the present, totally
unefficient implementation, netrik was faster than lynx and old versions of
w3m, and about as fast as the present w3m. It was quite slow compared to links,
though. Memory usage is between two and three times lower than old w3m and
links, but about twice as high as lynx. (The new w3m need another 60% more...)

The results with the two files containing tables are not representative. Of
course, w3m and links were much slower than with tableless files -- they
actually render the tables... As expected, lynx was still slower than netrik. 

The speed of the pager is harder to measure. w3m exhibits a strong delay when
scrolling pagewise, and lynx a small one. With links and netrik, there is no
delay on my box. (Does anyone have a slower box than a Pentium 166?...)

We are really curious what the results will be when netrik will have tables
(and other slow things) implemented...

The "big" graphical browsers were all slowass -- Netscape4, Opera, Mozilla.
Exactly in that order. (Yes, Netscape4 *was* faster than Opera. For simple
files without tables even very much faster. I wonder where the legend of Opera
being fast came from. Probably they created it themself. Nice marketing...)

_Feedback_

If you just want to tell us that you love netrik (of course you do :-) ), or if
you think our code is inefficient, or if you do not like our arrogant tone, or
if you found some bug, or if you think netrik is ugly and useless, or if you
don't like our indentation, or if you found typos somewhere, or if you think
our comments are cryptic, or if you think something could be done better, or if
you have a suggestion for some feature, or if you want to know something, or if
your cat likes watching you using netrik -- in short, if ever you feel the
irresistable desire to tell us something: Do so.

Send an e-mail to netrik-general@lists.sourceforge.net . Keep in mind that this
is a public mailing list, and everyone can look at the archives. If you prefer
a more "personal" way, you can also mail the project admin (which happens to be
me): antrik@users.sourceforge.net

_Contribute_

If you want the fame of participating in the greatest project of the new
millenium ;-), or if you just feel obliged to return something to netrik for
all the happy hours you spent with it :-), or maybe if you simply want to see
your favourite feature implemented as soon as possible: Just subscribe to the
mailing list. (s.a., _Keeping in Touch_) It's that simple. Really. (You may
also introduce yourself after subscribing, but you needn't.) If you want to
start right away, a glance at the ToDo file should give you some ideas.

_Bugs_

Netrik is still far from complete, and many things won't work. However, all
features that are implemented should work correcty -- so if you find some bug,
don't hesitate to report it; send an e-mail. Again, the address is
netrik-general@lists.sourceforge.net
