From d150c6379c03a9df98ff5dd53a6442a10713b571 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Sun, 28 May 2000 19:11:08 +0000 Subject: Documentation update. --- TODO | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/bird.sgml | 80 +++++++++++++++++++++++++++--------------------- 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 @@