Documentation update.

2 files changed, 143 insertions, 34 deletions

diff --git a/TODO b/TODO
index ec886fa..ca1fd07 100644
--- a/TODO
+++ b/TODO
@@ -56,3 +56,100 @@ OSPF
 	- RFC1587 NSSA areas
 	- RFC2370 opaque LSA's
 	- respect interface MTU and try not to create larger packets unless unavoidable
+
+Documentation (sorry, its in czech)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+K SGML:
+
+o  Mohl bys, prosim, nekam napsat, co je vsechno potreba udelat, aby bylo
+   dokumentaci mozno postavit? Skoncil jsem u toho, ze jsem do doc/sbase/
+   zkopiroval spoustu souboru z /usr/lib/sgml-tools a pridal nekolik symlinku
+   -- ted uz sice dokumentaci vygeneruji, ale asi to neni ta spravna cesta.
+
+K HTML:
+
+o  "2000" zcela vypadava mimo hlavicku.
+
+Uvod:
+
+o  "What is bird": tam by melo byt receno, _co_ je BIRD, nikoliv cemu se podoba.
+   To obnasi jednak par vet o tom, o co se vlastne snazi, potom nejaky feature
+   list (s odkazy do jednotlivych casti dokumentace?) a tez neco na tema "v cem
+   jsme lepsi nez konkurence" (a neargumentovat pouze licenci :) ).
+   Rovnez tak neni vubec urcen jen pro unixove systemy -- je velice portabilni
+   a shodou okolnosti Unix (presneji Linux) je jediny zatim napsany port.
+o  Chybi sekce popisujici instalaci, spousteni a command-line options.
+o  "About routing tables" by melo byt podstatne podrobnejsi (vysvetlit, co vlastne
+   routovaci tabulky jsou, co obsahuji, ze vubec existuji nejake atributy, k cemu
+   slouzi, ze nektere tabulky jsou synchronizovane s kernelem, zatimco jine nikoliv,
+   ze lze prenaset routy mezi tabulkami (odkaz na protokol pipe), ze k tabulkam
+   jsou pres filtry pripojeny protokoly atd.) Asi z toho udelat samostatnou kapitolu.
+o  Zminit logy a kategorie hlasek.
+
+Filtry:
+
+o  Na zacatku zejmena vysvetlit, jak jsou filtry do systemu zapojeny, k cemu slouzi,
+   ze dostanou routu a ocekava se od nich verdikt. Teprve pak vysvetlovat, ze to
+   jsou programy, ze mohou volat funkce atd. Tez zminit, ze protokol ma pravo
+   nektere routy akceptovat/odmitnout bez toho, aniz by se zeptal filtru.
+o  Napsat neco o tom, jak filtry debugovat -- ze existuje trasovani filtru
+   a CLI command pro vypsani routovaci tabulky tak, jak projde filtrem ci tak,
+   jak ji vidi dany protokol.
+o  `filters internally work ...' patri do progdoc.
+o  Vysvetlit nesting a zastinovani.
+o  Nadefinovat, co se stane, kdyz funkce nevrati hodnotu, i kdyz ma.
+o  Popsat runtime errory a ze se chovaji jako rejecty.
+o  Typy: tez rici, ze integery se lisi nejen od booleanu, ale take od enumu.
+o  Boolean: TRUE nebo true? U kazdeho typu zminit, jak vypadaji literaly
+   tohoto typu a psat je vzdycky tt fontem.
+o  int: Nadefinovat rozsah a rici, ze preteceni se nekontroluje. Zminit
+   hexadecimalni konstanty.
+o  ip: IPv4/IPv6 nezavisi na verzi BIRDa, nybrz na compile-time konfiguraci.
+o  ip: .mask zminit zvlast mezi specialnimi operatory.
+o  set: lepe vysvetlit matchovani prefixu, ukazat na prikladu.
+o  bgppath: list of autonomous system _numbers_
+o  bgpmask: vysvetlit matchovani.
+o  operations: prejmenovat na `operators', mela by to asi byt tabulka
+   operatoru, u kazdeho receno, na jakych typech je definovan a jakeho
+   typu je vysledek.
+o  operations: ~ pracuje i na clistech, neni-liz pravda?
+o  Examply by mohly byt krapet smysluplnejsi.
+o  defined(): To, ze undefined attribute cannot be accessed, by melo byt
+   rozhodne receno nekde jinde (v uvodu sekce) -- vzdyt u defined samotneho
+   to mozne je.
+o  attributes: nemyslim, ze jsou vsechny -- co treba scope a preference?
+o  Chybi operace na clistech a cestach.
+o  print: a coz takhle printn apod.?
+o  Mezi prikazy nikde neni zminen napriklad accept a reject.
+o  Co se stane, kdyz filtr skonci, aniz by vydal verdikt?
+
+Protocols:
+
+o  U kazdeho protokolu rici, jestli podporujeme pouze IPv4 nebo i IPv6 verzi.
+o  RIP: Vysvetlit, na ktere site se RIP hodi a na ktere ne, rici, ze je
+   hodnoty spise historicke, ale ze ve svete IPv6 se bezne pouziva, protoze
+   zatim neexistuji slusne implementace OSPFv3.
+o  RIP: Per-interface optiony uvadet tez jako definition list.
+o  RIP: U RIP-specific atributu zminit, jakeho jsou typu a jak vznikaji.
+o  Example u RIPu je out of date: `honour' -> `honor' apod. Tez ukazat
+   per-interface optiony.
+o  passwords: syntaxe data uz, tusim, davno vypada jinak.
+
+Struktura dokumentace:
+
+o  Chybi kapitola o CLI a o clientovi.
+o  Na konci (nebo ve zvlast sekci pro kazdy protokol?) by mel byt seznam referenci
+   na vsechny mozne dokumenty, zejmena vsak vsechna RFC, kterymi se ridime nebo
+   ktera maji neco spolecneho s tim, co delame (napriklad RPSL).
+
+K jazyku:
+
+o  K "BIRD Internet Routing Daemon" by mel patrit urcity clen.
+o  Nerika se `comparation', nybrz `comparison'.
+o  RFC (a ostatni zkratky) psat vzdy velkymi pismeny.
+o  Pokud je v zavorce cela veta, patri pred ')' tecka, pokud neni, tak
+   nepatri.
+o  Davej si pozor na rody -- router je vzdycky `it', nikdy `he'.
+
diff --git a/doc/bird.sgml b/doc/bird.sgml
index ef06501..a1fb863 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;
         }