Pro koho to je

Dokumentaci do Markdownu i s kódem

Clean Clipper přečte jazyk bloku přímo ze stránky – z třídy ohrazení, z rodičovského prvku nebo ze značek, které za sebou nechal zvýrazňovač – a zapíše ho do ohrazení. Na technickém korpusu tak značka přežila v 73 blocích ze 156, proti 20 a 0 u dvou porovnávaných nástrojů.

Proč je vložený kód k ničemu

Dokumentace je z větší části kód a většina clipperů zahodí právě ten. Blok vyjde jako holé ohrazení bez značky jazyka, takže v Obsidianu, ve VS Code i na GitHubu zůstane šedý. Doplnit python nebo js ručně u třiceti bloků je přesně ta práce, které jste se klikáním na ikonu chtěli vyhnout.

Druhá polovina problému jsou tabulky. Srovnání parametrů, ve kterém má buňka seznam nebo krátkou ukázku kódu, obecné převodníky složí do jediného řádku – a poznámka je nepoužitelná zrovna v místě, kvůli kterému jste ji ukládali. K tomu se do textu přimíchá postranní navigace dokumentace a přepínač verzí, které vypadají jako obsah, ale obsah nejsou.

Za pár měsíců se to vymstí potřetí. Úryvek putuje do firemní wiki nebo do popisu pull requestu a stojí tam šedý, protože ohrazení nenese jazyk. A když dvě poznámky popisují tutéž funkci ze dvou verzí referenční příručky, ani jedna neřekne, o kterou verzi šlo: číslo verze bylo v adrese a adresa se při kopírování ztrácí jako první. Poznámka pak na nic neodpovídá, jen vás pošle zpátky na stránku, ze které vznikla.

Co se změní

• Blok vyjde jako ```python, ne holý – zvýraznění v Obsidianu, VS Code i na GitHubu funguje hned po vložení
• Jazyk se z kódu nehádá: čte se třída, kterou nechal zvýrazňovač daného webu, takže značka je přesně tak správná jako zdrojová stránka
• Tabulka s kódem nebo seznamem v buňce se už nesloží do jediného řádku
• Postranní navigace dokumentace, drobečky a přepínač verzí se odříznou, ne převedou
• Nula zbylých HTML značek napříč 512 změřenými stránkami – v textu nezůstane div ani span
• README na GitHubu, odpovědi ze Stack Overflow a dokumentace frameworků byly původní testovací korpus
• Odkazy v textu se mění na poznámky pod čarou [^1], jejichž definice stojí až na konci souboru
• Adresa zdroje je ve frontmatteru – u verzované dokumentace drží, kterou verzi poznámka popisuje
• Na přehledu balíčků nebo ve výsledcích hledání rozšíření řekne „žádný článek“, místo aby uložilo tři sta odkazů

Seznam se dá používat jako zásobník, kde se poslední přidaná
položka odebírá jako první:

```python
zasobnik = [3, 4, 5]
zasobnik.append(6)
zasobnik.pop()
```

## 5.1.2. Použití seznamu jako fronty

Jak uložit stránku dokumentace

Šest úkonů, z nichž první čtyři jsou jednorázové nastavení. Potom stojí každá další stránka dokumentace jeden stisk kláves.

1. Otevřete nastavení a v položce cílové složky vyberte adresář, kam mají poznámky padat. Může to být složka přímo v pracovním stromu projektu, třeba docs/vystrizky. Prohlížeč se na přístup zeptá jednou a povolení si zapamatuje.
2. Šablonu názvu přepněte na {domain}-{title}. U dokumentace je doména užitečnější polovina jména souboru: na první pohled prozradí, jestli úryvek pochází z oficiální reference, nebo z příspěvku ve fóru.
3. Obrázky přepněte na „vynechat“. Ilustrace ve vývojářské dokumentaci bývají diagramy, které jako odkaz na cizí web stejně nepomůžou, a soubor zůstane bez řádků s obrázky.
4. Založte pravidlo pro referenci, do které se díváte nejčastěji: zadejte vzor adresy a vyberte podsložku. Příručky se pak ukládají odděleně od všeho ostatního, aniž byste na to při ukládání museli myslet.
5. Na stránce dokumentace stiskněte Alt+Shift+M. Pokud potřebujete jen jednu funkci místo celé referenční stránky, označte ten úsek předem; přepínač v horní části okna ukazuje, jestli před sebou máte výběr, nebo celou stránku.
6. V okně projděte ohrazení. Stojí-li za zpětnými apostrofy python, js nebo bash, stránka jazyk označila; nestojí-li tam nic, neoznačila ho a doplníte ho jednou ručně, ještě než se soubor zapíše.

Hotové nastavení pro dokumentaci

Tyhle hodnoty jsou stavěné na dohledávání, ne na archivaci: u referenčních stránek datum skoro nic neříká, zato původ říká hodně. Kdo sype blogové zápisky a referenci do jedné složky, hledá potom dvakrát.

Výjimku vyvoláte příkazem `raise`:

```
raise NameError("Ahoj")
```

```python
try:
    raise NameError("Ahoj")
except NameError:
    print("Proletělo to")
```

Tři cesty jedním dnem

Posoudit neznámou knihovnu

Zvažujete, jestli knihovna zapadne do projektu, a čtete kvůli tomu úvodní stránku, konfiguraci a stránku o omezeních. Tři stránky, třikrát Alt+Shift+M, tři soubory v podsložce Reference – se šablonou {domain}-{title} v názvu, takže se všechny tři seřadí vedle sebe.

Večer leží rozhodnutí v editoru místo v patnácti otevřených panelech. Ukázky kódu mají značku jazyka, tabulka voleb má své řádky a adresa zdroje v každém frontmatteru říká, kterou verzi dokumentace jste četli – číslo verze bývá v cestě adresy, a tou se do poznámky dostane.

Zachytit řešení, které přišlo z fóra

Řešení otravného problému nestojí v oficiální dokumentaci, ale v příspěvku se čtyřiceti odpověďmi. Označíte tu jedinou odpověď, která funguje, a uložíte výběr: do souboru jde blok kódu i se značkou jazyka, ne celé vlákno a ne postranní seznam podobných dotazů.

Protože pravidlo pro tenhle web míří do jiné podsložky než reference, je při pozdějším dohledávání hned vidět, že řešení pochází od cizího člověka, ne od autorů knihovny. Přesně ten rozdíl musíte umět obhájit v code review.

Přenést ukázku do README

Do README má přijít příklad z oficiální reference. Kliknutí na ikonu přepnete pro tenhle jeden případ na schránku, uložíte výběr s příkladem a vložíte ho rovnou do souboru, aniž by se ukládala poznámka.

Vložené ohrazení dorazí jako ```js a GitHub ho obarví okamžitě. Adresu zdroje si vezmete z frontmatteru výstřižku, pokud pod ukázku chcete dát odkaz na referenci – řádek stojí v okně nad textem.

Proti obvyklým způsobům

Ostatní cesty nejsou špatné, jen řeší jinou úlohu – a u kódu neřeší zrovna tu část, na které záleží. Poslední řádek říká i to, co stojí tahle cesta.

Když se něco pokazí

Proč za zpětnými apostrofy žádný jazyk nestojí?

Protože ho neuvádí sama stránka. Clean Clipper čte třídu, kterou u ohrazení nechal zvýrazňovač daného webu, a z kódu nehádá – na technickém korpusu takovou třídu neslo 73 ohrazení ze 156. U zbytku ohrazení zůstane holé a je to správná odpověď: vymyšlená značka přepne zvýraznění na nesprávný jazyk a je horší než žádná.

Proč rozšíření na úvodní stránce dokumentace hlásí „žádný článek“?

Protože tam žádný není. Rozcestník se skládá skoro jen z popisků odkazů a rozšíření měří hotový Markdown: sedí-li v odkazech víc než čtvrtina textu, výstřižek odmítne. Sestupte o úroveň níž na stránku se skutečným textem a projde to.

Dokumentace se dokresluje JavaScriptem – proč chybí půlka obsahu?

Ukládá se DOM v tom stavu, v jakém je ve chvíli kliknutí. Jednostránková dokumentace se proto uloží správně, ale záložky a rozbalovací bloky, které jsou zavřené, v DOM často vůbec neexistují. Rozbalte oddíl a přepněte na tu záložku, kterou potřebujete, teprve pak ukládejte.

Uložil jsem stránku podruhé – přepsal jsem si původní poznámku?

Ne. Při shodě jmen se hledá volné jméno s pomlčkou a číslem: vedle Filter.md vznikne Filter-2.md a starší soubor zůstane nedotčený. Pro srovnání dvou verzí reference je to výhodné, obě znění pak leží vedle sebe a postavíte je proti sobě nástrojem na diff ve svém editoru.

Co nedělá

Neprochází celý dokumentační web – ukládáte stránku, na které stojíte, jednu po druhé; žádný crawler tu není. Nestahuje obrázky ani jiné binární přílohy, takže diagramy zůstanou odkazy na původní web. Kód nespouští, nepřepisuje ani nepřeformátovává. A na stránkách, které prohlížeč chrání, jako chrome:// nebo samotný obchod s rozšířeními, neběží vůbec.

Otázky