Documentation update.

1 files changed, 46 insertions, 34 deletions

diff --git a/doc/bird.sgml b/doc/bird.sgml
index ef065012..a1fb863d 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -1,7 +1,7 @@
 <!doctype linuxdoc system>
 
 <!--
-	Bird documentation
+	BIRD documentation
 
     Look for "about this documentation" section to learn more.
 
@@ -13,7 +13,7 @@
 
 <article>
 
-<title>Bird
+<title>BIRD
 <author>
 Pavel Machek <tt/pavel@ucw.cz/
 
@@ -29,15 +29,15 @@ This document contains documentation for BIRD Internet Routing Daemon
 
 <sect>Introduction
 
-<sect1>What is bird
+<sect1>What is BIRD
 
-<p><label id="intro"> You may wonder what 'bird' means. It is acronym of 'BIRD Internet Routing
+<p><label id="intro"> You may wonder what 'BIRD' means. It is acronym of 'BIRD Internet Routing
 Daemon', and we think that's cool name. Its task is similar to what firmware of Cisco routers does,
 or what gated <HTMLURL URL="http://www.gated.org/"> or GNU zebra <HTMLURL
 URL="http://www.zebra.org/"> does. However, you can not run Cisco's firmware on "normal" computer
-and gated is really hard to configure and comes under wrong license. Bird is being developed on
+and gated is really hard to configure and comes under wrong license. BIRD is being developed on
 Charles University, Prague, and can be freely distributed under terms of GNU General Public
-License. Bird is designed to run on Unix and unix-like systems, it is primarily developed on Linux.
+License. BIRD is designed to run on Unix and unix-like systems, it is primarily developed on Linux.
 
 <sect1>About this documentation
 
@@ -61,6 +61,12 @@ section in filters.
 
 <sect1>Introduction
 
+<p>BIRD is configured using text configuration file. At startup, BIRD reads <file/bird.conf/ (unless
+-c command line parameter is given). Configuration may be changed on user request: if you modify
+config file and then signal BIRD with SIGHUP, it will adjust to new config. There's BIRD client,
+which allows you to talk with BIRD in more extensive way than just telling it to reconfig. BIRD
+writes messages about its work to log files or syslog (according to config).
+
 <p>Bird is configured using text configuration file. At startup, bird
 reads <file/bird.conf/ (unless -c command line parameter is
 given). Everything on a line after <cf/#/ is a comment, whitespace is
@@ -68,13 +74,11 @@ ignored, C-style comments <cf>/* comment */</cf> are also
 recognized. If there's variable number of options, it is grouped using
 <cf/{ }/ brackets. Each option is terminated by <cf/;/.
 
-<p>Really simple configuration file might look like this, you can find
-example of more complicated configuration file in
-<file>doc/bird.conf.example</file>.
+<p>Really simple configuration file might look like this:
 
 <code>
 protocol kernel {
-	persist;		# Don't remove routes on bird shutdown
+	persist;		# Don't remove routes on BIRD shutdown
 	scan time 20;		# Scan kernel routing table every 20 seconds
 	export all;		# Default is export none
 }
@@ -98,42 +102,44 @@ protocol rip {
 	<cf/debug/ for debugging message, <cf/trace/, <cf/info/,
 	<cf/remote/ for messages about misbehavior of remote side, <cf/warning/,
 	<cf/error/, <cf/auth/, <cf/fatal/, <cf/bug/ for internal bugs
-	of bird. You may specify more than one <cf/log/ line to log to multiple
+	of BIRD. You may specify more than one <cf/log/ line to log to multiple
 	destinations.
 				  
 	<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
-	sets global default of debugging options.
+	sets global default of protocol debugging options.
 
 	<tag>filter <m/name/{ <m/commands/ }</tag> define filter. You can learn more about filters
 	in next chapter.
  
-	<tag>protocol rip|ospf|bgp <m/[name]/ { <m>protocol options</m> }</tag> define protocol
+	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> define protocol
 	instance, called name (or called something like rip5 if you omit name). You can learn more
-	about configuring protocols in their own chapters.
+	about configuring protocols in their own chapters. You can run more than one instance of
+	most protocols (like rip or bgp).
 
 	<tag>define constant = expression</tag> define constant. You can use it later in every place
 	you could use simple integer.
 
-	<tag>router id <m/num.num.num.num/</tag> set router id. Router
-	id needs to be world-wide unique 32bit number, identifying
-	router. It is usually one of router's IP addresses.
+	<tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide
+	unique. It is usually one of router's IPv4 addresses.
 
 	<tag>table <m/name/</tag> create new routing table.
 
 	<tag>eval <m/expr/</tag> evaluates given filter expression. It is used for testing.
 </descrip>
 
-<sect1>Per-protocol options
+<sect1>Protocol options
 
 <p>Several options are per-protocol, but all protocols support them. They are described here.
 
 <descrip>
-	<tag>preference <m/expr/</tag> sets preference of this protocol.
+	<tag>preference <m/expr/</tag> sets preference of routes generated by this protocol.
 
-	<tag>disabled</tag> disables given protocol.
+	<tag>disabled</tag> disables given protocol. You can disable/enable protcol from command
+	line interface without needing to touch config.
 
 	<tag>debug <m/setting/</tag> this is similar to global debug setting, except that it only
-	affects one protocol.
+	affects one protocol. Only messages in selected debugging categories will be written to
+	logs.
 
 	<tag>import <m/filter/</tag> filter can be either either <cf> { <m>filter commands</m>
 	}</cf> or <cf>filter <m/name/</cf>. Import filter works in direction from protocol to main
@@ -153,18 +159,20 @@ protocol rip {
 	time from which password is not announced but is allowed. id is password id, as needed by
 	certain protocols.
 
-	<tag>interface "<m/mask/" [ { <m/option/ ; [ ... ] } ]</tag> specifies, which interfaces
-	this protocol is active at, and allows you to set options on interface-by-interface
-	basis. Mask is specified in shell-like patters, thus <cf>interface "*" { mode broadcast;
-	};</cf> will start given protocol on all interfaces, with <cf>mode broadcast;</cf> option.
+	<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> specifies, which
+	interfaces this protocol is active at, and allows you to set options on
+	interface-by-interface basis. Mask is specified in shell-like patters, thus <cf>interface
+	"*" { mode broadcast; };</cf> will start given protocol on all interfaces, with <cf>mode
+	broadcast;</cf> option.
+						  
 </descrip>
 
 <sect>Filters
 
 <sect1>Introduction
 
-<p>Bird contains rather simple programming language. (No, it can not yet read mail :-). There are
-two objects in this language: filters and functions. Filters are called by bird core when route is
+<p>BIRD contains rather simple programming language. (No, it can not yet read mail :-). There are
+two objects in this language: filters and functions. Filters are called by BIRD core when route is
 being passed between protocol and main routing table, and filters may call functions. Functions may
 call other functions, but recursion is not allowed. Filter language contains control structures such
 as if's and switches, but it allows no loops. Filters are
@@ -205,6 +213,10 @@ pairs <cf><M>type name</M>;</cf>, where each pair defines one local variable. Bo
 several statements into one by <cf>{ <M>statements</M> }</cf> construction, that is useful if
 you want to make bigger block of code conditional.
 
+<p>There are two special filters, <cf/all/ (which accepts all routes) and <cf/none/ (which rejects
+all routes).
+
+
 <p>Bird supports functions, so that you don't have to repeat same blocks of code over and
 over. Functions can have zero or more parameters, and can have local variables. Function basically
 looks like this:
@@ -252,7 +264,7 @@ booleans (that is to prevent you from shooting in the foot).
 	  such variables, but you can not concatenate two strings (for example). String constants
 	  are written as <cf/"This is a string constant"/.
 
-	<tag/ip/ this type can hold single ip address. Depending on version of bird you are using, it
+	<tag/ip/ this type can hold single ip address. Depending on version of BIRD you are using, it
 	  can be IPv4 or IPv6 address. IPv4 addresses are written (as you would expect) as
 	  <cf/1.2.3.4/. You can apply special operator <cf>.mask(<M>num</M>)</cf>
 	  on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip
@@ -275,7 +287,7 @@ booleans (that is to prevent you from shooting in the foot).
 	  3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}.
 
 	<tag/enum/
-	  enumeration types are halfway-internal in the bird. You can not define your own
+	  enumeration types are halfway-internal in the BIRD. You can not define your own
 	  variable of enumeration type, but some predefined variables are of enumeration
 	  type. Enumeration types are incompatible with each other, again, for your
 	  protection.
@@ -406,12 +418,12 @@ periodic messages onto this interface and <cf>nolisten</cf> means that rip will
 interface but not listen on it.
 
 <p>Following options generally override specified behavior from rfc. If you use any of these
-options, bird will no longer be rfc-compatible, which means it will not be able to talk to anything
-other than equally misconfigured bird. I warned you.
+options, BIRD will no longer be rfc-compatible, which means it will not be able to talk to anything
+other than equally misconfigured BIRD. I warned you.
 
 <descrip>
 	<tag>port <M>number</M></tag>
-	  selects IP port to operate on, default 520. (This is useful when testing bird, if you
+	  selects IP port to operate on, default 520. (This is useful when testing BIRD, if you
 	  set this to address &gt;1024, you will not need to run bird with UID==0).
 
 	<tag>infinity <M>number</M></tag>
@@ -438,8 +450,8 @@ protocol rip MyRIP_test {
         port 1520;
         period 7;
         garbagetime 60;
-        interface "*";
-        honour neighbour;
+        interface "eth0" { metric 3; mode multicast; } "eth1" { metric 2; mode broadcast; };
+        honor neighbour;
         passwords { password "ahoj" from 0 to 10;
                 password "nazdar" from 10;
         }