Ovoce mého inovačního snažení: www.lindevdoc.org

15.2.2008 19:54 | Přečteno: 1718× | | poslední úprava: 17.2.2008 21:15

Jak asi kdekdo ví, v SUSE/Novellu je poslední dobou dobrým zvykem poskytovat zaměstnancům čas na jejich vlastní projekty; leckdo dělá velice zajímavé věci, leckdo věci poněkud šílené a leckdo oboje. Ten můj pološílený projekt se nyní dostal do stadia, kdy je schopen omezeného představení veřejnosti - proto jej nyní předkládám - k nahlédnutí, kritice, posouzení, odsouzení, atd.

O co jde? Můj plán je ambiciózní - nic menšího než dokumentační web ve stylu MSDN - detailní, prolinkovaná, přehledná, hezká a co nejkompletnější integrovaná dokumentace pro vývojáře. Samozřejmě, že v tomhle stadiu to ještě zdaleka není, ale pokud by se našlo pár (raději pár desítek ) pomocných rukou, snad by se do toho stadia mohl dostat.

Chcete-li, zkuste: www.lindevdoc.org

Děkuji za pozornost

Poznámka: Omlouvám se, že je to jen anglicky, ale nemám sil dělat současně dokumentaci v češtině i v angličtině, a rád bych, aby to bylo užitečné pro co největší skupinu lidí. Jungmanne, odpusť.

UPDATE: Zprovoznil jsem registraci; po registraci je možné editovat a přidávat stránky. Prosím, pokud to budete chtít zkusit, dávejte pozor na bugy a hlavně mi je hlaste        

Komentáře

[Luk]

Chválím, a to hlavně za standardní knihovnu C. To je totiž přesně to, co tu chybělo a čeho jsem se permanentně dožadoval

[qk]

No kdyz sem koukal na tu knihovnu, tak si nemuzu pomoct, ale zrovna u ni by mi prislo lepsi, kdyby se generovala z kodu, treba doxygenem. Tenhle popis je peknej, ale kdyz chce clovek pouzivat IDE co umi rovnou zpracovat i komentare k funkcim (treba doxygeni), tak by to rozhodne vice pomohlo.

[Luk]

A jak se z kódu vygeneruje ta logická struktura? Nijak. Pokud chci dokumentaci k určité funkci, použiju man. Jenže to musím nejdřív vědět, že mám použít právě tuto funkci. V tom je hlavní smysl toho celého a už jsem to tu říkal několikrát.

[qk]

Kupodivu to mozne je. Neco ve stylu sestkovych netbeans. Jednoducha pravidla jako neco = funkce, tak funkci porad podle typu co vraci ....dale treba nejdrive dej funkce co pracuji s typy co maji lokalni promenne, pak teprve globalni. Samozrejme je trochu problem s carovanim s pointery.
To ze C neni objektovy jazyk a tedy nemuze davat pouze metody jako treba java, je samozrejme problem. Ale myslim ze z takoveho webu se clovek nenauci jaky funkce pouzivat....jinak kdyz sme u toho ja kdyz nevim fci, pouziju apropos s grepem a nehledam po webu, maximalne nejaky example.

[Luk]

Asi si nerozumíme. Mně jde o něco úplně jiného. Uvedu příklad (záměrně takový, aby se to velmi částečné dílo dalou použít). Chci třeba najít funkci (a samozřejmě pak dokumentaci k ní), která mi zjistí efektivního uživatele procesu. Tak půjdu: Security -> Process-user relation -> geteuid().

Uvedený příklad je jednoduchý. Ale je mnoho dalších případů, kdy člověk nemá ani ponětí o existenci nějakých (hlavně novějších nebo méně obvyklých) funkcí, proto řeší problémy zbytečně složitě nebo musí sáhodlouze tápat a hledat po webu.

Je to věc, kterou měl Microsoft ve své MSDN dokumentaci už dávno a zde bylo žádoucí si z něho vzít příklad.

[qk]

Jo uz chapu....ale i to se da udelat v tom doxygenu...napriklad kdyz sme do skoly delali male jadro pro mips, tak sme meli main page doxygenu presne takhle vystavenou. Ze tam to byli odkazy podle kategorii a ty nanavigovali az do headeru, ktere se tykali konkretniho tematu (napr syn. primitiva -> mutex.h,semaphore.h scheduling->loadBalancer.h,scheduler.h atd.) Ale uznavam ze podle komentare nize je to nekdy dost tezky udelat ten doxygen.

[andree]

jeee, OSy.. a uz mate hodnotenie?

[Kyosuke]

Tak tak, MSDN je boží věc, něco takového je zapotřebí jako sůl. Je pochopitelné, že autorů dokumentace je mnohem méně, než systémových hackerů (psát tyhle věci dobrovolně mohou jen vyšinutí jedinci jako já ), ale to nezmění ten fakt, že dokumentace kulhá. Myslím, že na inspiraci MSDN nebude nic špatného.

Bezva. Čekal jsem, jestli se to dostane do nějakého oficiálního stadia, a stalo se. Zkusím si najít nějakou tu oblast, na které by stálo za to zapracovat, jakmile bude fungovat registrace (rejp! ).

[Bluebear]

jakmile bude fungovat registrace

Omlouvám se - to není bug, ale moje zbabělost. Registrace by snad i fungovala, jen jsem se zatím neodvážil ji zapnout. Ten engine je poněkud (čti: značně) zabugovaný a mám strach tam pustit někoho jiného, než odlovím ty nejbrutálnější bugy - ještě včera večer se mi podařilo šlápnout na bug, jehož následky jsem opravoval za pomoci ruční editace databáze

(Mimochodem, jsem jediný, kdo si myslí, že nepřítomnost transakcí v MySQL je sadismus?)

Tudíž prosím o trpělivost - jakmile pochytám bugy, které sám vidím, tak registraci zapnu; mělo by to být jen pár dnů.

[Messa]

V MySQL jsou transakce, AFAIK od verze 5; musíš použít InnoDB engine.

[Luk]

Byly tam už mnohem dřív, někdy od 3.23 - ale samozřejmě jen s InnoDB.

[Messa]

Sakra To bude tím, že v době před 5.0 jsem nic takového ani nepotřeboval, tak nevím že to tam už bylo.

[petr_p]

Nechci rýpat, ale info stránky jste viděl?

info libc → Users and Group → Reading Persona

[petr_p]

Aha, už se řešilo.

[Luk]

Totéž je také na webu, ale i ten je brutálně zastaralý, přestože se na něm v nedávné době dělaly mírné aktualizace. Mnoho funkcí tam chybí, některé fungují jinak, řada věcí byla odstraněna. Jen tak namátkou: toto neplatí, symboly O_READ a O_WRITE byly dávno odstraněny. Nehledě na to, že to není skutečná referenční dokumentace, takže člověk musí stejně nahlížet do manuálových stránek.

[petr_p]

Nehledě na to, že to není skutečná referenční dokumentace, takže člověk musí stejně nahlížet do manuálových stránek.

Zajímavé. A já neustále žiji v přesvědčení, že software vyvíjený pod FSF má texinfo jako primární dokumentační formát. Je tak koncipován rozcesník jen o patro výše, mnoho manuálových stránek to explicitně zmiňuje (hlavně ty z coreutils).

[Bluebear]

To je pravda, vývojáři GNU utilit považují texinfo za primární dokumentační formát a manuálové stránky za přežitek.

Na druhé straně řada jiných považuje texinfo za dost strašný formát a raději používá manuálové stránky (přestože formát manuálových stránek je rovněž strašný). Dokonce to jde tak daleko, že se svépomocí udržují manuálové stránky pro funkce z glibc, přičemž vývojáři glibc snad ani nevědí, že existují (ty stránky).

[Luk]

Přesně tak. Možná jsou ty manuálové stránky brutálně partyzánské, ale jsou skoro aktuální a navíc je to skutečná referenční dokumentace, což se o té v info říct nedá.

[petr_p]

Souhlasím.

Jen aby nedošlo k mílce, texinfo formát jsem raději nezkoumal. Stačil mi *roff, kdy po napsání několika stránek jsem se s radostí vrátil k docbooku. Na druhou stranu, na texinfu mi imponuje hypertext (i když souhlasím, že jeho prezentace v info(1) je šílená).

[Bluebear]

kdyz sem koukal na tu knihovnu, tak si nemuzu pomoct, ale zrovna u ni by mi prislo lepsi, kdyby se generovala z kodu, treba doxygenem

Uvažoval jsem o tom, ale u tak složité a low-level knihovny, jako je glibc, je to velmi obtížné. Řada funkcí má několik variant podle toho, v jakém prostředí a na jaké architektuře se kompiluje, používají se tam složité triky s preprocesorem. Když jsem četl kousky zdrojáků glibc, měl jsem problémy vůbec najít, kde je skutečná definice funkce, která se týká právě mého systému. Nedovedu si moc představit automatický nástroj, který by to dokázal.

S analýzou samotného zdrojového kódu je to IMHO ještě těžší, protože jde o velmi low-level záležitosti, kde je k pochopení nutná znalost hardwaru a spousty okrajových věcí; ten automatický analyzátor by musel být strašně chytrý, aby to zvládl.

[Luk]

Tohle je mimochodem důvod, proč se nevyvíjí referenční dokumentace k jádru na webu kernel-api.org. Tam jsem to totiž generoval pomocí doxygenu (s tím, že se to předchroustalo pomocí sedu). Jenže to, co jsem vygeneroval, bylo těžce neúplné, protože jsem nedefinoval některé symboly. A když jsem je dodefinoval, doxygen už to neustál a po naalokování neuvěřitelného množství paměti se zhroutil (mám pocit, že i na 64-bitové platformě s dostatkem paměti).

[thingie]

Těžkotonážní sbírka dokumentace pro glibc je v Info (ano, taky ten systém nesnášim, ale je to tam).

[Bluebear]

Bohužel info stránky ke glibc jsou hodně zastaralé; dost dlouho nejsou lidi na jejich údržbu. Ve skutečnosti právě to (resp. že jsme za to dostali v Berlíně vynadáno) mě přivedlo na myšlenku udělat vlastní dokumentační projekt.

[petr_p]

A proto jsme založili nový dokumentační projekt, do kterého se lidé jen pohrnou.

[Bluebear]

Nikdo jiný to neudělá.

Uvažoval jsem (uznávám, že jen krátce) o tom, že bych pomohl updatovat info stránky glibc, ale to mělo následující problémy:

1. Glibc není zdaleka jediná věc, kterou je třeba zdokumentovat; například ioctly jsou na tom ještě hůř (pro glibc je aspoň nějaká dokumentace, pro většinu ioctlů není vůbec) a je třeba, aby byla dokumentace na jednom místě.

2. Info není (pro mne) příliš příjemný formát a špatně se prohlíží (lze sice vyexportovat do Docbooku, ale ten je ještě podstatně horší).

3. Dobrý zdroj mě varoval, ať se nepokouším komunikovat s glibc upstreamem (Uli Drepper), že by mě vynesl v zubech.

[Luk]

pro většinu ioctlů není vůbec

Připrav rozhraní, rád ho nakrmím, budu-li mít náladu (a to snad někdy budu mít, protože mi nezdokumentované ioctl příkazy natolik pijí krev, že jsem ochoten se na ně pořádně podívat a jednou provždy to někam zanést).

Info není (pro mne) příliš příjemný formát a špatně se prohlíží

Info přímo nesnáším. Preferuji HTML. Nevidím ve formátu info žádnou výhodu.

Dobrý zdroj mě varoval, ať se nepokouším komunikovat s glibc upstreamem (Uli Drepper), že by mě vynesl v zubech.

[Bluebear]

Připrav rozhraní, rád ho nakrmím, budu-li mít náladu

Nuže, rozhraní je připraveno, dokonce už jsem pokusně začal jednu kapitolu (ioctly CDROM), takže budeš-li mít chuť a čas, stačí si zvolit nějakou ucelenou skupinu ioctlů a začít.

Samozřejmě i kdokoli další je vítán - nejen na ioctly, je tam práce jak na kostele.

[Luk]

Dobře, sice mám na práci spoustu důležitějších věcí, ale stejně si na to nějakou chvilku rezervuji

[Bluebear]

Jejda, to není povinné Myslel jsem skutečně, až (a když) budeš mít chvíli času a chuť. Neber to jako závazek

[Luk]

Vždyť já to jako závazek neberu Jenže vždycky je to tak, že člověk radši dělá něco naprosto nedůležitého, namísto věcí, které jsou skutečně důležité

[Luk]

Ještě technická poznámka - bylo by dobré argumenty uvádět přesně tak, jak se posílají do funkce. Jde hlavně o to, že je potřeba přesně rozlišit konkrétní hodnoty a ukazatele na ně.

Například pokud se uvede long, pak se musí skutečně použít přímo long a ne long *. Pro druhý případ by se mělo uvádět long *. Totéž pro konzistenci i u struktur, i když tam je jasné, že se předává vždy pointer.

[Bluebear]

Správná připomínka; opravím to.

[Luk]

Teď koukám, že tam není nová verze příkazů, které jsem tam vkládal. Sakra práce! Buď se to vytratilo z databáze (což není moc pravděpodobné), nebo jsem si jen zobrazil náhled a pak už jsem to nepotvrdil

[Bluebear]

Z databáze by se to ztratit nemělo; neprováděl jsem žádnou tak drastickou akci. Spíš to vypadá na ten náhled; to je mi líto.

Pokusím se na to něco vymyslet, ale zatím nevím, co.

[Luk]

Za to nemůžeš, asi jsem se uklikl nebo něco takového. Každopádně je to dost demotivující (už jsem to měl skoro hotové) - doufám, že ještě seberu chuť to udělat znovu (a radši si to příště uložím i lokálně).

[Ignor]

Pěkné, akorát XWindows mě teda praštilo do očí. Ale přál bych si, aby se přímo pro linux programovalo co nejméně a programy se psaly multiplatformně.

[Zdeněk Burda]

Pěkné

[Bluebear]

Oo, díky - chvála od znalce potěší dvojnásob

(Teď jen doufám, že se mi podaří to dokopat do bodu, kdy bude možné povolit volnou editaci. )

[qk]

Jeste mala pripominka - chtelo by to lepsi vyhledavani. zkusmo sem zadal tyto tri hledane vyrazy - open file, open pipe a copy file a nic to nenaslo, coz neni zrovna idealni.

[Bluebear]

Hledání je vždycky problém; zkusím to postupně vylepšit.

[disorder]

pre uplnost by sa tam zisli aj online manpages, pretoze ked uz tam niekto bude chodit alebo prezerat tie popisy, tak sa to moze zist

[Josef Kufner]

Ještě by to chtělo nějak poladit ty url... aby místo http://www.lindevdoc.org/?action=show&page=122 bylo třeba http://www.lindevdoc.org/show/scripting-utilities.

[Bluebear]

Struktura URL se asi ještě změní; pokusím se to udělat tak, aby byla přehlednější (ale v tomto bodě nemůžu nic slíbit, jsem rád, že to vůbec funguje )

[Messa]

Zdar, dovolil bych si zde takový malý brainstorming jako komentář k tvému nápadu.

Taky jsem si říkal, že by nebyl špatný web věnovaný dokumentaci (samozřejmě zatím zůstalo jen u toho říkání si ). Proč - dokumentace knihovny nebo jiného softwaru může být po obsahové stránce kvalitní, ale dost často chybí nějaké věci okolo - např. vyhledávání (ideálně kvalitní vyhledávání), prolinkování, přehlednost, třeba i možnost komentářů/wiki a odkazy na tutorialy a howto. Tím neříkám, že dokumentace softwarových projektů je nekvalitní, můžeme být rádi za to že vůbec je. Ale zkusit udělat website, který by dokumentaci z různých projektů sbíral a takto uceleně a nějak "hezčeji" prezentoval. To, že by byla dokumentace k více věcem na jednom místě, by mělo další výhody. Kdyby se pod to ještě přidalo nějaké diskuzní fórum a kdyby tam čas od času vyšel nějaký článek, byl by to dost zajímavý vývojářský portál Jo a překládání by se dalo vyřešit třeba přes wiki. Prostě, ne jen psát popis všeho možného nebo ne jen dát dohromady pár stránek vygenerovaných doxygenem; ale udělat klidně obojí a propojit to. Navíc na web se toho vejde... jako třeba hezky zformátované info a man stránky apod. Co si o tom myslíte? Do tohohle bych chtěl jít já.

BTW. Nemusí zůstat jen u webu; z takového webu by se pak daly třeba exportovat nějaké přehledy funkcí s metadaty apod., textové editory by to pak mohly využít jako "quickhelp" nebo při doplňování.

[Bluebear]

Kdyby se pod to ještě přidalo nějaké diskuzní fórum

Mám ho v plánu, ale bude to ještě chvíli trvat - zatím se patlám s chytáním bugů, které se, jak to tak bývá, objevily teprve poté, co jsem to dal na veřejný web.

[Murry]

Velmi pěkný nápad. Kdyby chtěl býti realizován, určitě bych přispěl.....
I když v momentální chvíli nevím čím.....

[kralyk z abclinuxu]

Hmm, nápad to je dobrej, ale potřebuješ komunitu!
za webem MSDN určitě stojí celej hafo velkej tým.

Co takle se optat Leoše a hodit to pod křídla abíčka?
To by se hned komunita přispěvatelů seběhla mnohem snáz...

[Kyosuke]

Jenže na tohle potřebuješ hlavně hafo velkej tým native speakerů, nebo aspoň takovej hafo velkej tým, kde jich bude značné procento... Jestli se nepletu, Jirka to chce jako těžce globální iniciativu.

[Bluebear]

Myslím, že s nativními mluvčími to nebude tak horké. Dokumentace není krásná literatura, pár chyb a neobratností se klidně snese a dají se opravovat postupně; důležité je, aby byla v pořádku fakta. Moje angličtina taky není zrovna dokonalá.

[anicka]

To by IMHO bylo dost nanic. Kolik je na abicku lidi, co jsou schopni prohrabavat zdrojaky glibc a pak o tom, co nasli, anglicky psat? A z tech schopnych, kolik je ochotnych? Ja Jirku hrozne moc obdivuju od sameho zacatku, kdy si tuhle posetilost usmyslel zrealizovat (posetilost rikam proto, ze od zacatku vypadal, ze chce zvladnout vsechno sam), ale delat bych to asi moc dlouho nevydrzela. Mozna tomu nekdy venuju tak jedno odpoledne, budu-li mit kvuli necemu obzvlastni vycitky svedomi, svatemu Tucnakovi jako pokani.

[Bluebear]

Díky moc za pochvalu (ano, výraz pošetilost v tomto kontextu chápu jako pochvalu); opět, chvála od znalce potěší dvojnásob

Nepočítám s tím, že bych to celé dělal sám, to jen tenhle začátek. Teoreticky těch hlavních přispěvatelů nemusí být příliš mnoho; doufám, že se mi podaří vyrobit takové mechanismy, které maximálně usnadní vkládání dat. Jeden už tam je (na radu Jirky Bence - ahoj ) - většinou se neoznačují odkazy, ale naopak místa, na která se dá odkazovat, a engine se snaží vytvářet linky sám, pokud to jde (například názvy funkcí a konstanty se poznají dobře).

Právě se pokouším sesmolit speciální tag, který říká o této věci nevíme dost, uvítali bychom informace od zkušenějších. První místo, kam ten tag dám, bude pravděpodobně stránka popisující chyby ENXIO a ENODEV - v životě jsem nepochopil, čím se od sebe liší.

[Luk]

chyby ENXIO a ENODEV - v životě jsem nepochopil, čím se od sebe liší

The Single UNIX ® Specification, Version 2:

[ENXIO] No such device or address Input or output on a special file refers to a device that does not exist, or makes a request beyond the capabilities of the device. It may also occur when, for example, a tape drive is not on-line.

[ENODEV] No such device An attempt was made to apply an inappropriate function to a device; for example, trying to read a write-only device such as a printer.

Chybu ENXIO jádro hlásí např. při pokusu otevřít socket voláním open(). Chyba ENODEV se hlásí třeba při pokusu připojit nepodporovaný filesystém. Je ale pravda, že je v tom chaos a asi by stačilo mít jen jeden kód. Navíc některé chyby jádro hlásí špatně, přinejmenším v některých verzích.

Ještě zábavnější je to u EAGAIN a EWOULDBLOCK, které jsou na Linuxu identické, ale obecně být nemusí (a někde skutečně nejsou).

[Bluebear]

Ouou, to je ale motanice (navíc ta jména jsou zvolena přesně opačně vzhledem k jejich významu). Moc díky za informaci.

[Bluebear]

Tam by možná byl lehoučký problém s hlavním sponzorem AbcLinuxu; nevím, jak bych vysvětlil, proč má projekt, který byl vytvořen za peníze Novellu, na sobě logo Sunu

[kralyk z abclinuxu]

Nj, já ty detaily neznám, jen sem plácnul návrh, neberte to moc vážně

[Fluttershy, yay!]

Poslušně hlásím bug: "Trace: Appendices > Kernel command line > SMP > Kernel options by name > The kernel > Welcome"

Totiž když jsem vlezl na nějakou stránku v podsekci a klikl v drobečkové navigaci na vlezní stránku, vyhodilo mi ji to na konec stávající drobečkové navigace.

[Bluebear]

Húm, hom, to není bug... tak jsem to plánoval Když navštívíš stránku, která už je v seznamu drobečků, tak se umístí na konec a odstraní se z původní pozice.

Pokud je to nepřehledné, můžu to změnit - vyhovovalo by více, kdyby jednou navštívená stránka zůstala na původním místě (tzn. seznam drobečků by se při návratu na už navštívenou stránku nezměnil), nebo kdyby se prostě přidala na konec, i když už v seznamu jednou je?

[Fluttershy, yay!]

Pak by byla lepší zvláštní drobečková navigace s historií.

[Messa]

Normálním uživatelům většinou stačí tlačítko Zpět v browseru, nemusí na to mít ještě odkazy na stránce

Drobečková navigace většinou sleduje nějakou logickou strukturu, tj. od stránky přes "parent" stránku, její parent stránku atd. až k homepage. jako třeba v Eshopech, např. Monitory - LCD - 24" a ne Monitory - LCD - 250 GB - Podložky pod myš.

[Josef Kufner]

Klasické drobečky jsou prostě pozice v hiearchii... něco jako cesta k adresáři na disku. To že se to chová takle jinak a vypadá tradičně je trochu matoucí.

Ale pokud chceš takovouhle historii, tak tam dej ukazovátko. Prostě když uživatel vleze někam, kde už byl, tak se posune ukazovátko na odpovídající položku, ale pozici položka nezmění. Pak ještě nějak smysluplně domyslet, co se stane, když pak půjde jinam a bude to supr

[herne the hunter]

hlásím bug (teda jestli je to vůbec bug): otevřel jsem si ty stránky do záložky a když jsem se k nim po minimálně hoďce a půl propracoval, dal jsem registraci. systém mi odpověděl "Invalid session. You were logged in but your session has expired. Please re-login."

ale jinak vážně super, přesně tohle mi moc chybělo :)

[Bluebear]

Je to bug; je způsobený tím, že po určité době vyprší cookie, což je v pořádku, ale engine si už neověřuje, jestli uživatel je nebo není zalogován, a rovnou ohlásí tuto chybu, což je špatně - pokud uživatel není zalogován, tak samozřejmě nebyl ani odlogován a měla by se bez řečí rovnou ukázat příslušná stránka. Mělo by pomoci normálně reloadnout stránku.

Opravím to ASAP.

[Tom.š Ze.le.in]

Přijde mi to jako velmi ambiciózní projekt. Držim palce.

Dotazy:

Je to mířené na Linux, nebo na SUSE? Pokud jsou či budou mezi distribucemi rozdíly, je cílem tam mít všechny varianty? Pokud dojde k vývoji, bude se nechávat informace pro staré Linuxy?

Musí tam být přímo data, nebo se lze spokojit s odkazy na autoritativní dokumenty? (The Filesystem => FHS), a případně popis větších detailů nebo komentáře tam kde třeba?

Vůbec, jaký je předpokládaný rozsah - gcc není jen pro Linux. Patří tam třeba perl? sbcl? Popis x86?

Bude se řešit to, že dnes zadaný popis čehosi tam může zastarat tak jako dnes info libc? Jak? (kdysi jsem udržoval dokumentaci pro jeden projekt, a informace o verzi ve které funkce vznikla, případně zanikla byla povinný atribut - a užitečný)

V rámci projektu by mohly být užitečné nástroje pro konverzi z man, docbook, info nebo čehokoliv. Plánují se, nebo se vše bude přepisovat ručně s verifikací? A pak duplicitně udržovat? A obráceně, když někdo bude udržovat dokumentaci v tomto, udělá z toho man page?

[Bluebear]

Přijde mi to jako velmi ambiciózní projekt. Držim palce.

Díky

Ambiciózní projekt to bezesporu je, nevím, jestli půjde zvládnout, ale chci to zkusit. Mám rozsáhlou zkušenost s neúspěšnými projekty, takže případný totální výbuch mi nic moc neudělá.

Je to mířené na Linux, nebo na SUSE?

Na Linux obecně.

Pokud jsou či budou mezi distribucemi rozdíly, je cílem tam mít všechny varianty?

Ano, i když doufám, že takových míst nebude moc. Například u package managerů bych tam rád měl dokumentaci ke všem, ne jen k rpm (rpm-kem jsem začal proto, že ho relativně lépe znám).

Musí tam být přímo data, nebo se lze spokojit s odkazy na autoritativní dokumenty?

Musí tam být přímo data, aby bylo všechno pohromadě, ve stejném formátu, prolinkované a vždy dostupné; odkaz na autoritativní dokument se rozhodně hodí, ale nestačí.

Vůbec, jaký je předpokládaný rozsah - gcc není jen pro Linux. Patří tam třeba perl? sbcl? Popis x86?

Ideál (samozřejmě nedosažitelný) je mít tam všechno, co linuxový developer může potřebovat - tedy glibc, kernel, manuály ke gcc, bashi, všem možným utilitám, atd. atp. Popis x86, případně dalších assemblerů, sice už není v hlavním proudu, ale v appendixech by se vyjímal dobře.

Bude se řešit to, že dnes zadaný popis čehosi tam může zastarat tak jako dnes info libc? Jak?

Rozhodně se to řešit bude - dokumentace musí zůstat aktuální, aby k něčemu byla. Technické řešení zatím nemám; například by se to dalo dělat tak, že když si někdo všimne, že stránka je neaktuální, ale neví, jak by měla být správně, tak ji označí nějakým tagem a stránka se pak ukáže v přehledech, takže kdo bude vědět, může ji aktualizovat. Mluvilo se i o automatizovaném updatu, ale to je spíš hudba budoucnosti.

V rámci projektu by mohly být užitečné nástroje pro konverzi z man, docbook, info nebo čehokoliv.

Ano, a mám je v plánu, i když nejdřív budu muset udělat řadu dalších věcí (přinejmenším opravit chyby). Automatický import z manu už je téměř hotov (není dokonalý, ale formát manu je tak hrozný, že to nejde udělat stoprocentně), ale bohužel v praxi není příliš užitečný, protože manuálové stránky jsou jinak strukturované, než bych potřeboval, a krom toho jsou tu licenční překážky.

Export bude zcela nepochybně. Musí být možnost si stáhnout celou dokumentaci na lokální stroj, aby ji mohl developer prohlížet bez nutnosti se pokaždé připojovat k netu. Přinejmenším do samostatného statického HTML, doufám, že se podaří i další formáty.

Nevím, jak to bude s manem či infem, protože struktura manuálových stránek a infostránek je jiná než struktura téhle dokumentace, ale čistě technicky převést jednu stránku do manu nebo do infa by neměl být problém.

[Tom.š Ze.le.in]

Bude se řešit to, že dnes zadaný popis čehosi tam může zastarat tak jako dnes info libc? Jak?

Rozhodně se to řešit bude - dokumentace musí zůstat aktuální, aby k něčemu byla. Technické řešení zatím nemám; například by se to dalo dělat tak, že když si někdo všimne, že stránka je neaktuální, ale neví, jak by měla být správně, tak ji označí nějakým tagem a stránka se pak ukáže v přehledech, takže kdo bude vědět, může ji aktualizovat. Mluvilo se i o automatizovaném updatu, ale to je spíš hudba budoucnosti.

Smazat nebo přepsat neaktuální možnost možná není úplně ideální. Může existovat přechodové období (třeba i dost dlouhé), kdy se používají obě možnosti. Nebo přijdu ke starému stroji. Nebo píšu skript, který chci aby byl obecně použitelný i na starších strojích. Nebo jsem ještě gtk aplikaci nepřevedl do gtk2. Nebo mne Michal Kubeček pořád ještě neodradil od ifconfigu.

Nevím, jak to bude s manem či infem, protože struktura manuálových stránek a infostránek je jiná než struktura téhle dokumentace, ale čistě technicky převést jednu stránku do manu nebo do infa by neměl být problém.

Bylo by smutné, kdybyste v rámci distribuce distribuovali tuhle dokumentaci v aktuální formě, ale všichni uživatelé četli zastaralé manuálové nebo info stránky (a uživatelé *jsou* konzervativní, a man *je* pohodlný na užívání).