Jdi na navigaci

AsciiDoc

AsciiDoc je v současné době jazyk s nejširší podporou v rámci Courses. Mimo rozsáhlé možnosti formátování umožňuje například použití proměnných, bloků podmíněného překladu apod. Tato stránka obsahuje výčet základních a nejčastěji používaných elementů. Kompletní syntaxe je k naleznutí v oficiální dokumentaci.

Soubory AsciiDoc ukládejte s příponou .adoc. Název stránky v navigaci je určen pomocí elementu titulek (viz bod 1 sekce Metadata a atributy).

Metadata a atributy

Každé stránce lze zadefinovat různé proměnné (atributy), kterými můžete ovlivnit např. titulek stránky, vzhled atp.

Ukazková stránka může výpadat následovně:

= Anotace 1
:toc: 2
:imagesdir: ./media/ 3
:garant-predmetu: doc. Kevin Flynn 4

Předmět se zabývá základními principy života.
Garantem předmětu je {garant-predmetu}. 5
  1. Název stránky. Každá stránky musí mít právě jeden název. Pod tímto názvem je zároveň zobrazena v navigaci.
  2. Zapnutí zobrazení Obsahu (lze vypnout neuvedením tohoto řádku).
  3. Cesta k adresáři s obrázky (není nutné využívat). Více viz Obrázky.
  4. Definice vlastní proměnné.
  5. Použití proměnné v textu.

Více viz oficiální dokumentace.

Nadpisy

Nadpisy jsou nedílnou součástí stránky. Mimo jiné slouží k automatickému generování obsahu, viz Metadata a atributy.

Název formátováníZadaný textVýsledný text
Nadpis 1. úrovně== Nadpis 1. úrovně-
Nadpis 2. úrovně=== Nadpis 2. úrovně-
Nadpis 3. úrovně==== Nadpis 3. úrovně-
Nadpis 4. úrovně===== Nadpis 4. úrovně-

Nadpisům lze přiřazovat libovolné ID. To se následně projeví v URL, při kliknutí na nadpis. Zároveň se na něj lze pohodlně odkazovat, viz příklad.

Příklad použití ID nadpisu

Vytvořím nadpis s vlastním ID video.

[#video]
== Záznamy přednášek

Na této stránce naleznete seznam záznamů přednášek.

Později na stránce se na takto označenou sekci mohu pohodlně odkázat. Více viz Odkazy.

Všechny přednášky v rámci toho předmětu jsou <<video, nahrávány>>.

Více viz oficiální dokumentace.

Formátování textu

Název formátováníZadaný textVýsledný text
Tučné*text*text
Kurzíva_text_text
Neproporcionální`text`text
Uvozovky"`takto`"„takto“
Pomlčka-- – 

Část slova, nikoli celé slovo (viz následující příklad) lze formátovat s pomocí tzv. Unconstrained formatting pair.

Pro zvýraznění pouze části slova je potřeba využít dvě hvezdičky, namísto jedné.

Více viz oficiální dokumentace.

Název formátováníZadaný textVýsledný text
Odkazhttps://www.cvut.cz/https://www.cvut.cz
Odkaz s vlastním textemhttps://www.cvut.cz/[This Link points to CVUT]This Link points to CVUT
Interní odkazxref:pagename.adoc#[]Pozn. Zobrazený text bude název stránky.
Interní odkaz na nadpisxref:asciidoc.adoc#links[]Odkazy
E-mailmailto:helpdesk@fit.cvut.cz[]helpdesk@fit.cvut.cz
Odkaz v rámci dokumentu<<links, Sekce s odkazy>>Sekce s odkazy

Uvnitř hranatých závorek na konci odkazu je možné specifikovat vlastní text, pod kterým bude odkaz zobrazen.

Více viz oficiální dokumentace.

Obrázky

Obrázky ukládejte do složky k tomu určené[1], v opačném případě by došlo k automatickému přidání obrázku jako samostatné stránky do postranní navigace.

Volitné[2] – V záhlaví stránky určete složku ve které má AsciiDoc hledat obrázky. Provedete tak pomocí :imagesdir: <relativní cesta ke složce>. Viz třetí bod sekce Metadata a atributy.

Příklady vložení obrázku:

Název příkladuZadaný text
Obyčejný obrázek
image::obrazek.jpg[Alternativní text]
Obrázek s titulkem
.Toto je titulek, který bude zobrazen společně s obrázkem
image::obrazek.jpg[Alternativní text]
Obrázek se zarovnáním
image::obrazek.jpg[Alternativní text, align=left]

Mezi další atributy, kterými lze vykreslení obrázků modifikovat patří:

  • Šířka width=<velikost>
  • Odkaz link=<odkaz>
  • a další

Více viz oficiální dokumentace.

Soubory

  1. Soubor přidejte do složky k tomu určené[1].
  2. Na požadované stránce uveďte odkaz na soubor ve tvaru link:<relativní cesta k souboru>[].

Zobrazení v navigaci

Soubory lze zobrazit přímo v navigaci. Stačí jej umístit v libovolné složce[4] a Generátor Course Pages jej zařadí do navigace.

Seznamy

Pro vynucené oddělení sousedících seznamů využijte //-.

Název seznamuZadaný textVýsledný text
Nečíslovaný
* Toto je nečíslovaný seznam
* Toto je jeho druhá položka
** Jiná úroveň seznamu
* Další položka
  • Toto je nečíslovaný seznam
  • Toto je jeho druhá položka
    • Jiná úroveň seznamu
  • Další položka
Číslovaný
. Toto je číslovaný seznam
. Toto je jeho druhá položka
.. Jiná úroveň seznamu
. Další položka
  1. Toto je číslovaný seznam
  2. Toto je jeho druhá položka
    1. Jiná úroveň seznamu
  3. Další položka
Vlastní číslování a změna pořadí[5]
[loweralpha, start=5]
. Toto je číslovaný seznam
. Je číslovaný malými písmeny
** Druhá úroveň seznamu
** Je nečíslovaná
. Další položka
  1. Toto je číslovaný seznam
  2. Je číslovaný malými písmeny
    • Druhá úroveň seznamu
    • Je nečíslovaná
  3. Další položka
Víceřádkové položky
* Toto je položka.
+
S více řádky.

* Toto je jeho druhá položka
  • Toto je položka.

    S více řádky.

  • Toto je jeho druhá položka

Více viz oficiální dokumentace.

Bloky

Důležité:

Toto je blok obsahující důležitou informaci. Název bloku je IMPORTANT.

Varování:

Toto je blok obsahující důrazné varování. Název bloku je WARNING.

Následuje ukázka jednořádkového bloku. Místo NOTE lze dosadit libovolný typ bloku, viz názvy výše.

NOTE: Toto je blok obsahující poznámku. Název bloku je `NOTE`.

Bloky mohou být také víceřádkové, místo IMPORTANT lze dosadit libovolný typ bloku, viz názvy výše.

[IMPORTANT]
====
Toto je blok obsahující důležitou informaci.

- název bloku je `IMPORTANT`
- je víceřádkový
- a může obsahovat i složitější struktury (jako např. tento seznam)
====

Více viz oficiální dokumentace.

Poznámky pod čarou

Poznámku pod čarou lze zapsat pomocí footnote:[Text poznámky pod čarou.] na požadované místo do textu. O číslování se AsciiDoc postará sám.

Výsledek bude vypadat následovně.[6]

Znovuvyužití poznámky

Na konkrétní poznámku pod čarou se lze vícekrát odkázat. Vytvořte poznámku pomocí footnote:<id poznamky>[<text poznamky>]. Na existující poznámku se můžete odkázat pomocí footnote:<id poznamky>[]. <id poznamky> nahraďte libovolným identifikátorem poznámky.

Více viz oficiální dokumentace.

Kód

Kód lze psát jednořádkový – například `text` bude vykresleno jako text.

Víceřádkový kód viz následující příklad:

[source,c]
----
airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));

long int j = 0;
for (long int i = 0; i < n; i++)
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;
----

Bude vykresleno jako:

airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));

long int j = 0;
for (long int i = 0; i < n; i++)
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;

Řádek [source,<jazyk>] se stará o zvýraznění syntaxe. Za <jazyk> lze dosadit libovolný jazyk. Vynecháním tohoto řádku nebude u kódu zvýrazněna syntaxe.

Více viz oficiální dokumentace.

Kód s vysvětlivkami

Do kódu lze vkládat vysvětlivky. Lze tak přehledně komentovat práci bez nutnosti využívat komentáře.

Jednotlivé vysvětlivky jsou kombinací dvou prvků:

  • značka – // <1>, typ značky lze volit v závislosti na jazyce ukázky.[7]
  • komentář – <1> Deklarace proměnných
[source,c]
----
airplane_t *strip = NULL; // <1>
strip = (airplane_t *) malloc(n * sizeof(*strip)); // <1>

long int j = 0;
for (long int i = 0; i < n; i) // <2>
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j;
----

<1> Deklarace proměnných.
<2> Cyklus, který proběhne právě n-krát.

Bude vykresleno jako:

airplane_t *strip = NULL; 1
strip = (airplane_t *) malloc(n * sizeof(*strip)); 1

long int j = 0;
for (long int i = 0; i < n; i++) 2
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;
  1. Deklarace proměnných.
  2. Cyklus, který proběhne právě n-krát.

Více viz oficiální dokumentace.

Přepínací lišta

Pomocí následujícího kódu lze vytvořit přepínací lištu.

[tabbed] 1
Arch Linux:: 2
+
První řádek záložky Arch Linux.
+
Druhý řádek.
3
Debian / Ubuntu::
+
První řádek záložky Debian / Ubuntu.
+
Druhý řádek.

Fedora::
+
První řádek záložky Fedora, která navíc obsahuje zdrojový kód:
+
[source, c]
----
airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));
----

openSUSE::
+
První řádek záložky openSUSE.
+
Druhý řádek.
  1. Blok s přepínací lištou musí být označen [tabbed].
  2. Název lišty může být libovolný, avšak musí být ukončen ::, např Arch Linux::.
  3. Jednotlivé lišty jsou odděleny prázdným řádkem.

Bude vykresleno jako:

Arch Linux

První řádek záložky Arch Linux.

Druhý řádek.

Debian / Ubuntu

První řádek záložky Debian / Ubuntu.

Druhý řádek.

Fedora

První řádek záložky Fedora, která navíc obsahuje zdrojový kód:

airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));
openSUSE

První řádek záložky openSUSE.

Druhý řádek.

Skrývatelné bloky

Pomocí následujícího kódu lze vytvořit skrývatelné bloky.

[%collapsible]
.Řešení 1. domacího úkolu
====
Zde je řešení domací úlohy.
====

Bude vykresleno jako:

Řešení 1. domacího úkolu

Zde je řešení domací úlohy.

Komentáře

Komentáře nejsou součástí výsledné podoby stránky.

// Jednořádkový komentář

Lze psát také víceřádkové.

////
Komentář, který má

více řádek.
////

Více viz oficiální dokumentace.

Tabulky

AsciiDoc poskytuje komplexní podporu pro tvorbu tabulek, včetně možnosti slučování buněk, různého zarovnání nebo načtení dat z CSV souboru.[8]

Příklad jednoduché tabulky bez formátování:

Zdrojový kód
[%header, cols="1,1,2"] 1
|=== 2
|Jméno
|Heslo
|Popis

|user 3
|1234
|Normální uživatel

|root
|root
|Superuser
|=== 2
  1. Nepovinné: Seznam atributů. Atribut %header" určí první řádek záhlavím tabulky. cols="1,1,2" specifikuje tři sloupce, kde třetí je dvojnásobné délky.
  2. Povinné: Tabulka musí být ohraničena řetězcem znaků |===.
  3. Jednotlivé řádky tabulky jsou ve zdrojovém kódu odděleny prázdným řádkem.
Výsledek
JménoHesloPopis
user1234Normální uživatel
rootrootSuperuser

U tabulek lze modifikovat:

  • Formátování a zarovnání sloupců[9]
  • Slučování, formátování nebo zarovnávání buněk[10]
  • Šířku a zarovnání celé tabulky[11]
  • atd.

Více viz oficiální dokumentace.

Pokročilé formátování

Zdrojový kód
.Hodnocení předmětu 1
[%header] 2
[cols="^1s, 2, 2"] 3
[width=50%] 4
[align=left] 5
|====
|Známka
|Bodové rozmezí
|Slovní hodnocení

|A
|90 a více
|výborně

|B
|80-89
|velmi dobře

|C
|70-79
|dobře

|D
|60-69
|uspokojivě

|E
|50-59
|dostatečně

|F
|méně než 50
|nedostatečně
|====
  1. Nepovinné: Název tabulky.
  2. %header první řádek tabulky bude označen jako záhlaví.
  3. cols="^1s, 2, 2" první sloupec tabulky bude zarovnán na střed (^) a bude zvýrazněn tučně (s), zbylé sloupce budou dvojnásobné délky.
  4. width=50% šířka tabulky bude 50% šířky stránky.
  5. align=left tabulka bude jako celek zarovnána vlevo.
Výsledek
Tabulka 1. Hodnocení předmětu
ZnámkaBodové rozmezíSlovní hodnocení
A90 a vícevýborně
B80-89velmi dobře
C70-79dobře
D60-69uspokojivě
E50-59dostatečně
Fméně než 50nedostatečně

Data ze souboru

Příklad alternativního zdroje dat:

Zdrojový kód
[%header, format=csv, separator=;, cols="1,1,2"]
|===
include::tracks.csv[]
|===
tracks.csv
Cvičení;Datum;Obsah cvičení
1;23. 9. 2020;Základní pojmy
2;30. 9. 2020;Chomského hierarchie
Výsledek
CvičeníDatumObsah cvičení
123. 9. 2020Základní pojmy
230. 9. 2020Chomského hierarchie

Matematické výrazy

Abychom na stránce mohli používat matematické výrazy a formule zadávané pomocí La/TeX syntaxe, musíme správně nastavit stem atribut dokumentu na hodnotu latexmath. Toho snadno docílíme následovně:

= Stránka s matematickými výrazy 1
:stem: latexmath 2
  1. Název dokumentu/stránky.
  2. Nastavení atributu stem na hodnotu latexmath.

Courses k finální sazbě matematických výrazů používají KaTeX. Jedná se o nástroj umožňující zobrazovat matematické výrazy zadané pomocí matematické La/TeX syntaxe na webu. Původně byl tento nástroj vytvořen pro Khan Academy. KaTeX nepodporuje úplně všechny matematické možnosti a balíčky známé z La/TeXu, resp. AMSTexu, ale jeho možnosti budou pro většinu uživatelů a problémů naprosto dostatečné. Přesný seznam podporovaných maker a prostředí je uveden v dokumentaci KaTeXu.

Rovnice v textu

K vytvoření matematických výrazů vyskytujících se přímo v textu (inline math) lze použít makro stem. Třeba bychom chtěli diskutovat vlastnosti funkce f(x)=sin(x)f(x) = \sin(x) nebo se bavit o posloupnosti (n+1)n=1(n+1)_{n=1}^\infty. Zdrojový kód takovéto věty s matematickými výrazy vypadá takto:

Třeba bychom chtěli diskutovat vlastnosti funkce stem:[f(x) = \sin(x)]
nebo se bavit o posloupnosti stem:[(n+1)_{n=1}^\infty].

Makro stem je tedy prakticky ekvivalentní LaTeX matematickému módu ohraničenému dvěma symboly $. Musíme si zde ovšem dát pozor na uzavírací hranatou závorku označující nepovinné parametry některých LaTeX maker, například třetí odmocninu ze dvou, 23\sqrt[3]{2}, správně zadáme pomocí

stem:[\sqrt[3\]{3}] 1
  1. Všimněte si \] místo ].

Samostatné rovnice

K vysázení větší rovnice, která vyžaduje osamostatnění na vlastním řádku, použijeme blok ohraničený čtyřmi + symboly (obsah tohoto bloku se nijak nemodifikuje a posílá se rovnou KaTeXu; passthrough block) se stylem stem. Například rovnici

k=1k=112,\sum_{k=1}^\infty k = -\frac{1}{12}\,,

jsme vytvořili pomocí kódu

[stem] 1
++++ 2
  \sum_{k=1}^\infty k = -\frac{1}{12}\,, 3
++++ 4
  1. stem styl.
  2. Začátek bloku.
  3. Obsah bloku s matematickou LaTeX notací.
  4. Konec bloku.

Takovýto blok tedy odpovídá standardnímu nečíslovanému LaTeX prostředí equation*, resp, LaTeX matematickému módu ohraničenému \[ a \].

Často ovšem potřebujeme vysázet více rovnic najednou a chceme je pěkně zarovnat. K tomu můžeme použít prostředí aligned. Následující soustavu dvou rovnic o dvou proměnných

2x+3y=4,5x+6y=7.\begin{aligned} 2x + 3y &= 4, \\ 5x + 6y &= 7. \end{aligned}

jsme vytvořili pomocí kódu

[stem]
++++
\begin{aligned} 1
  2x + 3y &= 4, \\ 2
  5x + 6y &= 7.
\end{aligned}
++++
  1. Využití aligned makra k zarovnání více rovnic.
  2. K zarovnání rovnic používáme symbol & a k oddělení rovnic \\.

V KaTeXu je vedle makra aligned k dispozici ještě jedno marko známé z AMSTexu, gathered, které umožňuje sazbu víceřádkových vycentrovaných rovnic bez zarovnání, např.

(x+y)n=k=0n(nk)xnkyk==(n0)xn+(n1)xn1y+(n2)xn2y2++(nn1)xyn1+(nn)yn.\begin{gathered} (x + y)^n = \sum_{k=0}^n \dbinom{n}{k} x^{n-k} y^k = \\ = \dbinom{n}{0} x^n + \dbinom{n}{1} x^{n-1} y + \dbinom{n}{2} x^{n-2} y^2 + \cdots + \dbinom{n}{n-1} x y^{n-1} + \dbinom{n}{n} y^n\,. \end{gathered}

Tuto rovnici jsme vytvořili pomocí tohoto kódu:

[source,latex]
[stem]
++++
\begin{gathered} 1
  (x + y)^n = \sum_{k=0}^n \dbinom{n}{k} x^{n-k} y^k = \\ 2
  = \dbinom{n}{0} x^n + \dbinom{n}{1} x^{n-1} y + \dbinom{n}{2} x^{n-2} y^2
  + \cdots + \dbinom{n}{n-1} x y^{n-1} + \dbinom{n}{n} y^n\,.
\end{gathered}
++++
  1. Využití gathered makra k vycentrování víceřádkové rovnice.
  2. K zalomení rovnice využíváme \\.

Další matematické tipy a triky

Odkazy na rovnice

V matematickém textu bývá zvykem se odkazovat na některé (očíslované) rovnice. KaTeX/AsciiDoc/Course Pages však přímo nepodporují ekvivalent LaTeX maker label a eqref, resp. ref. Můžeme si ale celkem snadno pomoci, protože KaTeX podporuje tag makro. Příslušný blok, obsahující rovnici na kterou se chceme odkazovat, označíme pomocí id, rovnici přidáme tag a v odkazu na ní použijeme AsciiDoc makro xref. Například následující rovnici

(1)abf(x)dx=[F(x)]ab.\tag{1} \int_{a}^{b} f(x)\,\mathrm{d}x = \big[ F(x) \big]_{a}^{b}\,.

jsme vysázeli pomocí kódu

[[eq1]]
[stem]
++++
  \tag{1}
  \int_{a}^{b} f(x)\,\mathrm{d}x = \big[ F(x) \big]_{a}^{b}\,.
++++

V rovnici (1) (odkaz vytvořen pomocí xref:#eq1[(1)]) pozorný čtenář jistě rozpoznává Newtonovu formuli.

Zvýraznění částí rovnic

K upozornění čtenáře na důležité části rovnice můžeme využít svorky (makro underbrace) nebo i barvy (makro color), např. v rovnici

(abcd)1=1adbc(dbca).\underbrace{ \begin{pmatrix} a & b \\ c & d \end{pmatrix}^{-1} }_{\triangle} = \frac{1}{\color{red}ad-bc} \begin{pmatrix} d & -b \\ -c & a \end{pmatrix}.

jsme matici na levé straně označili trojúhelníčkem (\triangle) a výraz ve jmenovateli na pravé straně červenou barvou. Použitý kód je následující:

[stem]
++++
  \underbrace{ 1
  \begin{pmatrix}
    a & b \\
    c & d
  \end{pmatrix}^{-1}
  }_{\triangle}
  =
  \frac{1}{\color{red}ad-bc} \begin{pmatrix} 2
    d  & -b \\
    -c & a
  \end{pmatrix}.
++++
  1. Makro underbrace.
  2. Makro color.

Definice, věty a důkazy

Ve formálnějších matematických textech bývá zvykem typograficky oddělovat důležité části jako Definice, Věty, atp. V LaTeXu k tomuto účelu existuje známý balíček amsthm.

V AsciiDocu/Courses můžeme k takovémuto typografickém oddělení použít například pojmenovaný blok určený pro citaci. Následuje jedna konkrétní ukázka tohoto přístupu.

Základní věta algebry

Každý polynom stupně nNn \in \mathbb{N} má nejvýše nn komplexních kořenů.

Kód, kterým jsme toto zvýraznění vytvořili je následující:

.Základní věta algebry 1
[[Veta1]] 2
____ 3
Každý polynom stupně stem:[n \in \mathbb{N}] má nejvýše stem:[n] komplexních kořenů.
____
  1. Titulek.
  2. id, pomocí kterého se můžeme na větu v textu odkazovat.
  3. Blok ohraničený čtyřmi podtržítky.

K slavnostnímu označení konce důkazu se v matematické literatuře většinou používá Halmosův náhrobek \square, či čtvereček. Ten můžeme vytvořit pomocí KaTeXu kódem stem:[\square]. Alternativně lze samozřejmě použít obyčejnou textovou zkratku Q.E.D.


  1. Standardně se jedná o složky media nebo files, avšak název se může lišit v závislosti na konfiguraci daného projektu.
  2. V případě, že neuvedete atribut :imagesdir:, bude potřeba ke každému obrázku uvádět jeho úplnou cestu.
  3. Microsoft OneDrive mimo jíné disponuje rozšířenými metodami pro správu přístupu a udělování práv.
  4. Mimo cesty, které jsou nastavením skryté – nastavení hiddenFiles a excludedFiles v konfiguračním souboru. Typicky složky media nebo files
  5. Alternativně lze číslovat v opačném pořadí, a to s pomocí příznaku %reversed
  6. Text poznámky pod čarou.
  7. Místo // <1> lze využít např. # <1>, ;; <1>, <!--1-->. Tak aby značka byla validním komentářem v daném jazyce.
  8. Více k formátu dat viz oficiální dokumentace.
  9. Více k formátování sloupců viz oficiální dokumentace.
  10. Více k formátování buněk viz oficiální dokumentace.
  11. Více k šířce tabulky viz oficiální dokumentace.