Documentation update

2 files changed, 93 insertions, 78 deletions

diff --git a/TODO b/TODO
index ecf00d81..d33162b7 100644
--- a/TODO
+++ b/TODO
@@ -58,59 +58,16 @@ OSPF
 
 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.
-o  Zkusit HTML projet nejakym validatorem.
-
-Uvod:
-
-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.
-o  Chybi installation requirements: tedy ze potrebujeme GCC a GNU make.
-
 Filtry:
 
-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  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  attributes: nemyslim, ze jsou vsechny -- co treba scope a preference?
-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  RIP: Per-interface optiony uvadet tez jako definition list.
 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).
@@ -122,17 +79,6 @@ 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'.
 
-> > Nechtel bys kapitolu o clientovy napsat ty? Ja o nem nic nevim, a
-> > kvalita uzivatelske dokumentace je o hodne dulezitejsi nez
-> > programatorske.
->
->    O clientovi neni temer co psat, commandy si, myslim, snadno najdes v config.Y.
-> Protokol je velice jednoduchy: uzivatel posila prikazy, BIRD odpovida radky
-> typu CCCCs..., kde CCCC je kod hlasky (viz doc/reply-codes), `s' je whitespace,
-> `...' hlaska. Viceradkove odpovedi maji na vsech radcich mimo posledniho misto `s'
-> minus a nebo na druhem az predposlednim radku misto celeho prefixu jen whitespace
-> (presne jako ve FTP).
-
 Jeste by to chtelo trosku podrobneji:
 
 (1) zminit se o atributech, rici, co vsechno o route rikaji a odkazat  
diff --git a/doc/bird.sgml b/doc/bird.sgml
index 9bae9eea..e817d0b2 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -98,30 +98,55 @@ it is slightly modified linuxdoc dtd.  Anything in <descrip> tags is consi
 configuration primitives, <cf> is fragment of configuration within normal text, <m> is
 "meta" information within fragment of configuration -- something in config which is not keyword.
 
+
+<sect1>About routing tables
+
+<p>Bird has one or more routing tables, which may or may not be
+synchronized with kernel and which may or may not be synchronized with
+each other (see protocol pipe). Each routing table contains list of
+known routes. Each route has certain attributes, most important is
+prefix of network this route is for. Routing table maintains more than
+one entry for network, but at most one entry for one network and one
+protocol. The entry with biggest preference is used for routing. If
+there are more entries with same preference and they are from same
+protocol, protocol decides (typically according to metrics). You can
+get list of route attributes in "Route attributes" section in
+filters. Filters can alter routes passed between routing tables and
+protocols.
+
 <sect1>Installing BIRD
 
-<p>On UNIX system, installing BIRD should be as easy as:
+<p>On recent UNIX system, installing BIRD should be as easy as (bird
+relies on GNU C and GNU make extensions): <!-- It is not true that we
+require gcc, there are other compilers supporting gcc extensions! -->
 
 <code>
         ./configure
         make
         make install
         vi /usr/local/etc/bird.conf
+	bird
 </code>
 
-<p>You can use <tt>./configure --help</tt> to get list of configure options.
+<p>You can use <tt>./configure --help</tt> to get list of configure
+options. Most important (and not easily guessed) option is
+<tt/--enable-ipv6/, which enables IpV6 support.
 
-<sect1>About routing tables
+<p>You can pass several command-line options to bird:
 
-<p>Bird has one or more routing tables. Each routing table contains
-list of known routes. Each route has certain attributes, most
-important is prefix of network this route is for. Routing table
-maintains more than one entry for network, but at most one entry for
-one network and one protocol. The entry with biggest preference is
-used for routing. If there are more entries with same preference and
-they are from same protocol, protocol decides (typically according to
-metrics). You can get list of route attributes in "Route attributes"
-section in filters.
+<descrip>
+	<tag>-c <m/config name/</tag>
+	use given config file instead of <file>bird.conf</file>.
+
+	<tag>-d</tag>
+	enable debugging.
+
+	<tag>-D <m/filename for debug log/</tag>
+	log debugging information to given file
+
+	<tag>-s <m/name of communication socket/</tag>
+	use given filename for socket for communications with bird client, default is <file/bird.ctl/.
+</descrip>
 
 <sect>Configuration
 
@@ -246,7 +271,10 @@ protocols, telling BIRD to show various information, telling it to
 show routing table filtered by any filter, or telling bird to
 reconfigure. Press <tt/?/ at any time to get online help. Option
 <tt/-v/ can be passed to client, telling it to dump numeric return
-codes.
+codes. You do not neccessarily need to use BIRDC to talk to BIRD, your
+own application could do that, too -- format of communication between
+BIRD and BIRDC is stable (see programmer's documenation).
+
 
 <sect>Filters
 
@@ -291,7 +319,6 @@ 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:
@@ -320,6 +347,27 @@ to any functions being called. Filter must terminate with either
 accept or reject statement. If there's runtime error in filter, route
 is rejected. 
 
+<p>Nice trick to debug filters is using <cf>show route filter
+<m/name/</cf> from command line client. Example session might look
+like:
+
+<code>
+pavel@bug:~/bird$ ./birdc -s bird.ctl
+BIRD 0.0.0 ready.
+bird> help
+No such command.
+bird>
+bird> show route
+10.0.0.0/8         dev eth0 [direct1 23:21] (240)
+195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
+127.0.0.0/8        dev lo [direct1 23:21] (240)
+bird> show route ?
+show route [<prefix>] [table <t>] [filter <f>] [all] [primary] [(import|protocol) <p>] [stats]  Show routing table
+bird> show route filter { if 127.0.0.5 ~ net then accept; }
+127.0.0.0/8        dev lo [direct1 23:21] (240)
+bird>
+</code>
+
 <sect1>Data types
 
 <p>Each variable and each value has certain type. Unlike C, filters distinguish between integers and
@@ -358,10 +406,12 @@ booleans and between integers and enums (that is to prevent you from shooting in
 	  filters know four types of sets. Sets are similar to strings: you can pass them around
 	  but you can not modify them. Constant of type <cf>set int</cf> looks like <cf>
 	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
-	  sets. Sets of prefixes are special: you can specify which prefixes should match them by
+	  sets. Sets of prefixes are special: you can specify which prefix lengths should match them by
 	  using <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. 3.0.0.0/8{5,6} matches
 	  prefixes 3.X.X.X, whose prefix length is 5 to 6. 3.0.0.0/8+ is shorthand for 3.0.0.0/{0,8},
-	  3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}.
+	  3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}. For example,
+	  <tt>1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ]</tt> is true, but
+	  <tt>1.0.0.0/8 ~ [ 1.0.0.0/8- ]</tt> is false. 
 
 	<tag/enum/
 	  enumeration types are halfway-internal in the BIRD. You can not define your own
@@ -374,10 +424,14 @@ booleans and between integers and enums (that is to prevent you from shooting in
 
 	<tag/bgpmask/ 
 	  bgp mask is mask used for matching bgp paths
-	  (using <cf>path ~ / 2 3 5 ? / syntax </cf>). <cf/?/ is
-	  really serving in "any number of autonomous systems", but we
+	  (using <cf>path ~ / 2 3 5 ? / syntax </cf>). Matching is
+	  done using shell-like pattern: <cf/?/ means
+	  "any number of any autonomous systems". Pattern for single
+	  unknown autonomous system is not supported. (We
 	  did not want to use * because then it becomes too easy to
-	  write <cf>/*</cf> which is start of comment.
+	  write <cf>/*</cf> which is start of comment.) For example,
+	  <tt>/ 4 3 2 1 / ~ / ? 4 3 ? 1 /</tt> is true, but 
+	  <tt>/ 4 3 2 1 / ~ / ? 4 5 ? /</tt> is false.
 
 	<tag/clist/ 
 	  community list. This is similar to set of pairs,
@@ -428,11 +482,13 @@ attributes, just like it accesses variables. Access to undefined
 attribute results in runtime error; you can check if attribute is
 defined using <cf>defined( <m>attribute</m> )</cf> syntax.
 
-
 <descrip>
-	<tag/<m/prefix/ network/
+	<tag/<m/prefix/ net/
 	network this route is talking about.
 
+	<tag/<m/int/ preference/
+	preference of this route.
+
 	<tag/<m/ip/ from/
 	who told me about this route.
 	
@@ -441,6 +497,12 @@ defined using <cf>defined( <m>attribute</m> )</cf> syntax.
 
 	<tag/<m/enum/ source/
 	what protocol told me about this route. This can have values such as <cf/RTS_RIP/ or <cf/RTS_OSPF_EXT/.
+
+	<tag/<m/enum/ scope/
+
+	<tag/<m/enum/ cast/
+
+	<tag/<m/enum/ dest/
 </descrip>
 
 <p>Plus, there are protocol-specific attributes, which are described in protocol sections.
@@ -1014,11 +1076,18 @@ protocol static {
 }
 </code>
 
-<sect>Getting more help
+<sect>Problems
 
-<p>This is really last section of this file, should give pointers to
-programmers documentation, web pages mailing lists and similar stuff.
+<p>BIRD is relatively young system, and probably contains some
+bugs. You can report bugs at <HTML URL="fixme">, but before you do,
+please make sure you are running latest version (available at <HTML
+URL="fixme">), and that bug was not already reported by someone else
+(mailing list archives are at <HTML URL="fixme">). (Of course, patch
+which fixes the bug along with bug report is always welcome). When
+trying to understand, what is going on, Internet standards are
+relevant reading; you can get them from <HTML URL="fixme">.
 
+<p><it/Good luck!/
 
 </article>