Markdown: dokumenty v prostém textu s minimem námahy ==================================================== Obtěžují vás značky HTML při psaní textů určených k publikování na webu? Chcete texty šířit v čitelné podobě s minimálními nároky na softwarové vybavení jak vaše, tak čtenářů? Zkuste použivat některý minimalistický značkovací jazyk pro formátování prostého textu, např. Markdown. ##Úvod Před příchodem formátování e-mailových zpráv pomocí HTML se v písemné komunikaci použivaly kombinace symbolů pro vyjádření informací navíc — ať už šlo o "smajlíky" nebo zvýrazňování slov \*hvězdičkami\* či \_podtržítky\_. Právě takovými konvencemi se inspirovali tvůrci některých CMS, zvláště wiki a aplikací pro generování webových stránek offline. Ono je totiž poměrně nepohodlné psát značky HTML, pokud nepoužíváte nějaký sofistikovaný HTML editor, a čtení zdrojových kódů webových stránek je snad ještě horší — syntaktický "balast" překáží v soustředění se na samotný text. Co nám tedy minimalistické značkovací jazyky přinášejí? Jak jsem již zmínil, docela dobře čitelné dokumenty přímo v prostém textu a při použití vhodného softwaru odstínění od HTML při psaní textů pro web. Ale to není vše, je totiž možné automatizovaně konvertovat texty do více různých podob než jen do obyčejného (X)HTML. Mezi podporované formáty může patřit LaTeX, DocBook, Open Document Format nebo některá šablona pro prezentace v HTML. ##Přehled Mezi populárnější minimalistické značkovací jazyky patří např.: * [Markdown](http://daringfireball.net/projects/markdown/) (o něm více níže) * [reStructuredText](http://docutils.sourceforge.net/rst.html) (součást Pythonu, resp. [Docutils](http://docutils.sourceforge.net/index.html) — viz [PEP 287](http://www.python.org/dev/peps/pep-0287/)) * [Textile](http://textile.sitemonks.com/) a [Texy!](http://texy.info/) (populární především na webu) * [AsciiDoc](http://www.methods.co.nz/asciidoc/) (velmi komplexní, přímo přeložitelný do DocBooku) * [txt2tags](http://txt2tags.org/) Přehled některých dalších lehkotonážních značkovacích jazyků najdete např. na [Wikipedii](http://en.wikipedia.org/wiki/Lightweight_markup_language). ##Markdown Markdownu se zde věnuji z toho prostého důvodu, že je to můj osobní favorit. Jednak mi vyhovuje jeho syntaxe, jednak existuje několik jeho implementací — v Perlu, Ruby, Pythonu a především PHP, díky čemuž se umí integrovat např. do CMS [WordPress](http://wordpress.org/extend/plugins/tags/markdown) nebo [DokuWiki](http://www.dokuwiki.org/plugin:markdownextra). Navíc je podporovaný programem [pandoc](http://johnmacfarlane.net/pandoc/) pro konverzi do pestré řady jiných formátů a nemohu zapomenout ani na jednoduchý WYSIWYG editor [ReText](http://sourceforge.net/projects/retext/). Sluší se ale podotknout, že různé implementace nemusí být zcela kompatibilní — jde především o různá rozšíření oproti [původní implementaci Johna Grubera](http://daringfireball.net/projects/markdown/), ale [Markdown Extra](http://michelf.com/projects/php-markdown/extra/) a [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) se dají považovat za de facto nepsaný standard. ###Syntaxe Pojďme se nejprve podívat na základní syntaxi Markdownu, která by měla být v zásadě stejná napříč různými implementacemi. * zvýrazňování se provádí pomocí \*hvězdiček\* nebo \_podtržítek\_, příp. výraznější zvýraznění zdvojením \*\*hvězdiček\*\* nebo \_\_podtržítek\_\_ * odstavce jsou bloky neodsazeného textu oddělené prázdnými řádky * nadpisy jsou jako v HTML šesti druhů (podle významnosti) a určují se uvedením odpovídajícího počtu znaků pro kanál (#) na začátku řádku, tzn. `# nadpis první úrovně`, `## nadpis druhé úrovně` atd. * blokové citace jsou (jako v e-mailech) bloky textu, jejichž každý řádek začíná znakem "být větší než" (>) * seznamy * bod nečíslovaného seznamu je řádek, který začíná znakem +, - nebo \*, za nímž následuje mezera a pak text * bod číslovaného seznamu je řádek, který začíná číslem vyjádřeným řadovou číslovkou, za níž následuje mezera a pak text * seznam musí být od okolního textu oddělen prázdnými řádky * do další úrovně seznamu se dostaneme odsazením bodu o čtyři mezery nebo tabulátor * odkazy se obvykle vkládají pomocí `[text odkazu](url)` — za odkaz můžeme volitelně přidat text, který se zobrazí po najetí kurzoru v bublině, tedy `[text odkazu](http://neco.nekde.foo/bar/ "bublina")` * syntaxe pro vkládání obrázků je podobné té pro odkazy, pouze se předřadí vykřičník: `![alternativní text](url)` — opět s volitelným popiskem do bubliny * horizontální čára se vloží třemi a více hvězdičkami, podtržítky nebo podobnými znaky na samostatném řádku * do textu formátovaného pomocí Markdownu můžeme prakticky libovolně zapisovat značky a entity HTML, přitom * Markdown inteligentně rozpozná, kde ampersand nahradit entitou a kde ne — podobně chytře nahrazuje také také znak "být menší než" (<) * blokové elementy HTML (typicky tabulky) musí být od okolního textu odděleny prázdnými řádky a syntaxe Markdownu se v nich neinterpretuje * zdrojové kódy * v ukázkách zdrojového kódu se neinterpretuje syntaxe HTML, ani Markdownu * zdrojový kód v textu se obklopuje \`zpětnými apostrofy\` * blok kódu se odsazuje o čtyři mezery nebo tabulátor, od okolního textu musí být oddělen prázdnými řádky * pokud se Markdown snaží interpretovat některý speciální symbol (např. číslo, za nímž následuje tečka, na začátku odstavce), můžeme si pomoci zpětným lomítkem, které symbol zneškodní (kupř. `1969\. foo bar`, abychom se zbavili interpretace jako bod seznamu) Aby to nebylo bez příkladu, můžete si prohlédnout [tento článek napsaný pomocí Markdownu](./clanek.txt). Pro vyčerpávající popis se podívejte na dokumentaci k implementaci, kterou používáte. V tomto stručném přehledu jsem vycházel z [původního Markdownu](http://daringfireball.net/projects/markdown/syntax), který si můžete vyzkoušet také online díky nástroji [Dingus](http://daringfireball.net/projects/markdown/dingus). ###Implementace Existuje mnoho implementací Markdownu v mnoha programovacích jazycích — nebudu se zde snažit o kompletní přehled, ale odkážu vás na [velmi pěkný přehled odkazů týkajících se Markdownu](http://xbeta.org/wiki/show/Markdown) a [Wikipedii](http://en.wikipedia.org/wiki/Markdown#Alternate_implementations). Musím ale upozornit na skutečnost, že různé implementace vesměs nejsou zcela kompatibilní, což se nemusí týkat jen různých rozšíření syntaxe, ale i interpretace vcelku základních záležitostí. Pro kontrolu doporučuji [test kompatibility s původní implementací](http://six.pairlist.net/pipermail/markdown-discuss/2004-December/000909.html) a [Babelmark](http://babelmark.bobtfish.net/), který ve webovém prohlížeči zobrazuje HTML výstup různých implementací Markdownu pro vámi zadaný vstup. Mezi nejrozšířenější implementace patří vedle té [původní](http://daringfireball.net/projects/markdown/) od Johna Grubera v Perlu např. [PHP Markdown](http://michelf.com/projects/php-markdown/), [python-markdown](http://www.freewisdom.org/projects/python-markdown/) (resp. [python-markdown2](https://github.com/trentm/python-markdown2)), [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) a [Text::Markdown](http://search.cpan.org/~bobtfish/Text-Markdown-1.000031/lib/Text/Markdown.pm) (nachází se v CPAN) v Perlu, [Maruku](http://maruku.rubyforge.org/) a [kramdown](http://kramdown.rubyforge.org/) v Ruby, [Showdown](http://www.showdown.im/) (funguje jako pseudoWYSIWYG editor ve webovém prohlížeči) a konečně [Pandoc](http://johnmacfarlane.net/pandoc/), jemuž se budu dále věnovat. ####Pandoc Pandoc je univerzální konverzní nástroj, který si rozumí nejen s Markdownem a HTML, ale i s několika dalšími minimalistickými jazyky jako reStructuredText nebo Textile — a na výstupu nabízí pestrou škálu formátů zahrnujících také LaTeX, ODT, RTF, syntaxi MediaWiki, groff pro manuálové stránky, DocBook nebo třeba prezentace v HTML s využitím šablon [S5](http://meyerweb.com/eric/tools/s5/) a [Slidy](http://www.w3.org/Talks/Tools/Slidy). Napsaný je v Haskellu a pravděpodobně ho najdete v repozitářích své distribuce, můžete také [použít](http://johnmacfarlane.net/pandoc/installing.html) nástroj `cabal` určený ke správě knihoven Haskellu — nebo je možné si prostě [stáhnout](http://code.google.com/p/pandoc/downloads/list) zdrojové kódy, resp. na MS Windows nebo Mac OS X připravenou binárku. A pro případ nouze je tu [online verze](http://johnmacfarlane.net/pandoc/try). Vedle pestré škály podporovaných formátů Pandoc také nabízí rozšíření syntaxe Markdownu o např. poznámky pod čarou, seznam citací, zvýrazňování syntaxe v ukázkách zdrojových kódů, bohatší možnosti ohledně seznamů, matematické vzorce, tabulky aj. To dalece přesahuje rozsah tohoto článku, proto vás pouze odkážu na [dokumentaci](http://johnmacfarlane.net/pandoc/README.html). Pro demonstraci jeden příklad tabulky: +----------------+---------------+--------------+-------------+-----------------+ | vlastnost | Nook Classic | Simple Touch | Nook Color | Amazon Kindle 3 | +================+===============+==============+=============+=================+ | hmotnost (g) | 329 | 212 | 448 | 241 | +----------------+---------------+--------------+-------------+-----------------+ | rozměry (cm) | 19.6×12.5×1.3 | 17×13×1.2 | 21×13×1.2 | 19×12.3×0.9 | +----------------+---------------+--------------+-------------+-----------------+ | displej | 6" E Ink | dotykový 6" | 7" LCD | 6" E Ink Pearl | | a ovládání | + 3,5" LCD | E Ink Pearl | dotykové | klávesnice | +----------------+---------------+--------------+-------------+-----------------+ | paměť pro data | 2GB interní | 2GB interní | 8GB interní | 4GB interní | | | + microSDHC | + microSDHC | + microSDHC | | +----------------+---------------+--------------+-------------+-----------------+ | připojení | WiFi (+ 3G) | WiFi | WiFi | WiFi | | | microUSB | microUSB | microUSB | microUSB | +----------------+---------------+--------------+-------------+-----------------+ | zvuk | 3,5mm jack | nic | 3,5mm jack | 3,5mm jack | | | reproduktor | | reproduktor | reproduktor | +----------------+---------------+--------------+-------------+-----------------+ | baterie | 1530mAh | 1530mAh | 4000 mAh | 1750mAh | | | vyměnitelná | vyměnitelná | pevná | pevná | | | až 10 dní | "dva měsíce" | 8 hodin | asi tři týdny | +----------------+---------------+--------------+-------------+-----------------+ | systém | Android 1.5 | Android 2.1 | Android 2.2 | embedded Linux | +----------------+---------------+--------------+-------------+-----------------+ | cena | $119 ($169) | $139 | $259 | $139 | +----------------+---------------+--------------+-------------+-----------------+ Tato tabulka pochází z mé prezentace na [Openmobility 2011](http://www.openmobility.cz/konference/openmobility-konference-2011/) — můžete si prohlédnout také [slajdy](http://www.openmobility.cz/wp-content/uploads/2011/05/nook_slidy_openmobility-2011-1.html) využívající šablonu Slidy — vygenerované pomocí nástroje Pandoc příkazem: pandoc -w slidy -s nook.text -o nook_slidy_openmobility.html ##Závěr Doufám, že se mi podařilo ukázat jiný pohled na tvorbu textových dokumentů (typicky určených pro web). Třeba vás zaujme a najdete si svou cestu (nebo "workflow", jak se dnes říká), jak efektivně psát.