docs: add emacs-extensions.org — detailed guide for new packages

2026-02-24 18:04:08 +01:00
parent 57e9b56a5f
commit 037fda7d80
1 changed files with 471 additions and 0 deletions
--- a/notes/emacs-extensions.org
+++ b/notes/emacs-extensions.org
@@ -0,0 +1,471 @@
 #+TITLE: Emacs Extensions — Instalace a Workflow
 #+DATE: [2026-02-24 Tue]
 #+OPTIONS: toc:3
 * Přehled keybindings
 | Klávesa     | Příkaz                   | Popis                          |
 |-------------+--------------------------+--------------------------------|
 | =SPC o c=   | org-caldav-sync          | Sync kalendáře s CalDAV        |
 | =SPC o k=   | kubel                    | Kubernetes management          |
 | =SPC o C=   | cfw:open-org-calendar    | Vizuální kalendář              |
 | =SPC u=     | vundo                    | Vizuální undo tree             |
 | =SPC s e=   | iedit-mode               | Editace všech výskytů          |
 | =SPC s q=   | org-ql-search            | Org-ql dotaz                   |
 | =SPC s Q=   | org-ql-view              | Org-ql uložené pohledy         |
 | =SPC n r u= | org-roam-ui-mode         | Org-roam graf v prohlížeči     |
 | =SPC b b=   | citar-open               | Otevřít referenci              |
 | =SPC b i=   | citar-insert-citation    | Vložit citaci                  |
 | =SPC b n=   | citar-open-notes         | Poznámky k článku              |
 | =SPC b r=   | citar-refresh            | Obnovit bibliografii           |
 | =SPC t g=   | langtool-check           | Kontrola gramatiky             |
 | =SPC t G=   | langtool-check-done      | Zrušit zvýraznění gramatiky    |
 | =, C i=     | org-clock-in             | Začít měřit čas (org)          |
 | =, C o=     | org-clock-out            | Ukončit měření                 |
 | =, C r=     | org-clock-report         | Výpis odpracovaného času       |
 | =, A s=     | org-anki-sync-entry      | Sync heading do Anki           |
 | =, A S=     | org-anki-sync-all        | Sync vše do Anki               |
 | =C-M-n/p=   | combobulate-navigate     | Navigace po AST uzlech         |
 | =C-M-u/d=   | combobulate-navigate     | Nahoru/dolů v AST              |
 * Tier 1 — Vysoký dopad
 ** org-caldav — Sync s CalDAV
 Obousměrná synchronizace org souborů s CalDAV serverem. Události z org se promítnou do kalendáře a naopak.
 *** Instalace
 Balíček je v =packages.el=, konfigurace v =config.el=. Server: =cal.apps.sukany.cz=, uživatel =martin@sukany.cz=. Heslo v =~/.openclaw/.env= (=$CALDAV_PASSWORD=).
 *** Keybindings
 | Klávesa   | Příkaz            | Popis              |
 |-----------+-------------------+--------------------|
 | =SPC o c= | org-caldav-sync   | Spustit sync       |
 *** Příklad workflow
 1. Otevři =~/org/personal.org=, přidej heading s datem: =* Schůzka <2026-03-01 Sun 14:00-15:00>=
 2. =SPC o c= — sync s CalDAV
 3. Událost se objeví v kalendáři na =cal.apps.sukany.cz=
 4. Změny z kalendáře se stáhnou do =~/org/caldav-inbox.org=
 *** Tipy
 - Sync směr je =twoway= — funguje oběma směry
 - =caldav-inbox.org= slouží jako přijímací soubor pro nové události ze serveru
 - Před prvním syncnem vytvoř =~/org/caldav-inbox.org= (prázdný soubor stačí)
 ** envrc — Per-project prostředí
 Automaticky načítá =.envrc= soubory přes direnv při vstupu do projektového adresáře. Proměnné prostředí se nastaví per-buffer.
 *** Instalace
 #+begin_src shell
 # direnv musí být nainstalovaný
 brew install direnv  # macOS
 sudo apt install direnv  # Debian/Ubuntu
 #+end_src
 Balíček se aktivuje globálně po startu Emacsu.
 *** Příklad workflow
 1. V kořeni projektu vytvoř =.envrc=: =export DATABASE_URL=postgres://...=
 2. =direnv allow= v shellu
 3. Otevři soubor z projektu v Emacsu — envrc automaticky nastaví proměnné
 4. =M-x envrc-show= ukáže aktuální prostředí bufferu
 *** Tipy
 - Funguje per-buffer, ne globálně — různé projekty mají různé proměnné
 - Kombinuj s =.env= soubory přes =dotenv= layout v =.envrc=
 ** embark — Kontextové akce
 Doom vertico modul embark zahrnuje. Embark nabízí kontextové akce nad aktuálním cílem (soubor, symbol, URL) v minibufferu nebo v bufferu.
 *** Keybindings
 Doom výchozí: =C-.= v minibufferu nebo bufferu spustí embark-act. Prompter nastaven na =embark-keymap-prompter= — zobrazí klávesovou mapu dostupných akcí.
 *** Příklad workflow
 1. =SPC f f= (find file) — začni psát název souboru
 2. =C-.= na kandidátovi — embark ukáže akce: otevřít, smazat, kopírovat cestu, grep...
 3. Vyber akci klávesou (např. =d= pro delete, =c= pro copy)
 *** Tipy
 - =C-;= = embark-dwim (provede nejpravděpodobnější akci rovnou)
 - Funguje i mimo minibuffer — na symbolu v kódu nabídne dokumentaci, definici
 ** wgrep — Editovatelný grep
 Umožňuje editovat výsledky grepu přímo v grep bufferu a uložit změny do všech souborů najednou.
 *** Příklad workflow
 1. =SPC s p= (project search) — hledej =old_function=
 2. V grep bufferu: =C-c C-p= (wgrep-change-to-wgrep-mode)
 3. Použij =:%s/old_function/new_function/g= (evil substitute)
 4. =C-c C-c= — uloží změny do všech souborů
 5. =C-c C-k= — zruší změny
 *** Tipy
 - =wgrep-auto-save-buffer= je zapnutý — soubory se uloží automaticky po =C-c C-c=
 - Kombinuj s =SPC s p= (ripgrep) pro refactoring přes celý projekt
 ** kubel — Kubernetes management
 Interaktivní rozhraní pro správu Kubernetes zdrojů přímo z Emacsu. Cluster: =infra01.sukany.cz=, přístup přes kubeconfig.
 *** Keybindings
 | Klávesa   | Příkaz                        | Popis                  |
 |-----------+-------------------------------+------------------------|
 | =SPC o k= | kubel                         | Otevřít kubel          |
 | =g=       | kubel-get-resource-details    | Detail zdroje          |
 | =E=       | kubel-exec-pod                | Exec do podu           |
 | =l=       | kubel-get-pod-logs            | Logy podu              |
 | =d=       | kubel-describe-resource       | Describe                |
 | =D=       | kubel-delete-resource         | Smazat zdroj           |
 *** Příklad workflow
 1. =SPC o k= — otevře kubel s aktuálním kontextem
 2. Vyber namespace (kubel zobrazí seznam)
 3. =l= na podu — zobrazí logy
 4. =E= na podu — otevře shell v podu přes vterm
 *** Tipy
 - Kubeconfig musí být správně nastaven (=~/.kube/config= nebo =$KUBECONFIG=)
 - Pro přepínání kontextů použij =kubel-set-context=
 * Tier 2 — Kvalita života
 ** org-clock — Sledování času
 Vestavěná funkce org-mode pro sledování času stráveného na úkolech. Konfigurace přidává persistenci a přehledný reporting.
 *** Keybindings
 | Klávesa | Příkaz            | Popis                    |
 |---------+-------------------+--------------------------|
 | =, C i= | org-clock-in      | Začít měřit              |
 | =, C o= | org-clock-out     | Ukončit                  |
 | =, C r= | org-clock-report  | Tabulka odpracovaného    |
 | =, C d= | org-clock-display | Zobrazit časy v bufferu  |
 *** Příklad workflow
 1. Na org heading: =, C i= — začne měření
 2. Pracuj na úkolu
 3. =, C o= — ukončí měření, zapíše LOGBOOK
 4. =, C r= — vloží clocktable s přehledem časů
 *** Tipy
 - =org-clock-persist= ukládá stav přes restart Emacsu
 - Formát =h:mm= — hodiny a minuty, ne dny
 - Nulové záznamy se automaticky mažou
 ** combobulate — Strukturální editace
 Tree-sitter navigace a editace po syntaktických uzlech. Funguje v Pythonu, Go, JS, TypeScriptu.
 *** Keybindings
 | Klávesa | Příkaz                         | Popis                    |
 |---------+--------------------------------+--------------------------|
 | =C-M-n= | combobulate-navigate-next      | Další sourozenec         |
 | =C-M-p= | combobulate-navigate-previous  | Předchozí sourozenec     |
 | =C-M-u= | combobulate-navigate-up        | Rodičovský uzel          |
 | =C-M-d= | combobulate-navigate-down      | Potomek                  |
 *** Příklad workflow
 1. Otevři Python soubor s funkcemi
 2. Kurzor na =def= — =C-M-n= přeskočí na další funkci
 3. =C-M-u= — přejde na třídu obsahující funkci
 4. =C-M-d= — vstoupí do prvního potomka (první metoda)
 *** Tipy
 - Vyžaduje tree-sitter gramatiky pro daný jazyk
 - V Go funguje na =func=, =if=, =for= blocích
 ** iedit — Editace více výskytů
 Označí všechny výskyty slova pod kurzorem a umožní je editovat simultánně.
 *** Keybindings
 | Klávesa   | Příkaz      | Popis                      |
 |-----------+-------------+----------------------------|
 | =SPC s e= | iedit-mode  | Zapnout/vypnout iedit      |
 *** Příklad workflow
 1. Kurzor na proměnné =counter=
 2. =SPC s e= — všechny výskyty =counter= se zvýrazní
 3. Edituj — změna se projeví na všech místech najednou
 4. =SPC s e= znovu — ukončí iedit
 *** Tipy
 - Pro omezení rozsahu: nejdřív vyber region, pak =SPC s e=
 - Kombinuj s =C-;= (embark) pro komplexnější refactoring
 ** vundo — Vizuální undo
 Zobrazí undo historii jako strom s větvemi. Umožňuje navigovat mezi různými stavy souboru.
 *** Keybindings
 | Klávesa | Příkaz | Popis                    |
 |---------+--------+--------------------------|
 | =SPC u= | vundo  | Otevřít undo tree        |
 *** Příklad workflow
 1. Udělej několik změn v souboru (edituj, undo, edituj jinak)
 2. =SPC u= — zobrazí se strom s větvemi
 3. Šipkami naviguj mezi stavy, =RET= potvrdí vybraný stav
 4. =q= zavře vundo
 *** Tipy
 - Unicode symboly pro přehledný strom (=vundo-unicode-symbols=)
 - Doom =undo= modul zajišťuje undo-fu — vundo ho doplňuje vizuální navigací
 ** breadcrumb — Kontext v header-line
 Zobrazuje aktuální pozici v kódu (funkce, třída, metoda) v header-line bufferu.
 *** Příklad workflow
 Automaticky se aktivuje v =prog-mode= a =cperl-mode=. Při navigaci kódem vidíš v horní liště např. =MyClass > my_method > if block=.
 *** Tipy
 - Nepotřebuje LSP — pracuje s imenu
 - Užitečné při navigaci ve velkých souborech
 * Tier 3 — Doplňkové
 ** org-anki — Anki flashcards
 Exportuje org headings jako Anki kartičky. Heading = přední strana, obsah = zadní strana.
 *** Keybindings
 | Klávesa | Příkaz                | Popis                  |
 |---------+-----------------------+------------------------|
 | =, A s= | org-anki-sync-entry   | Sync aktuální heading  |
 | =, A S= | org-anki-sync-all     | Sync vše               |
 | =, A d= | org-anki-delete-entry | Smazat kartičku        |
 *** Příklad workflow
 1. V org souboru:
   #+begin_example
   * Co je CIDR notace?
   Způsob zápisu IP adres s prefixem sítě, např. 192.168.1.0/24.
   #+end_example
 2. =, A s= — sync do Anki decku "Emacs"
 3. Anki musí běžet s AnkiConnect pluginem
 *** Tipy
 - Výchozí deck: "Emacs" — změň v konfiguraci podle potřeby
 - Anki + AnkiConnect musí běžet lokálně (port 8765)
 ** org-ql — Query language pro org
 Vyhledávání v org souborech pomocí s-expression dotazů. Silnější než org-agenda filtry.
 *** Keybindings
 | Klávesa   | Příkaz         | Popis                    |
 |-----------+----------------+--------------------------|
 | =SPC s q= | org-ql-search  | Interaktivní dotaz       |
 | =SPC s Q= | org-ql-view    | Uložené pohledy          |
 *** Příklad workflow
 1. =SPC s q= — zadej dotaz:
   #+begin_example
   (and (todo "TODO") (tags "work") (deadline :to today))
   #+end_example
 2. Zobrazí se všechny pracovní TODO s deadline dnes
 3. Plain-text syntax funguje taky: =todo:TODO tags:work deadline:to=today=
 *** Tipy
 - Kombinuj s =org-ql-view= pro ukládání častých dotazů
 - Podporuje regulární výrazy v =regexp= predikátu
 ** calfw — Vizuální kalendář
 Zobrazuje org-agenda události v měsíčním kalendáři.
 *** Keybindings
 | Klávesa   | Příkaz                  | Popis              |
 |-----------+-------------------------+--------------------|
 | =SPC o C= | cfw:open-org-calendar   | Otevřít kalendář   |
 *** Příklad workflow
 1. =SPC o C= — otevře měsíční pohled
 2. Šipky pro navigaci mezi dny/týdny
 3. Události z org-agenda se zobrazí v buňkách
 *** Tipy
 - Po org-caldav sync zobrazí i události z CalDAV serveru
 - =M= přepne na měsíční, =W= na týdenní pohled
 ** org-roam-ui — Graf poznámek
 Webové rozhraní zobrazující graf propojení org-roam poznámek v prohlížeči.
 *** Keybindings
 | Klávesa     | Příkaz             | Popis                |
 |-------------+--------------------+----------------------|
 | =SPC n r u= | org-roam-ui-mode   | Spustit/zastavit UI  |
 *** Příklad workflow
 1. =SPC n r u= — spustí lokální server
 2. Otevře se prohlížeč s interaktivním grafem
 3. Kliknutí na uzel otevře poznámku v Emacsu
 4. Graf se aktualizuje při ukládání souborů
 *** Tipy
 - Synchronizuje téma s Emacsem (=org-roam-ui-sync-theme=)
 - Sleduje aktuální buffer (=org-roam-ui-follow=)
 ** dirvish — Moderní správce souborů
 Nahrazuje dired moderním rozhraním s náhledy, ikonami a git integrací.
 *** Keybindings
 | Klávesa | Příkaz                          | Popis                    |
 |---------+---------------------------------+--------------------------|
 | =h=     | dired-up-directory              | Nahoru                   |
 | =l=     | dired-find-file                 | Otevřít                  |
 | =s=     | dirvish-quicksort               | Řazení                   |
 | =TAB=   | dirvish-subtree-toggle          | Rozbalit/sbalit adresář  |
 | =q=     | dirvish-quit                    | Zavřít                   |
 | =M-f=   | dirvish-history-go-forward      | Historie vpřed           |
 | =M-b=   | dirvish-history-go-backward     | Historie zpět            |
 *** Příklad workflow
 1. =SPC .= (find file) nebo =SPC o -= (dired) — dirvish přebírá dired
 2. =TAB= na adresáři — rozbalí obsah inline (subtree)
 3. =h/l= navigace jako v rangeru
 4. Git status se zobrazuje ikonami vedle souborů
 *** Tipy
 - Atributy zahrnují nerd-icons, git-msg, file-time, file-size
 - Boční panel: 35 znaků šířka
 * BibTeX / Citar — Správa literatury
 Citar je součástí Doom biblio modulu. Slouží ke správě bibliografických referencí, citací a poznámek k článkům.
 ** Instalace a setup
 Citar je nainstalován automaticky (Doom biblio modul v =init.el=). Konfigurace:
 - Bibliografie: =~/org/references.bib=
 - Poznámky: =~/org/notes/=
 - PDF články: =~/org/papers/=
 Vytvoř tyto adresáře a =references.bib= soubor:
 #+begin_src shell
 mkdir -p ~/org/notes ~/org/papers
 touch ~/org/references.bib
 #+end_src
 ** Keybindings
 | Klávesa   | Příkaz                 | Popis                |
 |-----------+------------------------+----------------------|
 | =SPC b b= | citar-open             | Otevřít referenci    |
 | =SPC b i= | citar-insert-citation  | Vložit citaci        |
 | =SPC b n= | citar-open-notes       | Poznámky k článku    |
 | =SPC b r= | citar-refresh          | Obnovit bibliografii |
 ** Workflow: citace v org dokumentech
 1. Stáhni BibTeX záznam článku (z Google Scholar, DOI...)
 2. Vlož do =~/org/references.bib=
 3. V org dokumentu: =SPC b i= — vyber referenci z minibufferu
 4. Citar vloží citační klíč: =[cite:@author2024]=
 ** Workflow: poznámky k článkům
 1. =SPC b b= — otevře PDF článku z =~/org/papers/=
 2. =SPC b n= — otevře/vytvoří poznámkový soubor v =~/org/notes/=
 3. Kombinuj s org-noter pro anotace přímo v PDF
 *** Tipy
 - BibTeX soubory exportuj z Zotero nebo přímo z Google Scholar
 - =SPC b r= po přidání nových záznamů do =.bib= souboru
 * Grammar check (LanguageTool)
 LanguageTool kontroluje gramatiku a styl textu. Podporuje češtinu.
 ** Instalace
 #+begin_src shell
 # Stáhni LanguageTool
 mkdir -p ~/languagetool
 cd ~/languagetool
 wget https://languagetool.org/download/LanguageTool-stable.zip
 unzip LanguageTool-stable.zip
 # JAR musí být na ~/languagetool/languagetool-commandline.jar
 #+end_src
 ** Keybindings
 | Klávesa   | Příkaz               | Popis                    |
 |-----------+----------------------+--------------------------|
 | =SPC t g= | langtool-check       | Zkontrolovat buffer      |
 | =SPC t G= | langtool-check-done  | Zrušit zvýraznění        |
 ** Příklad workflow
 1. Napiš text v org nebo markdown
 2. =SPC t g= — LanguageTool zvýrazní chyby
 3. Kurzor na chybu — zobrazí návrh opravy
 4. =SPC t G= — vyčistí zvýraznění po opravách
 ** Tipy
 - Výchozí jazyk: čeština (=cs=)
 - Pro anglické texty: =M-x langtool-check= s argumentem "en"
 - Vyžaduje Javu (JRE)
 * Obecné tipy pro kombinaci nástrojů
 - *Refactoring:* =SPC s p= (ripgrep) → =C-c C-p= (wgrep) → edituj → =C-c C-c= uloží do všech souborů
 - *Org workflow:* org-caldav sync (=SPC o c=) → calfw zobrazení (=SPC o C=) → org-clock měření (=, C i=)
 - *Studium:* citar otevře článek (=SPC b b=) → org-noter anotace (=SPC o n=) → org-anki kartičky (=, A s=)
 - *Code navigation:* breadcrumb v header-line + combobulate (=C-M-n/p/u/d=) + iedit (=SPC s e=)
 - *Kubernetes:* kubel (=SPC o k=) + envrc pro per-project kubeconfig