Jaderné noviny - 8. 7. 2016: Dokumentace jádra ve Sphinx a jak jsme se sem dostali, část 1.

17. 7. 2016 | Redakce | Jaderné noviny | 2739×

Stav vydání jádra. Dokumentace jádra ve Sphinx a jak jsme se sem dostali, část 1.

Stav vydání jádra

Současný vývojový kernel má označení 4.7-rc6, vydán byl 3. července. „Rád bych řekl, že se věci uklidňují a jejich objem se zmenšuje, ale to bych lhal. Nejde zrovna o obrovské rc, ale je rozhodně větší než předchozí rc. Nemyslím si, že to je nutně zásadní problém, spíš se jedná hlavně o načasování.“

Čtvrtá verze seznamu regresí v 4.7 Thorstena Leemhuise byla vydána 2. července. Obsahuje 14 záznamů včetně dvou nových a čtyř, jejichž opravy směřují do hlavního repozitáře.

Stabilní aktualizace: V minulém týdnu žádné nevyšly, stabilní verze jádra 4.6.4 byla v době psaní tohoto článku v procesu revidování a vyšla 11. července.

Dokumentace jádra ve Sphinx, část první: Jak jsme se sem dostali

Na LWN se o formátované dokumentaci jádra psalo naposledy v lednu. Tehdy to vypadalo, že začlenění podpory AsciiDoc pro strukturovanou dokumentaci zdrojového kódu jádra („kernel-doc“) je na spadnutí. Jak napsal Jonathan Corbet ve funkci správce dokumentace jádra: „Nasazení stávajícího přijatelného řešení by se nemělo zdržovat příliš dlouho v naději, že by se časem nejasné myšlenky na něco jiného mohly proměnit ve funkční kód.“ Nicméně, někdy hrozba, že by mohlo dojít k začlenění něčeho nedokonalého, stačí k tomu, aby se lidé odhodlali k proměně neurčitých myšlenek v něco skutečného.

Nakonec se jako budoucnost dokumentace jádra objevují Sphinx a reStructuredText, navíc s mnohem ambicióznějšími cíli, než jaké měly původní patche pro podporu AsciiDoc. Vzhledem ke značnému objemu práce na infrastruktuře, začleněnému do větve docs-next směřující do vydání 4.8, nyní nastává vhodná doba popřemýšlet nad tím, jak se to vlastně stalo, a poskytnout přehled o slibné budoucnosti dokumentace jádra.

Pozadí

Patche k podpoře jednoduchého značkovacího jazyka (původně Markdown, později AsciiDoc) v komentářích kernel-doc vznikly na popud potřeby lepší dokumentace grafického subsystému. Jedním z cílů bylo zlepšit dokumentaci vnitřností grafického subsystému přímo v kódu, a to ze dvou důvodů. Za prvé, pokud je dokumentace vedle kódu, který popisuje, má větší šanci být aktualizována spolu s kódem. Za druhé, pokud je možné dokumentaci psát v prostém textu místo XML DocBooku, je větší šance, že ji někdo vůbec napíše.

Jenže prostý text se ukazuje býti až příliš prostý, chcete-li dokumentovat více než jen funkce a typy, potažmo chcete-li generovat hezké HTML nebo PDF dokumenty. Přidání podpory jednoduchého značkovacího jazyka do komentářů kernel-doc tak bylo přirozené. Bohužel se ukázalo, že našroubování této funkcionality na existující sadu nástrojů kolem DocBooku je problematické.

Jako součást procesu sestavení dokumentace extrahuje skript scripts/kernel-doc strukturované komentáře a zpracovává je do formátu DocBook. Skript kernel-doc podporuje nějaké to strukturování, ale jen velmi málo formátování. Aby to vše fungovalo, patche pro podporu jednoduchého značkovacího jazyka přidaly do kernel-doc volání externího konverzního nástroje (původně pandoc, později asciidoc) pro každý blok dokumentačních komentářů, který byl převeden z příslušné jednoduché syntaxe do DocBooku. Bylo to zoufale pomalé.

Konverze v kernel-doc udržovala věci na straně DocBooku více méně netknuté a lhostejné k jakékoliv další značkovací syntaxi, ale přidávala další příležitost k selhání na již tak dost dlouhé a trnité cestě od komentářů k HTML nebo PDF. Problémy se značkovací syntaxí a chybami v dílčích krocích konverze činily ladění velmi náročným. Použité nástroje nebyly navrženy k vzájemné spolupráci a často si navzájem odporovaly v tom, kdy a jak by se měla používat která syntaxe.

Bylo jasné, že nešlo o ideální řešení, ale toho času to fungovalo a nic lepšího nebylo k dispozici.

Sázka na AsciiDoc, vody se kalí

Inspirován Jonathanovým článkem a frustrován zdlouhavým sestavováním dokumentace (testovali jsme patche v integračním stromu grafiky Intel), dostal jsem nápad upravit kernel-doc, aby jeho výstupem byl přímo AsciiDoc namísto DocBooku. Převést několik strukturálních prvků z komentářů do AsciiDocu a ponechat zbytek bylo triviální. kernel-doc již podporoval několik výstupních formátů s rozumnou abstrakcí. Jak to tak bývá, při zpětném ohlédnutí se to jevilo jako samozřejmost. Najednou se otevřely dveře k psaní všech vysokoúrovňových dokumentů z Documentation/DocBook v AsciiDocu, vkládání dokumentačních komentářů na této úrovni a k možnosti zcela se zbavit šablon DocBooku. Přineslo to velké výhody a Jonathan na to brzy navázal s ověřením koncepce, které to potvrzuje.

Strhl se kolem toho docela povyk. Lidé zkoumali, experimentovali a opravdu zkoušeli konverzi dokumentů. Řada debat mezi zainteresovanými vývojáři na linux.conf.au dále potvrzovala, že by mohlo jít o cestu vpřed. Ale když už se zdálo, že přechod k AsciiDoc je jasná věc, Jonathan všechny znejistěl uvedením Sphinx jako alternativy k AsciiDoc.

Sphinx vs AsciiDoc

Sphinx je generátor dokumentace, který používá značkovací jazyk reStructuredText a parser Docutils. Jak Sphinx, tak Docutils vznikly v Pythonu za účelem nasazení v dokumentaci Pythonu, ovšem podporují i dokumentaci kódu v C a C++. Sphinx podporuje několik formátů přímo, např. HTML, LaTeX či ePub, a PDF podporuje skrze LaTeX nebo externí nástroj rst2pdf.

Na druhé straně je AsciiDoc sémanticky ekvivalentní s DocBookem, jen místo XML používá syntaxi jednoduchého značkovacího jazyka. Je čitelnější než XML a lidem se snáze píše, ale protože je navržen k překladu do DocBooku, krásně zapadá do jeho sady nástrojů. Původní nástroj AsciiDoc napsaný v Pythonu není žádná novinka, ale nedávno byl nahrazen reimplementací v Ruby, nazvanou Asciidoctor. Co se syntaxe AsciiDocu týče, Asciidoctor byl navržen jako přímá náhrada, ale veškerá rozšíření jsou kvůli změně implementačního jazyka závislá na implementaci. Oba nástroje nativně podporují HTML a DocBook, další výstupní formáty jsou přístupné přes DocBook.

Ve srovnání formátů pro potřeby dokumentace jádra vyšel AsciiDoc jako výrazně lepší pouze v podpoře tabulek, která je zásadní zejména v dokumentaci subsystému médií. Jinak jsou výsledky spíše nerozhodné, takže porovnání je nakonec omezené jen na dílčí nástroje a programovací jazyky, v nichž jsou napsány. Syntaxe a příslušné nástroje jsou na sobě totiž závislé. Všechny varianty mají svá pro i proti.

Na první pohled by implementační jazyk nástroje neměl při rozhodování hrát roli. Ale vypadalo to, že ani jeden z nástrojů by nefungoval bez úprav, nebo že bychom z něj bez úprav nedokázali vytáhnout maximum. V jaderném stromu nejsou žádné nástroje napsané v Ruby, naopak těch napsaných v Pythonu je spousta. V tomto ohledu se příklon ke Sphinx vcelku nabízel.

Hledáte-li flexibilitu, pak jednoznačnou výhodou AsciiDoc je úzké provázání s DocBookem. Při přechodu na AsciiDoc by dokumentace jádra mohla nadále využívat stávající nástroje pro DocBook. Nevýhodou je, že Asciidoctor by přidal další krok na začátek už tak křehkého procesu zpracování nástroji DocBooku. Dan Allen z Asciidoctoru k tomu řekl: „Jedním z hlavních cílů projektu Asciidoctor je schopnost produkovat výstup v široké škále formátů přímo ze stejného zdroje (bez použití DocBooku).“ Nicméně současná podpora k tomu má bohužel ještě daleko.

Projekt Asciidoctor má slibnou budoucnost. Ale Sphinx je stabilní, dostupný nyní a odpovídá potřebám jádra. Grant Likely to shrnul následovně: „Upřímně řečeno, myslím, že bychom pro naše potřeby asi mohli využít libovolný z těch dvou nástrojů. Nicméně poté, co jsem se pokusil vytvořit hezký, publikovatelný dokument oběma nástroji, jsem seznal, že se Sphinx se lépe pracuje, [Sphinx] se jednodušeji rozšiřuje a má lepší podporu.“ Nakonec se Jonathan rozhodl pro Sphinx. Patche byly začleněny a první dokumentace s využitím Sphinx se objeví v jádře 4.8.

Druhá a poslední část této série bude o tom, jak nová sada nástrojů Sphinx pracuje a jak s její pomocí psát dokumentaci.

       

Komentáře

[aceman]

AsciiDoctor?

[Marián Petráš]

Hádám, že to vzniklo takto: AsciiDoc to R(uby)

[Bystroushaak]

No, jsem trochu skeptický. Abych to uvedl do kontextu - za poslední 3 roky jsem napsal pravděpodobně stovky kilobajtů sphinx dokumentace a pomáhal zformátovat jednu knihu. Během té doby jsem si mnohokrát přál, abych nemusel používat sphinx, resp. retardované rst, ale mohl použít prostě XML. Speciálně, pokud člověk ladí dvě verze (HTML a PDF), tak je to totální bolestivý omrd z boku. Dokumentace taky stojí v mnoha ohledech za hovno, takže jsem končil hrabáním se v python zdrojácích, které jsou mimochodem místama totální javovská zprasenina.

[Jendа]

Nikdy jsem to neviděl, tak jsem to proletěl a vypadá to podobně jako markdown.

Na všech těchto věcech (markdown, dokuwiki, částečně mediawiki…) mě neuvěřitelně vytáčí komplikované escapování. Například v HTML je to triviální, stačí si pamatovat, že se escapují <> a &. Tohle obsahuje spoustu různých formátovacích znaků a sekvencí, o kterých člověk vůbec nemusí tušit, že je parser sežere jako řídící, případně není způsob escapování hned zjevný. Specifikace escapování tak není na dvě věty, ale na dvě knihy. Různé parsery/kompilátory to mohou dělat trochu jinak a nedejbože v další verzi přibude něco dalšího a existující text se rozbije.

Myslím, že příklad návrhového failu z odkazované stránky je

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Co když chci, aby byl zdroják indentovaný?

Další věc, která se mi např. v DokuWiki prostě nepodařila udělat, je formátování (tučnost, barva) uvnitř <pre> -- takže nejde udělat zdroják nebo ascii art s ručně ztučněnými důležitými částmi.

Atd.

[Filip Jirsák]

Zajímalo by mne, zda za těmi stovkami dokumentových formátů desetkrát složitějších než XML je opravdu jenom fóbie ze špičatých závorek, nebo i něco jiného. Možná by stačilo vydat nový standard XML, kde by se místo špičatých závorek používaly složené…

[Tom.š Ze.le.in]

Nebo kulaté. A možná by stačila na konci místo ozávorkovaného jména tagu zavírací závorka. Ta by se pak nemusela psát u otvíracího tagu.

Aha, to tu už bylo.

[Filip Jirsák]

Kulaté ne, ty se přeci jen v běžném textu používají dost často.

[deda.jabko]

Zajímalo by mne, zda za těmi stovkami dokumentových formátů desetkrát složitějších než XML je opravdu jenom fóbie ze špičatých závorek, nebo i něco jiného.

Ano, zejmena to, ze XML je na rucni tvorbu textu zoufale ukecane. Jenom udelat text <b>tucne</b> je na sedm znaku coz, je *zbytecne* moc, kdyz staci dva. Pokud chci odrazky, musim tam cpat <ul>, a pak <li> a to vsechno dvakrat, misto toho abych udelal, enter + hvezdicka nebo neco podobneho, coz opravdu prudi.

desetkrát složitějších než XML

Zajimalo by me, kolik lidi opravdu rozumi XML vcetne takovych detailu jako jsou entity nebo jmenne prostory.

[Jendа]

Jenom udelat text <b>tucne</b> je na sedm znaku coz, je *zbytecne* moc, kdyz staci dva.

Jenže právě přivlastnění hvězdičky, podtržítka a lomítka, což jsou v technických poznámkách dost časté znaky, pak způsobuje ten opruz, že člověk musí neustále escapovat.

[deda.jabko]

Jenže právě přivlastnění hvězdičky, podtržítka a lomítka, což jsou v technických poznámkách dost časté znaky, pak způsobuje ten opruz, že člověk musí neustále escapovat.

Ve vyse zvyraznenem textu je zakopan pes. Ne vsichni pisou technicke poznamky. A pan Jirsak se pta, proc vznikaji stovky ruznych formatu. Muzes si tedy vybrat, bud si poridis naprosto univerzilni nastroj a delat v nem i bezne veci bude opruz, nebo pro kazdou situaci pouzijes vhodny nastroj a smiris se s tim, ze nektere specializovane veci bude trochu vetsi opruz.

[Bystroushaak]

Ve Sphinxu, což je programátorský dokumentační systém na zdrojové, prakticky všichni píšou jen technické poznámky.

[Filip Jirsák]

Problém je v tom, že se vždycky ukáže, že dva znaky nestačí. Že jsou potřeba tabulky, makra… Ten „jednoduchý text“ rázem vypadá jak zdroják v Perlu, a oproti XML jsou ty konstrukce možná o pár znaků kratší, ale mnohem méně čitelné (protože obvykle intuitivně nepoznáte, co kde začíná a končí).

Pro takovouhle dokumentaci entity nepotřebujete znát vůbec, a jmenné prostory výjimečně (pokud chcete do jednoho jazyka vložit jiný – což se v těch stovkách „jednoduchých textových“ formátů dělá také stovkami způsobů).

Jinak ono je klidně možné používat formát, kde prázdný řádek znamená oddělení odstavců, hvězdičky znamenají tučné písmo a hvězdička na začátku řádku odrážku. Ale jakmile do tohohle formátu někde začne přidávat cokoli složitějšího, měl by si dát facku – cokoliv složitějšího nemá smysl psát v něčem jiném, než v XML. Nemá smysl vytvářet další a další formáty, které ve skutečnosti jsou definované jenom jedinou implementací parseru.

[deda.jabko]

Problém je v tom, že se vždycky ukáže, že dva znaky nestačí. Že jsou potřeba tabulky, makra… Ten „jednoduchý text“ rázem vypadá jak zdroják v Perlu, a oproti XML jsou ty konstrukce možná o pár znaků kratší, ale mnohem méně čitelné (protože obvykle intuitivně nepoznáte, co kde začíná a končí).

Neverim. Napr. dokumentace k MyJIT je psana v RST a prekvapive to jako zdrojak v perlu nevypada (napriklad), i kdyz tam jsou zakomponovane zdrojaky, apod. a jde to cist i v beznem textovem editoru/konzoli. Navic, leze z toho pekne HTML i PDF.

Pro takovouhle dokumentaci entity nepotřebujete znát vůbec, a jmenné prostory výjimečně (pokud chcete do jednoho jazyka vložit jiný – což se v těch stovkách „jednoduchých textových“ formátů dělá také stovkami způsobů).

To byla spise takova sarkasticka poznamka k jednoduchosti XML.

Ale jakmile do tohohle formátu někde začne přidávat cokoli složitějšího, měl by si dát facku – cokoliv složitějšího nemá smysl psát v něčem jiném, než v XML.

A proto, mile deti, vsichni matematici pisou vedecke prace v MathML. </ironie>

[Filip Jirsák]

Neverim. Napr. dokumentace k MyJIT je psana v RST a prekvapive to jako zdrojak v perlu nevypada (napriklad), i kdyz tam jsou zakomponovane zdrojaky, apod. a jde to cist i v beznem textovem editoru/konzoli.

Jenže tam není nic složitého, používají se tam čtyři formátovací prvky. To se pomocí těch hvězdiček a pomlček zvládnout dá. V tomto případě je nevýhoda "pouze" to, že každý z těch jednoduchých jazyků používá jiný zápis pro ty základní formátovací prvky (nadpisy, tučné písmo, kurzíva). Na to snad musí existovat nějaká komise, která ty znaky přiděluje, aby to žádné dva jazyky neměly stejné...

A proto, mile deti, vsichni matematici pisou vedecke prace v MathML.

Předpokládám, že matematika se nejvíc píše v TeXu a LaTeXu. Což jsou zase jazyky, které mají obecná jednoduchá a srozumitelná pravidla pro zápis "maker". Srovnejte pravidlo "každé makro začíná zpětným lomítkem, následuje název makra a ve složených závorkách jeho parametry" s pravidlem pouze pro formátování tučného textu a kurzivy, které je popsané na celou obrazovku a ještě to není ani zdaleka kompletní.

Navíc ten váš argument neodporuje mému tvrzení. Ona se ta matematika občas píše i v tom MathML. Ale kolik matematických prací jste viděl napsaných v Markdown, RST, Sphinx, MediaWiki nebo něčem podobném?

[Fluttershy, yay!]

Předpokládám, že matematika se nejvíc píše v TeXu a LaTeXu. Což jsou zase jazyky, které mají obecná jednoduchá a srozumitelná pravidla pro zápis "maker". Srovnejte pravidlo "každé makro začíná zpětným lomítkem, následuje název makra a ve složených závorkách jeho parametry" s pravidlem pouze pro formátování tučného textu a kurzivy, které je popsané na celou obrazovku a ještě to není ani zdaleka kompletní.

To zní jako výrok někoho, kdo ten (La)TeX nikdy moc nepoužíval.

Řada znaků se musí escapovat tak jako tak. Různá makra (ne)fungují v závislosti na prostředí. Parametry se píšou nahodile – někdy do hranatých, jindy do chlupatých, ba dokonce žádných závorek (podle původu makra). Tabulky jsou kapitola sama pro sebe.

Ale kolik matematických prací jste viděl napsaných v Markdown, RST, Sphinx, MediaWiki nebo něčem podobném?

To není úplně dobrá otázka, protože z výsledné publikace se moc nepozná, co kdo použil na začátku řetězce… pokud celý řetězec není nějaké zvěrstvo typu MS Word. (Což je jedna možná cesta, jak se dostat k těm lehkotonážním nástrojům… a když jsme u toho, samotný autor Pandoc je filosof/logik.)

[Michal Kubeček]

Řada znaků se musí escapovat tak jako tak. Různá makra (ne)fungují v závislosti na prostředí. Parametry se píšou nahodile – někdy do hranatých, jindy do chlupatých, ba dokonce žádných závorek (podle původu makra).

Ono je to ve skutečnosti ještě mnohem horší (hint: kategorie znaků a \catcode). Ale tohle drtivá většina matematiků neví a naštěstí vědět nepotřebuje.

[Josef Kufner]

Proto LaTeX vůbec vzniknul. TeX má ta pravidla šílená, ale LaTeX zavádí právě tyhle hezké konvence, jak makra psát.

[deda.jabko]

Problém je v tom, že se vždycky ukáže, že dva znaky nestačí

Jenže tam není nic složitého, používají se tam čtyři formátovací prvky.

Je tam tucne, kurziva, escapovany text, zdrojaky, tri nebo ctyri druhy nadpisu, odkazy. Co realne potrebujes vic pro dokumentaci API nebo nejakeho kodu? (Obzvlast, pokud chces mit text, ktery pujde editovat/zobrazit i v beznem textovem rezimu.)

Ona se ta matematika občas píše i v tom MathML.

,,Obcas.'' :-]]

Navíc ten váš argument neodporuje mému tvrzení

To zcela jiste, protoze tu nekdo tvrdil:

cokoliv složitějšího nemá smysl psát v něčem jiném, než v XML.

Ale kolik matematických prací jste viděl napsaných v Markdown, RST, Sphinx, MediaWiki nebo něčem podobném?

Kdo rika, ze tyto nastroje jsou urcene pro psani matematickeho textu?

Razim tezi, ze je lepsi mit na kazdou praci vhodny nastroj, ktery ti danou praci umozni delat pohodlne, nez mit univerzalni nastroj, kde delat i ty nejbeznejsi veci je otrava. Z vlastni zkusenosti bych rekl, ze delat dokumentaci v XML je asi jako jist rizek lzici. Ne, ze by to neslo, ale radsi si na to vezmu neco jineho.

[Filip Jirsák]

Je tam tucne, kurziva, escapovany text, zdrojaky, tri nebo ctyri druhy nadpisu, odkazy. Co realne potrebujes vic pro dokumentaci API nebo nejakeho kodu? (Obzvlast, pokud chces mit text, ktery pujde editovat/zobrazit i v beznem textovem rezimu.)

Stačí si přečíst článek, pod kterým diskutujeme.

Razim tezi, ze je lepsi mit na kazdou praci vhodny nastroj, ktery ti danou praci umozni delat pohodlne, nez mit univerzalni nastroj, kde delat i ty nejbeznejsi veci je otrava.

S tím souhlasím. Přičemž AsciiDoc, Markdown, MediaWiki ani další podobné „plaintext formáty“ nepovažuju za vhodné nástroje pro složitější formátování, makra nebo šablony. Pokud chce někdo tučné písmo vyznačovat hvězdičkami, ať to klidně dělá (i když by bylo fajn dohodnout se na tom, že tučné písmo bude třeba vždy hvězdička). Ale jakmile je potřeba něco složitějšího – obrázek, tabulka, makro, šablona – ať se autoři vykašlou na implementaci speciálních formátů do těch „plaintext“ formátů a použijí normální HTML nebo XML. Protože to je přesně ten okamžik, kdy ten „plaintext“ formát přestává být vhodný nástroj a začíná být neuvěřitelně otravný.

[Fluttershy, yay!]

Ale jakmile je potřeba něco složitějšího – obrázek, tabulka, makro, šablona – ať se autoři vykašlou na HTML nebo XML a použijí normální „plaintext“ formát. Protože to je přesně ten okamžik, kdy to HTML nebo XML přestává být vhodný nástroj a začíná být neuvěřitelně otravné.

[Jendа]

Přesněji řečeno „plaintext“ formát, ve kterém tak „pokročilé“ věci, jako to tučnění uvnitř <pre>, které v něm udělat nejdou, stejně budou muset vyřešit pomocí HTML?

[Fluttershy, yay!]

Obávám se, že ti uniká sémantický smysl <pre>.

To, co chceš, je pravděpodobně něco jako line_blocks, což je věc přítomná v RST nebo Markdownu z Pandoc.

[Filip Jirsák]

z Pandoc

Myslím, že tohle mluví za vše. Formát, který je v každé implementaci jiný.

[Jendа]

To, co chceš, je pravděpodobně něco jako line_blocks, což je věc přítomná v RST nebo Markdownu z Pandoc.

Ne, potřebuju, aby se to vysázelo monospace fontem. Účelem je udělat ascii art nějaké součástky a zvýraznit některé nožičky.

To, co chceš, je pravděpodobně něco jako line_blocks, což je věc přítomná v RST nebo Markdownu z Pandoc.

Aha, takže si ještě musím vybrat ten správný markdown. Doufám, že v něm nebudou zase jiné chyby.

[Fluttershy, yay!]

Účelem je udělat ascii art nějaké součástky a zvýraznit některé nožičky.

Což není úkol pro předformátovaný text.

Ne, potřebuju, aby se to vysázelo monospace fontem.

Tak si nastav výstupní šablonu.

[Bystroushaak]

Což není úkol pro předformátovaný text.

Pro co je to úkol?

[deda.jabko]

S tím souhlasím. Přičemž AsciiDoc, Markdown, MediaWiki ani další podobné „plaintext formáty“ nepovažuju za vhodné nástroje pro složitější formátování, makra nebo šablony

A v tom je to hlavni nepochopeni. Jsou to totiz formaty, ktere umoznuji pohodlnou tvorbu/psani textu/dokumentace v beznem textovem editoru. Pokud potrebujes text formatovat, mas tu LaTeX nebo InDesign.

[Filip Jirsák]

Jenže ty formáty se snaží umožnit i formátování. Podívejte se třeba na Wikipedii. Vytvářet články v InDesignu nebo LaTeXu by asi nebylo možné. Pro jednoduché formátování odstavců tak wiki syntaxe dává smysl. Ale obrázky, tabulky, šablony, ty už by byly srozumitelnější v XML, a navíc se tam stejně používá přímo HTML (aspoň že to wiki umožňuje), protože některé věci stejně ve wiki syntaxi napsat nejde.

[Bystroushaak]

Co když chci, aby byl zdroják indentovaný?

::

  Indentovaný
    zdroják

Sphinx umožňuje vkládat i html a latex, ale .. ale. Prostě to místama fakt bolí. Co jsem já měl problém, tak třeba s obrázkama a jejich titulkama, na které se chci referencovat z textu s názvem strany / kapitoly. Třeba „Obrázek 2.4.5 - Popisek“, protože když si to někdo vytiskne, tak je mu reference pomocí popisku / názvu obrázku k ničemu, když neví, kde ho má hledat. Což mě přivádí k dalšímu problému, že layout obrázků v PDF stojí za vyližprdel a klidně ho to nacpe o pět stránek vedle, podle toho jak se mu to hodí.

Jako já nejsem žádný knižní nazi, který by si potrpěl na sázení podle pravidel a tak, ale už jen udělat tu knížku, aby nebyla vysloveně dementní si žádá spoustu různých úprav specificky pro PDF, které jsou občas úplně v konfliktu s tím co má být v HTML.

Pak to dopadá tak, že kód je plný sraček jako:

.. only:: html

  .. figure:: images/Pgm_Env_Image2.*
      :scale: 80

.. only:: not html

  .. figure:: images/Pgm_Env_Image2.*
      :scale: 50

Protože některé (zdaleka ne všechny, jinak by se to dalo poladit výstupní šablonou) obrázky musím přeškálovávat, jinak je to vrazí nesmyslně velké na samostatnou stránku. Což vede k duplikaci kódu.

Přijde mi, že prostě autoři sphinxu nepapají vlastní medicínu. Nechal bych je v tom dělat něco co se má renderovat do více formátů a imho by jim to došlo, protože to jsou fakt základní problémy.

Jinak problémů tohohle rázu jsem měl desítky, až mě to přivedlo k myšlence, že pokud budu někdy takhle sázet knihu, tak asi použiju snad lisp, nebo nějaké jiné programovadlo, protože se prostě hodí mít i v tom značkovacím jazyku podmínky a funkce a tak podobně (jo, vím že latex toho umí hodně, ale zase má svoje problémy a je to konstantní boj pokaždé, když chci něco netriviálního).

[Fluttershy, yay!]

Což mě přivádí k dalšímu problému, že layout obrázků v PDF stojí za vyližprdel a klidně ho to nacpe o pět stránek vedle, podle toho jak se mu to hodí.

To zní jako obyčejné plovoucí prostředí v LaTeXu. V tom případě by sis měl upravit šablonu (banální) nebo aspoň vzít v potaz, že takhle se za určitých okolností sazba dělá.

protože se prostě hodí mít i v tom značkovacím jazyku podmínky a funkce a tak podobně (jo, vím že latex toho umí hodně, ale zase má svoje problémy a je to konstantní boj pokaždé, když chci něco netriviálního)

TeX je totiž obskurní programovací jazyk a většina dostupných informací je zoufale zastaralá. Ono by „stačilo“ mít rozumnou aktualizovanou programátorskou příručku k jádru a základním principům, jenže to už by možná vyšlo jednodušeji napsat moderní systém (se stejnými algoritmy) od píky.

[Bystroushaak]

Sazba se nedělá tak, že to vezme 100px obrázek, ten to roztáhne na šířku celé A4, až jsou vidět jednotlivé pixely a tohle celé umístí na samostatnou stránku. Uznávám, že je to záležitost konfigurace, ale to nic nemění na tom, že je to blbě by default.

Druhá věc je, že to nedělá vždycky, ale jen někdy, takže nemůžeš jednoduše změnit výstupní šablonu, protože ta to mění vždycky a pak zas vypadají blbě jiné obrázky. Myslím, že to je právě nějaká sphinxovina, která chrlí špatný latex kód.

[Jendа]

::

  Indentovaný
    zdroják

Nechápu. Jako že to sežere na začátku řádku vždycky právě dvě mezery? Takže je to ještě horší než Python, kde je to alespoň přiměřeně inteligentní a neřeší to, kolik těch mezer tam přesně je, nebo jestli jsou tam taby?

[Bystroushaak]

Je to stejné jako python. Ostatně je to psané v pythonu, který imho sloužil jako inspirace.

Tohle je třeba reálný příklad:

Příklad (soubor ``/etc/webarchive/wa_kat.json``)::

    {
        "WEB_ADDR": "0.0.0.0",
        "WEB_DEBUG": true,
        "WEB_RELOADER": true,

        "SEEDER_TOKEN": "1acedb1b6347d9d40fe2f055aa6d3c077f106894", 

        "ZEO_CLIENT_PATH": "/home/bystrousak/web/WA-KAT/conf/zeo_client.conf",
        "ZEO_MAX_WAIT_TIME": 60
    }

Což pak vypadá takhle: http://wa-kat.readthedocs.io/en/latest/admin_manual.html#konfigurace-wa-katu

[Jendа]

No právě, sežralo to whitespace na začátku. Kdybych s tím chtěl udělat

    {
        "WEB_ADDR": "0.0.0.0",
        "WEB_DEBUG": true,
        "WEB_RELOADER": true,

        "SEEDER_TOKEN": "1acedb1b6347d9d40fe2f055aa6d3c077f106894", 

        "ZEO_CLIENT_PATH": "/home/bystrousak/web/WA-KAT/conf/zeo_client.conf",
        "ZEO_MAX_WAIT_TIME": 60
    }

(všimni si, že je to celé odsazené), tak budu potřebovat nějakou extra věc, co není v té stručné dokumentaci, pokud to vůbec půjde (např. v DokuWiki podle mě tučný text uvnitř <pre> (jejich <code>) prostě nijak udělat nejde). A tak je to tam se vším. Zato v HTML se člověk naučí těch pár pravidel a prostě to funguje. Nebo jsem deformovaný tím, že HTML byl dlouhou dobu jediný značkovací jazyk, který jsem znal?

[Bystroushaak]

Jo, takhle. Já tohle řeším unicode nonbreakable mezerama (stačí na začátek). Jinak já souhlasím s tím, že prostě *ML je v tomhle jednodušší.

[Ruža Becelin]

To je taky mozna ten duvod, proc je dneska problem dostat rozumnou dokumentaci v v PDF/ePUB/MOBI - dokumentace se necha prezvykat readthedocs a vyblije to HTML, takze cokoli na off-line cteni ee. Snaha pridat tam PDF vystup vede dost casto k tomu, ze to nefunguje vubec, nebo z toho lezou zmetky.

Asi maji byt vsichni on-line furt nebo co

[Fluttershy, yay!]

Třeba pandoc umí self-contained HTML, do kterého jsou nabouchané i obrázky, takže se to dá používat úplně offline a nezávisle na adresářové struktuře. Používám to na slajdy.

[Ruža Becelin]

Aha, to jsem nevedel - je tam kvalitativni rozdil mezi timhle a treba epub?

[Fluttershy, yay!]

Když se zavolá pandoc --self-contained (…), vyrobí to něco jako MHT (webové archivy toho času Opery a MSIE), kde jsou zahrnuty všechny externí věci (skripty, stylopisy, obrázky jako bloky binárního kódu). Funguje to všude IME.

Používám to na zmíněné prezentace (které se odkazují na některý, často sofistikovaný prezentační framework) nebo kvůli obrázkům (včetně těch generovaných online skripty pro konverzi latexových vzorců na bitmapy).

EPUB je oproti tomu archiv, který obsahuje všechny příslušné soubory (text, obrázky, písma) zvlášť.

Pandoc umí dělat i knížky v EPUB, ale musí se to nějak nakonfigurovat, s čímž jsem si hrál toliko jednou, a to dávno.

[Ruža Becelin]

Parada, kouknu na to, dik...

[Jendа]

Tobě se HTML blbě zobrazuje na nějaké čtečce nebo v čem je problém?

PDF se podle mě na text prohlížený elektronicky zoufale nehodí, protože mě fakt nezajímají žádné stránky - i na čtečce s einkem, kde je refresh drahý, bych si nastavil, že page down posune jenom o 80 % stránky, ne o celou -- prostě proto, že u většiny věcí, které nejsou jednoduchá lineární beletrie , potřebuju vidět kus historie, abych neztratil kontext.

[Ruža Becelin]

HTML se mi zobrazuje dobre, ale u slozitejsich veci jsou to tuny souboru, co se museji nacitat, neexistuje vyhledavani (protoze to neni jeden soubor), apod.

Co se preferenci cteni tyce, u me to je ePub -> PDF -> single_html -> multi html

[Bystroushaak]

PDF se podle mě na text prohlížený elektronicky zoufale nehodí, protože mě fakt nezajímají žádné stránky - i na čtečce s einkem, kde je refresh drahý, bych si nastavil, že page down posune jenom o 80 % stránky, ne o celou -- prostě proto, že u většiny věcí, které nejsou jednoduchá lineární beletrie , potřebuju vidět kus historie, abych neztratil kontext.

PDF musíš dělat primárně, teprve pak z toho (zdroje) můžeš generovat HTML a whatnot. Opačně to nefunguje - ePub/HTML prostě neobsahuje potřebné informace o formátování.