diff -r eec920c4bddf -r 4d33f14e99dd ukázka/skriptování.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ukázka/skriptování.xml	Sat Nov 17 23:05:59 2012 +0100
@@ -0,0 +1,358 @@
+<stránka
+	xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
+	xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
+	<nadpis>Skriptování</nadpis>
+	<perex>Na stránku můžeme vložit výstup skriptů.</perex>
+	<pořadí>50</pořadí>
+
+	<text xmlns="http://www.w3.org/1999/xhtml">
+
+		<p>
+			Na stránkách můžeme používat skripty.
+			Spouští se při generování a jejich standardní výstup se vloží do stránky.
+			Třeba doprostřed textu ostavce nebo do jiného elementu.
+		</p>
+		<p>
+			Příklad:
+			<em>
+				Tyto stránky byly vygenerované v systému
+				<span title="tento text pochází ze skriptu"><m:skript jazyk="bash">uname -o</m:skript></span>.
+			</em>
+		</p>
+
+		<p>
+			Díky skriptování můžeme stránky obohatit o prakticky libovolný obsah – 
+			jak prostý text, tak i XHTML fragmenty.<m:podČarou>
+				Zapíná se pomocí atributu <code>výstup="xhtml"</code> a generátor pak kontroluje správné formátování – 
+				nestane se vám, že byste omylem vygenerovali stránky s překříženými nebo neuzavřenými značkami.
+				Výchozím jmenným prostorem je XHTML a je dostupný i jmenný prostor pro makra (<code>m</code>).
+			</m:podČarou>
+		</p>
+		<p>
+			Skriptování ale může být nebezpečné, pokud byste spustili generátor na stránkách,
+			které psal někdo nedůvěryhodný a vložil do nich škodlivý kód.
+			Kromě toho, ukázková sada stránek by měla být přeložitelná kdekoli a mít minimum závislostí
+			(ne každý musí mít nainstalovaný Perl nebo Python či další podporované interprety).
+			Proto je skriptování ve výchozím stavu vypnuté – je potřeba ho povolit v souboru <code>web.conf</code>.
+		</p>
+
+		<h2>Podporované jazyky</h2>
+		<p>
+			V současnosti jsou podporované tyto jazyky:
+		</p>
+
+		<table>
+			<thead>
+				<tr>
+					<td>Jazyk</td>
+					<td>Interpret</td>
+				</tr>
+			</thead>
+			<tbody>
+				<m:skript jazyk="perl" výstup="xhtml"><![CDATA[
+use strict;
+use warnings;
+
+open(JAVA, "<", $ENV{"XWG_SKRIPTOVANI_JAVA"}) or die $!;
+
+while (<JAVA>) {
+	if (/podporovanýJazyk\.put\("(\w+)",\s*"(.*)"\);/) {
+		print "<tr><td><code>$1</code></td><td><code>$2</code></td></tr>\n";
+	}
+}
+				]]></m:skript>
+			</tbody>
+		</table>
+
+		<h3>Perl – ukázka</h3>
+		<p>Jazyky použité nebo citované na této stránce:</p>
+		<!--
+			Lepšího výsledku bychom samozřejmě dosáhli pomocí XPath dotazu,
+			ale toto je příklad na Perl :-)
+		-->
+		<pre><m:skript jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+open(XML, "<", $ENV{"XWG_STRANKA_SOUBOR"}) or die $!;
+my %skripty;
+
+while (<XML>) {
+	if (/m:skript\s+jazyk="(\w+)"/) {
+		$skripty{$1}++;
+	}
+}
+
+for(keys(%skripty)) {
+	print "$skripty{$_}×\t $_\n";
+}
+			]]></m:skript></pre>
+
+		<h3>BASH – ukázka</h3>
+		<pre><m:skript jazyk="bash"><![CDATA[
+echo -n "Právě je: ";
+date;
+echo -n "Operační systém: ";
+uname -o;
+echo -n "SHA-1 otisk zdrojáku této stránky: ";
+sha1sum "$XWG_STRANKA_SOUBOR" | cut -f 1 -d " ";
+			]]></m:skript></pre>
+
+			<!--
+			<h2>PHP</h2>
+			<pre style="max-height: 200px;"><m:skript jazyk="php"><![CDATA[
+<?php
+phpinfo();
+?>
+			]]></m:skript></pre>
+			-->
+
+			<h2>Proměnné prostředí</h2>
+			<p>
+				Ve skriptech máme dostupné následující proměnné prostředí:
+			</p>
+
+			<table>
+				<thead>
+					<tr>
+						<td>Proměnná</td>
+						<td>Význam</td>
+					</tr>
+				</thead>
+				<tbody>
+					<!-- Pokud načítáme skript ze souboru, je atribut jazyk nepovinný. -->
+					<m:skript jazyk="perl" výstup="xhtml" src="skriptování-proměnné.pl"/>
+				</tbody>
+			</table>
+
+			<p>
+				Kód:
+			</p>
+
+			<m:pre jazyk="xml"><![CDATA[<m:skript jazyk="bash">
+echo "URI:    $XWG_STRANKA_URI";
+echo "Soubor: $XWG_STRANKA_SOUBOR";
+echo "Nadpis: $XWG_STRANKA_NADPIS";
+echo "Perex:  $XWG_STRANKA_PEREX";
+</m:skript>]]></m:pre>
+
+			<p>nám vypíše:</p>
+
+			<pre><m:skript jazyk="bash"><![CDATA[
+echo "URI:    $XWG_STRANKA_URI" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
+echo "Soubor: $XWG_STRANKA_SOUBOR" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
+echo "Nadpis: $XWG_STRANKA_NADPIS";
+echo "Perex:  $XWG_STRANKA_PEREX";
+		]]></m:skript></pre>
+
+		<h2 id="makraZeSkriptů">Makra ze skriptů</h2>
+		<p>
+			XML generované skriptem může také obsahovat makra, která se následně interptetují.
+			<m:skript jazyk="bash" výstup="xhtml"><![CDATA[
+echo '<m:skript jazyk="bash">'; # Ty zrůdo! :-)
+echo 'echo "Takže můžeš skriptovat, když skriptuješ,";';
+echo '</m:skript>';
+			]]></m:skript>
+			nebo dělat něco užitečnějšího.
+		</p>
+		
+		<m:skript jazyk="perl" výstup="xhtml"><![CDATA[
+use strict;
+use warnings;
+
+my $adresar = "vstup/makra";
+
+print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
+print "	node		[shape=\"box\"];\n";
+print "	koren	[label=\"Uživatelská makra\"];\n";
+
+opendir(DIR, $adresar) or die $!;
+my $i = 0;
+while (readdir(DIR)) {
+	next if (/^\./);
+	# Měli bychom ošetřit zvláštní znaky v názvech souborů,
+	# abychom nezpůsobili chybu GraphVizu.
+	print "	n$i		[label=\"$_\"];\n";
+	print "	koren	-> n$i;\n";
+	$i++;
+}
+
+print "</m:diagram>";
+closedir(DIR);
+		]]></m:skript>
+
+		<p>…třeba vygenerovat tento diagram následujícím perlovským skriptem:</p>
+
+		<m:pre jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+my $adresar = "vstup/makra";
+
+print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
+print "	node	[shape=\"box\"];\n";
+print "	koren	[label=\"Uživatelská makra\"];\n";
+
+opendir(DIR, $adresar) or die $!;
+my $i = 0;
+while (readdir(DIR)) {
+	next if (/^\./);
+	# Měli bychom ošetřit zvláštní znaky v názvech souborů,
+	# abychom nezpůsobili chybu GraphVizu.
+	print "	n$i		[label=\"$_\"];\n";
+	print "	koren	-> n$i;\n";
+	$i++;
+}
+
+print "</m:diagram>";
+closedir(DIR);]]></m:pre>
+
+		<p>
+			Který vložíme zabalený v <code><![CDATA[<m:skript jazyk="perl" výstup="xhtml"> … </m:skript>]]></code> do stránky.
+		</p>
+		<p>
+			Známá chyba: ve skriptech zatím nefungují poznámky pod čarou (a není jisté, jestli kdy fungovat budou – pravděpodobně by to vyžadovalo vícefázové zpracování).
+		</p>
+
+		<h2>Makra ve skriptech</h2>
+		
+		<p>
+			Uvnitř zdrojového kódu skriptu můžeme používat jiná makra.
+			Např. tento kód:
+		</p>
+
+		<m:pre jazyk="xml"><![CDATA[<pre>
+	<m:skript jazyk="perl">
+		print "Náš podnik se jmenuje <m:firma/>";
+	</m:skript>
+</pre>]]></m:pre>
+
+		<p>
+			nám vygeneruje:
+		</p>
+
+		<pre><m:skript jazyk="perl">
+				print "Náš podnik se jmenuje <m:firma/>";
+		</m:skript></pre>
+
+		<p>
+			Můžete si tak vytvořit makra pro opakující se části
+			a používat je jak v textu stránek, tak ve skriptech nebo diagramech.<m:podČarou>
+				Jen pozor na ošetření zvláštních znaků – pokud text takové znaky obsahuje,
+				je dobré ho zabalit ještě do jedné značky, která se postará o <em>escapování</em> 
+				pro daný kontext (skriptovací jazyk a prostředí v něm – např. apostrofy vs. uvozovky).
+			</m:podČarou>
+		</p>
+		
+		<p>
+			Jen pro připomenutí: nejedná se o nějaké primitivní zástupky a nahrazování textu
+			– makra můžou být parametrizovaná, obsahovat atributy (např. pád a číslo) nebo vnořené elementy
+			a na základě této parametrizace vytvářet odlišný výstup, který je následně předán skriptu.
+		</p>
+		
+		<pre><m:skript jazyk="bash">
+			echo "S naší <m:firma pád="7"/> budete jistě spokojeni!";
+			echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
+		</m:skript></pre>
+		
+		<p>
+			Zdrojový kód:
+		</p>
+		
+		<!-- Pozor: ve zvýrazňovači syntaxe Pygmentize je chyba – neumí diakritiku – správně je: pád="7" -->
+		<m:pre jazyk="xml"><![CDATA[<pre>
+	<m:skript jazyk="bash">
+		echo "S naší <m:firma pad="7"/> budete jistě spokojeni!";
+		echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
+	</m:skript>
+</pre>]]></m:pre>
+
+		<p>
+			Skripty v těchto příkladech nejsou příliš užitečné, protože pouze vypisují text,
+			který by šlo vložit přímo do XML stránky
+			– předpokládá se, že ve svých skriptech budete dělat něco zajímavějšího :-)
+		</p>
+
+		<h2>Skripty v makrech</h2>
+		<p>
+			Uvnitř definic maker můžeme volat<m:podČarou>
+				Ovšem trochu jiným způsobem, než ve stránkách –
+				nacházíme se totiž v <em>programu</em> (XSL šablona definující makro)
+				nikoli v <em>datovém souboru</em> (XML stránka).
+			</m:podČarou>
+			jiná makra – mj. skripty.
+			Toho jsme využili v makru, které generuje tabulku verzí z mercurialu
+			– ten umí vypsat historii úložiště v XML, které následně snadno zpracujeme v XSLT.
+		</p>
+
+		<m:hg-verze/>
+
+		<p>
+			Toto makro naleznete v souboru <code>vstup/makra/hg-verze.xsl</code>.
+		</p>
+
+		<h2>Vnořování maker</h2>
+		<p>
+			Trochu jiný případ je vnořování maker na stránce.
+			Např. si chceme vypsat vybrané internetové služby:
+		</p>
+		<m:tabulka>
+			<m:skript jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+print "Port\tSlužba\tProtokol\n";
+open(S, "<", "/etc/services") or die $!;
+while (<S>) {
+	if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
+		print "$2\t$1\t$3\n";
+	}
+}
+			]]></m:skript>
+		</m:tabulka>
+		
+		<p>
+			Pro vygenerování použijeme dvě makra – tabulku a skript – která vložíme do textu stránky:
+		</p>
+		
+		<m:pre jazyk="xml"><![CDATA[
+<m:tabulka>
+	<m:skript jazyk="perl"><![CDATA[
+		print "Port\tSlužba\tProtokol\n";
+		open(S, "<", "/etc/services") or die $!;
+		while (<S>) {
+			if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
+				print "$2\t$1\t$3\n";
+			}
+		}
+	]]]]>&gt;<![CDATA[</m:skript>
+</m:tabulka>]]></m:pre>
+
+		<p>
+			Ve skriptu v tomto případě negenerujeme XHTML značky, ale CSV (s tabulátory)
+			a o převod na XHTML tabulku se postará XSL šablona.
+		</p>
+
+		<!--
+			Nebo to taky můžeme napsat na jeden řádek:
+			cat /etc/services | perl -ne 'if (/(\w+)\s+(21|22|25|80)\/(tcp)/) { print "$2\t$1\t$3\n";}'
+			a vložit do tabulky jako BASH skript :-)
+		-->
+
+		<p>
+			Podobně bychom mohli postupovat i u <a href="#makraZeSkriptů">diagramu</a> –
+			negenerovat skriptem značky makra, ale pouze jeho obsah – zadání diagramu, nebo jen jeho část.
+			Někdy se ale může hodit ve skriptu nastavovat atributy elementů nebo elementy vytvářet dynamicky.
+		</p>
+
+		<p>
+			Skriptování lze použít i pro generování zdrojového kódu, který bude následně zvýrazněn
+			pomocí značky <code>&lt;m:pre jazyk="…"/&gt;</code>.
+			Toho využíváme na stránce <m:a href="zdrojáky">Zdrojové kódy</m:a> v případě SQL a XML ukázek.
+			Skript můžeme použít mj. i ke zkrácení zdrojáku – když chceme vypsat jen jeho relevantní část.
+		</p>
+
+	</text>
+
+</stránka>
+