Opis składni GuideXML

1.  Podstawowe założenia

Założenia GuideXML

Składnia GuideXML jest przejrzysta, a jednocześnie pozostawia autorowi wiele możliwości formatowania tekstu. Celem było stworzenie czegoś, czego łatwo się nauczyć i co umożliwiłoby tworzenie dokumentacji w sposób jaki nam odpowiada. Liczba tagów jest ograniczona do absolutnego minimum - są tylko takie, które są naprawdę potrzebne. Dzięki temu łatwo przetworzyć nasze dokumenty na inne formaty, takie jak DocBook, XML/SGML czy gotowy do wyświetlenia na stronie HTML.

Celem jest stworzenie prostego formatu, którego tworzenie i konwersja będą maksymalnie uproszczone.

Dalsze informacje

Wszystkie osoby, które planują podzielenie się dokumentacją z Gentoo lub takie, które chcą przetestować GuideXML, powinny przeczytać Wskazówki dotyczące tworzenia dokumentacji Gentoo.

Warto również obejrzeć źródło XML tego dokumentu.

2.  GuideXML

Podstawowa struktura

Zacznijmy naukę składni GuideXML. Pierwszy etap to nagłówek dokumentu.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/pl/guide.xml" lang="pl">
<title>Dokumentacja Gentoo</title>

<author title="Autor">
  <mail link="autor@gentoo.org">Imię Nazwisko</mail>
</author>

<abstract>
Tekst opisujący proces tworzenia dokumentu za pomocą składni GuideXML
będącej oficjalnym formatem dokumentacji Gentoo. Ten dokument również powstał w
GuideXML.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.0</version>
<date>2004-12-25</date>

Pierwsza linia to niezbędny tag, dzięki któremu dokument jest identyfikowany jako XML i w którym podany jest adres pliku DTD. Linia <!-- $Header$ --> pomaga w śledzeniu zmian wersji dokumentów i zostanie automatycznie zmieniona przez serwer CVS. Później wpisujemy tag <guide>. Pomiędzy parą tagów <guide> </guide> zawarty jest cały dokument.
Parametr link jest niezbędny i powinien zawierać względną ścieżkę do pliku, chociaż sama nazwa pliku również będzie działać. Tag ten jest wykorzystywany głównie do tworzenia odnośników do stron przeznaczonych do druku. Jeśli wstawi się tu złą wartość, odnośnik do wersji do druku nie będzie działał lub będzie wskazywał na zły dokument. Przetłumaczone dokumenty muszą zawierać pełne ścieżki, ponieważ jest to wykorzystywane przy porównywaniu wersji tłumaczenia i oryginału.
Parametr lang wykorzystujemy do określenia kodu języka, w którym napisano dokument. Jest on wykorzystywany do formatowania daty oraz do wyświetlania informacji takich jak "Uwaga" czy "Ważne" w odpowiednim języku. Domyślny język to angielski.

Kolejny znacznik to <title>, który zawiera tytuł całego dokumentu.

Następnie występuje jeden lub kilka tagów <author>. Zawierają one informacje o osobach, które napisały konkretny dokument. Każdy tag <author> posiada opcjonalny element title wykorzystywany do określenia roli danej osoby w powstawaniu dokumentu (autor, redaktor, tłumacz, itd.). W przykładzie nazwiska autorów są zamknięte wewnątrz taga <mail>, dzięki któremu można ustawić adres e-mail autora. Tag <mail> jest opcjonalny i nie ma problemu jeśli zostanie pominięty. Dokument musi zawierać co najmniej jeden znacznik <author>.

Kolejne znaczniki to <abstract>, <version> i <date>, które zawierają krótki opis dokumentu, jego numer wersji oraz datę ostatniej aktualizacji (w formacie RRRR-MM-DD). Niewłaściwie wpisane daty zostaną przedrukowane do pliku HTML bez konwersji.

To wszystkie znaczniki, które muszą pojawić się w nagłówku dokumentu. Poza znacznikami <title> i <mail>, żaden z nich nie powinien pojawić się nigdzie wewnątrz dokumentu. Mogą one występować tylko natychmiast po znaczniku <guide>. Zalecamy wpisywanie ich przed właściwą treścią dokumentu.

Znacznik <license/> jest wykorzystywany do publikowania dokumentów na licencji Creative Commons - Attribution / Share Alike, tak jak wymaga tego Documentation Policy.

Rozdziały i sekcje

Po wpisaniu wszystkich podstawowych tagów możemy przystąpić do dodawania fragmentów szkieletu dokumentu. Nasze dokumenty są podzielone na rozdziały, a każdy z nich posiada jedną lub więcej sekcji. Każdy rozdział i każda sekcja posiada własny tytuł. Poniżej znajduje się przykładowy rozdział z jedną sekcją, zawierającą akapit tekstu. Po dodaniu poniższego tekstu do nagłówka dokumentu i po zamknięciu całości tagiem </guide> otrzymamy kompletny plik GuideXML.

<chapter>
<title>To jest rozdział</title>
<section>
<title>A to jego sekcja</title>
<body>

<p>
To zawartość akapitu.
</p>

</body>
</section>
</chapter>

Powyżej wpisaliśmy tytuł rozdziału za pomocą taga <title> wewnątrz taga <chapter>. Potem stworzyliśmy sekcję dodając tag <section>. Wewnątrz sekcji znajdują się dwa tagi, <title> i <body>. Element <title> omówiliśmy już wcześniej. Teraz pora na <body>. Jest to część pliku, która zawiera właściwy tekst dokumentu. Za chwilę omówimy wszystkie znaczniki, które można stosować wewnątrz <body>.

Przykładowe <body>

Teraz nauczymy się jak wprowadzać właściwą treść dokumentu. Poniżej znajduje się kod XML dla przykładowego znacznika <body>.

<p>
To akapit.  <path>/etc/passwd</path> jest plikiem.
<uri>http://forums.gentoo.org</uri> to moja ulubiona strona.
Wpisz <c>ls</c> jeśli masz ochotę.  Ja <e>naprawdę</e> jestem śpiący.
</p>

<pre caption="Przykładowy listing">
To wyjście programu.
# <i>to polecenia wpisywane przez użytkownika</i>

Można uczynić HTML/XML bardziej przejrzystym używając wyróżnień:
<foo><i>bar</i></foo>

<comment>(Tak dodaje się komentarze)</comment>
</pre>

<note>
To notatka.
</note>

<warn>
To ostrzeżenie.
</warn>

<impo>
To jest ważne.
</impo>

A oto jak powyższa zawartość <body> zostanie wyświetlone:

To akapit. /etc/passwd jest plikiem. http://forums.gentoo.org to moja ulubiona strona. Wpisz ls jeśli masz ochotę. Ja naprawdę jestem śpiący.

To wyjście programu.
# to polecenia wpisywane przez użytkownika

Można uczynić HTML/XML bardziej przejrzystym używając wyróżnień:
<foo>bar</foo>

(Tak dodaje się komentarze)

Znaczniki z <body>

Przed chwilą pokazaliśmy całe mnóstwo nowych znaczników. Teraz omówimy je po kolei. Znaczniki <p> (paragraf), <pre> (listing), <note> (notatka), <warn> (ostrzeżenie) i <impo> (ważne) muszą zawierać jedną lub więcej linii tekstu. Pomijając <table>, <ul>, <ol> i <dl>, o których opowiemy za chwilę, są to jedyne znaczniki jakie mogą pojawić się wewnątrz <body>. Znaczniki te nie mogą być zagnieżdżone wewnątrz siebie, czyli na przykład nie wolno umieszczać <note> wewnątrz <p>. Znacznik <pre> formatuje zawartość dokładnie tak jak jest wpisana w pliku, dlatego nadaje się doskonale do podawania wyjścia programów i serii poleceń. Każdy znacznik <pre> musi być zatytułowany za pomocą atrybutu caption w następujący sposób:

<pre caption="Wynik polecenia uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

Cytowanie

Delegates from the original 13 states formed the Contented Congress. Thomas Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration of Independence. Franklin discovered electricity by rubbing two cats backwards and declared, "A horse divided against itself cannot stand." Franklin died in 1790 and is still dead.

—Anonimowy autor

Z cytatów korzysta się, aby podpisać konkretny fragment tekstu. Jest to zwykły znacznik akapitu z atrybutem by zawierającym podpis.

<p by="Anonimowy autor">
Delegates from the original 13 states formed the...
</p>

<path>, <c>, <b>, <e>, <sub> i <sup>

Znaczniki <path>, <c>, <b>, <e>, <sub> i <sup> mogą być wykorzystywane wewnątrz każdego znacznika w <body> poza <pre>.

Znacznik <path> służy do wyróżnienia ścieżki do pliku znajdującego się na twardym dysku. Może to być zarówno ścieżka absolutna jak i względna. Może to też być po prostu sama nazwa pliku. Zawartość znacznika jest zwykle wyświetlana czcionką o szarej szerokości znaku.

Znacznik <c> jest wykorzystywany do wyróżnienia poleceń lub informacji wpisywanych przez użytkownika. <c> jest sposobem na zwrócenie uwagi czytelnika na fragmenty tekstu, które będzie musiał wpisać jako polecenia. Wszystkie znaczniki XML w tym tekście są wyróżnione za pomocą <c>, ponieważ przedstawiają one coś, co użytkownik będzie chciał wpisać i co nie jest ścieżką do pliku. Używając <c> umożliwiamy użytkownikom szybką identyfikację poleceń, które będą wpisywać. W związku z tym, że znaczniki <c> bardzo wyróżniają się w tekście, nie ma potrzeby otaczania poleceń cudzysłowami. Na przykład, nie warto wpisywać znaczników "<c>" tak jak zrobiliśmy to w tym zdaniu. Dzięki temu dokument staje się bardziej czytelny i ładniejszy.

Znacznik <b> jest wykorzystywany do pogrubienia fragmentów tekstu.

Znacznik <e> służy do wyróżniania słów lub zdań; na przykład; Naprawdę powinienem częściej używać średników. Jak widać tekst jest wyróżniony w akapicie za pomocą emfazy. Pozwala to na urozmaicenie długich i nudnych tekstów.

Znaczniki <sub> i <sup> są wykorzystywane do pisania w _{indeksie dolnym} i w ^{indeksie górnym}.

Kody źródłowe i kolorowanie składni

Aby zwiększyć czytelność listingów, są dostępne następujące znaczniki wewnątrz bloków <pre>:

<i>

Wyróżnia polecenia wpisywane przez użytkownika

<comment>

Komentarze do poleceń

<keyword>

Wyróżnia słowa kluczowe w języku, w którym jest kod

<ident>

Wykorzystywany jako identyfikator

<const>

Oznacza stałą

<stmt>

Oznacza wyrażenie

<var>

Oznacza zmienną

Przykładowy pokolorowany blok <pre>:

# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

<mail> i <uri>

Znacznik <mail> omawialiśmy już wcześniej. Korzysta się z niego w celu utworzenia odnośnika zawierającego konkretny adres e-mailowy. Ma on składnię <mail link="foo.bar@example.com">Imię Nazwisko</mail>. Można też wyświetlać jedynie adres e-mail, za pomocą składni <mail>foo.bar@example.com</mail>. Będzie to wyświetlone jako foo.bar@example.com.

Istnieje również skrótowa forma służąca do wyświetlania nazwisk oraz adresów e-mail deweloperów Gentoo. Zarówno <mail>neysx</mail> jak i <mail link="neysx"/> zostaną wyświetlone jako Xavier Neys. Jeśli zamierza się podać adres e-mail ale z treścią inną niż imię i nazwisko danego dewelopera, należy skorzystać z drugiej postaci. Na przykład jeśli chcemy napisać tylko imię danego dewelopera: <mail link="neysx">Xavier</mail> co wyświetli się jako: Xavier.
Bywa to szczególnie przydatne gdy nazwisko danego dewelopera zawiera jakieś międzynarodowe znaki których nie umie się wpisać do dokumentu.

Znacznik <uri> jest wykorzystywany do tworzenia odnośników do plików i stron w Internecie. Może on mieć dwie postaci. W pierwszej wyświetlamy adres jako tekst odnośnika, np. http://forums.gentoo.org. Aby utworzyć taki odnośnik, wystarczy wpisać <uri>http://forums.gentoo.org</uri>. Drugi sposób to podanie jakiegoś tekstu, który ma być odnośnikiem. Na przykład: Forum Gentoo. W celu stworzenia takiego odnośnika, należy wpisać <uri link="http://forums.gentoo.org">Forum Gentoo</uri>. Nie trzeba pisać http://www.gentoo.org/, aby tworzyć odnośniki do innych stron Gentoo. Na przykład odnośnik do Centrum dokumentacji powinien wyglądać tak: <uri link="/doc/pl/index.xml">Centrum dokumentacji Gentoo</uri>. Można ominąć też index.xml. Zadziała odnośnik <uri link="/doc/pl/">Centrum dokumentacji Gentoo</uri>. Dodanie znaku slash na końcu adresu oszczędzi serwerowi jedno zapytanie HTTP jakie musiałby wykonać gdyby go tam nie było.

Nie należy korzystać ze znacznika <uri> z parametrem link który zaczyna się od mailto:. Od podawania adresów e-mail jest znacznik <mail>.

Należy również powstrzymać się od złego zwyczaju kliknij tutaj tak jak jest to zalecane przez W3C.

Ilustracje

Teraz pora na omówienie sposobu dodawania ilustracji do dokumentu. Składnia wygląda następująco: <figure link="mygfx.png" short="mój obrazek" caption="mój ulubiony obrazek"/>. Atrybut link wskazuje na konkretny plik obrazka, który chcemy wykorzystać, atrybut short to skrócony opis ilustracji (obecnie umieszczany w wartości alt obrazka). Można również skorzystać ze standardowego HTML-owego znacznika <img src="foo.gif"/>, dzięki któremu możliwe jest dodanie ilustracji bez nagłówków, obramowania itp.

Tabele

Nasza składnia tworzenie tabel jest bardzo uproszczona i dość podobna do tej znanej z HTML. Wykorzystujemy do tego znacznik <table>. Wiersze tabeli to znaczniki <tr>. Nie ma jednak znacznika <td> znanego z HTML. Zamiast tego mamy dwa inne, <th> zawierający nagłówki i <ti> zawierający dane. Z <th> można skorzystać w dowolnym miejscu, podobnie jak z <ti>. Nie ma żadnej reguły mówiącej o tym, że <th> mogą znajdować się tylko w pierwszym wierszu.

Zarówno <th> jak i <ti> mogą zawierać atrybut colspan lub rowspan w celu połączenia kilku wierszy, kilku kolumn lub kilku wierszy i kolumn.

Dla komórek tabeli (<ti> i <th>) można ustawić wyrównanie do środka, do prawej lub do prawej za pomocą atrybutu align.

Listy

W celu utworzenia list numerowanych i nienumerowanych wykorzystujemy znane z XHTML znaczniki <ol>, <ul> i <li>. Listy mogą znajdować się wyłącznie wewnątrz <body> i <li> - co oczywiście oznacza, że listy można zagnieżdżać w innych listach. Warto pamiętać, że piszemy w XML - i dlatego trzeba zamknąć każdy znacznik, także te zawierające elementy list.

Można również tworzyć listy definicji (<dl>). Znaczniki <dt> (zawierający objaśniany termin) i <dd> (zawierający objaśnienie) nie mogą zawierać żadnych innych elementów blokowych takich jak np. paragrafy.

<dl>

Lista definicji zawierająca

<dt>

czyli pary definiowanych terminów

<dd>

oraz dane definicji

Poniższa lista skopiowana z w3.org pokazuje, że listy definicji mogą zawierać zarówno uporządkowane jak i nieuporządkowane listy. Nie może ona jednak zawierać innej listy definicji.

Składniki:

• 100g mąki
• 10g cukru
• 1 szklanka wody
• 2 jajka
• sól, pieprz

Przepis:

1. Dokładnie wymieszać suche składniki
2. Dodać składniki ciekłe
3. Mieszać przez 10 minut
4. Piec przez godzinę w 300 stopniach

Uwagi:

Można urozmaicić przepis dodając rodzynki

Odnośniki do treści wewnątrz tego samego dokumentu

Tworzenie odnośników to stosunkowo prosta i intuicyjna czynność. Można tworzyć odnośniki wskazujące na pierwszy rozdział wpisując <uri link="#doc_chap1">pierwszy rozdział</uri>. Można też wskazać drugą sekcję rozdziału pierwszego wpisując <uri link="#doc_chap1_sect2">druga sekcja rozdziału pierwszego</uri>. Aby odwołać się do trzeciej ilustracji w pierwszym rozdziale wystarczy wpisać <uri link="#doc_chap1_fig3">ilustracja 1.3</uri>. Może też stworzyć odnośnik odnośnik do drugiego listingu w drugim rozdziale wpisując <uri link="#doc_chap2_pre2">listing 2.2</uri>.

Niektóre teksty są zmieniane tak często, że "liczenie" obiektów może prowadzić do konieczności częstego poprawiania zepsutych odnośników. Aby sobie z tym poradzić, należy nadać nazwę elementowi <chapter>, <section> lub <tr>, używając atrybutu id, a następnie stworzyć odnośniki zawierający tę nazwą. Na przykład:

<chapter id="foo">
<title>To jest przykład!</title>
...
<p>
Więcej informacji można znaleźć w <uri link="#foo">przykładowym
rozdziale</uri>
</p>

Ostrzeżenia o martwych dokumentach

Dzięki parametrowi disclaimer można wyświetlić w opisie jedną z kilku uwag dotyczących jego treści. Te uwagi to:

• articles, używany do oznaczania artykułów pochodzących z innych serwisów
• draft, zaznaczający, że dokument jest jeszcze wersją roboczą i nie może być traktowany jako oficjalna dokumentacja
• oldbook, wykorzystywany do oznaczania starych wersji Podręcznika
• obsolete, wykorzystywany do oznaczenia dokumentu jako już nie aktualizowanego.

Zaznaczając dokument jako nieaktualny, możliwe jest też podanie odnośnika do nowej jego wersji. Służy do tego drugi atrybut, redirect. Dzięki temu użytkownik zostanie automatycznie przekierowany do nowego dokumentu.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide disclaimer="obsolete" redirect="/doc/pl/handbook/handbook-x86.xml">
<title>Instalacja Gentoo x86</title>

<author title="Autor">
...

FAQ

Dokumenty FAQ powinny zaczynać się od listy pytań wraz z odnośnikami do odpowiedzi. Tworzenie takiej listy ręcznie zajmuje dużo czasu i łatwo jest w niej popełnić błędy. Dlatego korzystamy z automatycznej metody jej generowania jaką jest znacznik faqindex, który zastępuje pierwszy rozdział dokumentu. Ma on taką samą strukturę jak znacznik chapter co pozwala na napisanie krótkiego wprowadzenia do całego dokumentu. Reszta tekstu powinna być podzielona na rozdziały (powinien być co najmniej jeden) zawierające sekcje, z których każda zawiera pytań wewnątrz znacznika title oraz odpowiedź wewnątrz body. Indeks pytań zostanie wygenerowany automatycznie.

Najłatwiej uczyć się na przykładach, dlatego polecamy przeczytanie naszego oficjalnego FAQ i porównanie wygenerowanego dokumentu z jego źródłem.

3.  Format podręcznika

Różnice pomiędzy Guide i Book

Dla dużej objętościowo dokumentacji, takiej jak Podręcznik instalacji Gentoo, potrzebny był nieco szerszy format. Dlatego powstało kompatybilne z GuideXML rozszerzenie pozwalające pisać dokumentację złożoną z wielu różnych plików.

Główny plik

Pierwszy krok to stworzenie "głównego" dokumentu. Nie będzie on zawierał właściwej treści, a jedynie odnośniki do konkretnych modułów dokumentacji. Składnia nie różni się bardzo od GuideXML:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book link="example.xml">
<title>Example Book Usage</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>
<date>...</date>

Jedyną różnicą jest wpisanie znacznika <book> zamiast <guide>. Jeśli chodzi o treść, nie dzielimy jej za pomocą znaczników <chapter>, tylko za pomocą znaczników <part>, które są ich odpowiednikiem zawierającym rozdziały naszego podręcznika.

<part>
<title>Część pierwsza</title>
<abstract>
  ...
</abstract>

(Definiowanie kilku rozdziałów)
</part>

Każda część posiada znaczniki <title> i <abstract>, które stanowią krótką jej charakterystykę.

Wewnątrz każdej z części można zadeklarować dowolną ilość znaczników <chapter>. Każdy rozdział musi być osobnym dokumentem. Od tego właśnie jest atrybut <include>, służący do dołączania zewnętrznych dokumentów.

<chapter>
<title>Chapter One</title>
<abstract>
  This is a small explanation on chapter one.
</abstract>

  <include href="path/to/chapter-one.xml"/>

</chapter>

Projektowanie poszczególnych rozdziałów

Zawartość każdego rozdziału Podręcznika powinna wyglądać następująco:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

<version>...</version>
<date>...</date>

(Define the several <section> and <subsection>)

</sections>

Wewnątrz każdego z rozdziałów może znajdować się kilka znaczników <section> (odpowiedników <chapter> z Guide) i <subsection> (odpowiedników <section> z Guide.

Każdy z rozdziałów powinien posiadać własne znaczniki daty i wersji. Przy przeglądaniu Podręcznika będzie wyświetlana najnowsza z dat w dokumentach.

4.  Zaawansowane opcje podręcznika

Wartości globalne

Czasami ta sama treść powtarza się wiele razy w różnych częściach podręcznika. Globalne operacje wyszukiwania i automatycznej zmiany takich treści są bardzo podatne na błędy. Poza tym możliwość dodania do podręcznika współdzielonych rozdziałów znacznie ułatwia zarządzanie nim.

Wartości globalne definiuje się w głównym pliku danego podręcznika. Są one wykorzystywane we wszystkich załączonych rozdziałach.

Definiowanie wartości jest stosunkowo proste, wystarczy dopisać znacznik <values> na początku głównego pliku podręcznika a następnie w serii znaczników <key> opisać wszystkie globalne zmienne jakich zamierza się używać. Atrybut id zawiera nazwę zmiennej a ich zawartość jest zarazem wartością zmiennej.

Poniżej znajduje się przykład ze zdefiniowanymi trzema zmiennymi:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>Example Book Usage</title>

<values>
 <key id="arch">x86</key>
 <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
 <key id="min-cd-size">57</key>
</values>

<author...>
  ...
</author>

...

Po zdefiniowaniu, wartości tych można używać w każdym rozdziale podręcznika w postaci <keyval id="key_id"/>. Atrybut id to nazwa zmiennej którą chcemy wstawić. Na przykład, zgodnie z naszym przykładem, <keyval id="min-cd-name"/> zostanie zastąpione przez "install-x86-minimal-2007.0-r1.iso".

<p>
The Minimal Installation CD is called <c><keyval id="min-cd-name"/></c>
and takes up only <keyval id="min-cd-size"/> MB of diskspace. You can use this
Installation CD to install Gentoo, but <e>only</e> with a working Internet
connection.
</p>

W celu ułatwienia pracy tłumaczom Podręcznika, korzystamy tylko z wartości których nie trzeba tłumaczyć. Np. definiujemy wartość min-cd-size jako 57 a nie 57 MB.

Elementy warunkowe

Czasami bywa tak, że wspólny rozdział w podręcznikach różni się tylko kilkoma szczegółami dla poszczególnych architektur. Nie chcemy dodawać niepotrzebnych informacji we wszystkich podręcznikach, dlatego stworzyliśmy możliwość wyświetlenia niektórych elementów wyłącznie w odpowiednim podręczniku. Można tak skonfigurować następujące znaczniki: <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> and <li>.

Warunek musi mieć postać wyrażenia XPATH, które zostanie przetworzone podczas wczytywania pliku XML. Jeśli jego wartość zostanie określona jako prawda (true), znacznik ten zostanie wyświetlony. Jeśli nie, nie zostanie wyświetlony. Warunek jest określony w atrybucie test.

Poniższy przykład wykorzystuje wartość arch zdefiniowaną w głównym pliku podręcznika do wyświetlenia pewnej treści.

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
This paragraph applies to both x86 and AMD64 architectures.
</p>

<p test="func:keyval('arch')='x86'">
This paragraph only applies to the x86 architecture.
</p>

<p test="func:keyval('arch')='AMD64'">
This paragraph only applies to the AMD64 architecture.
</p>

<p test="func:keyval('arch')='PPC'">
This paragraph will never be seen!
The whole body is skipped because of the first condition.
</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
This paragraph applies to the AMD64, PPC64 and PPC architectures because
the 'AMD64 PPC64' string does contain 'PPC'.
</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
This note only applies to the AMD64 and PPC64 architectures.
</note>

</body>

5.  Styl tworzenia dokumentów

Wprowadzenie

W związku z tym, że nad całą dokumentacją Gentoo pracuje wiele osób i tym, że każdy dokument jest edytowany przez wiele różnych osób, bardzo ważne jest określenie stylu tworzenia dokumentów. Pierwsza część rozdziału dotyczy rozmieszczania znaczników XML, druga mówi o tym w jaki sposób należy w dokumentacji umieszczać treść.

Oba podrozdziały znajdują się poniżej.

Wewnętrzny styl

Zaczynamy pisać w nowej linii po każdym znaczniku GuideXML z wyjątkiem: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>.

Puste linie umieszczamy po każdym znaczniku <body> (otwierającym) i przed każdym znacznikiem <chapter>, <p>, <table>, <author> (set), <pre>, <ul>, <ol>, <warn>, <note> i <impo> (otwierającym).

Zawijanie wierszy musi odbywać się po 80 znaku, z wyjątkiem zawartości znaczników <pre>. Można odejść od tej reguły tylko wtedy, gdy nie ma innego wyboru, na przykład gdy odnośnik jest dłuższy niż 80 znaków. W każdym wypadku program musi zawijać wiersz przy pierwszym wystąpieniu znaku niewidocznego. Warto również pilnować, by zawartość <pre> była zawijana po 80 znaku. Znacznie ułatwia to życie użytkownikom pracującym w konsoli.

Pisać od akapitów nie można nigdzie z wyjątkiem konstrukcji w XML wewnątrz znaczników <tr> (z <table>), <ul>, <ol>, <dl> i <author>. Jeśli już korzysta się z akapitów, każdy z nich musi rozpoczynać się dwoma spacjami. Nie wolno używać tabulatorów ani większej ilości spacji. Tabulatory są zakazane w składni GuideXML.

W przypadku, gdy zachodzi konieczność zawinięcia wiersza wewnątrz <ti>, <th>, <li> lub <dd>, należy skorzystać z wcięć dla umieszczenia w nich treści.

Przykład składni:

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>This is an example for indentation</ti>
  <ti>
    In case text cannot be shown within an 80-character wide line, you
    must use indentation if the parent tag allows it
  </ti>
</tr>
</table>

<ul>
  <li>First option</li>
  <li>Second option</li>
</ul>

Kiedy podaje się atrybuty, nie wolno pisać spacji wokół znaku "=". Przykład:

Źle:     <pre caption = "Atrybuty">
Dobrze:     <pre caption="Atrybuty">

Styl zewnętrzny

Wewnątrz tabel (<table>) i list (<ul>, <ol>) i <dl> nie wolno używać kropek, chyba, że wystąpi tam kilka zdań. W takim wypadku każde z nich musi kończyć się kropką.

Każde zdanie, włączając w to te wewnątrz tabel i list, musi zaczynać się wielką literą.

<ul>
  <li>Bez kropki</li>
  <li>Z kropką. Kilka zdań, prawda?</li>
</ul>

Każdy listing musi posiadać nagłówek (caption).

Warto nadawać nazwy odnośnikom (<uri>) za pomocą atrybutu link. Lepiej pisać Forum Gentoo niż http://forums.gentoo.org.

Komentarze wewnątrz <pre> należy umieszczać wewnątrz znacznika <comment>. Przed komentarzami w plikach winien znajdować się znak komentarza (# w bashu i wielu innych, // w C i tak dalej). Komentarz musi znajdować się przed wpisem, którego dotyczy.

(Należy zastąpić "rane" nazwą użytkownika)
# id rane

6.  Zasoby

Pora zacząć pisać

Składnia GuideXML została zaprojektowana tak, aby była możliwie łatwa do przyswojenia, a jej nauka nie zajmowała więcej czasu niż pisanie dokumentów. Dzięki takiemu narzędziu wielu deweloperów, którzy wcześniej nie chcieli pisać dokumentacji dla Gentoo, teraz może ją tworzyć w prosty i przyjemny sposób. Kilka ciekawych informacji dotyczących praktycznej części procesu tworzenia dokumentów znajduje się w tekście Documentation Development Tips & Tricks. Wszelkie pytania dotyczące składni GuideXML można kierować na Listę dyskusyjną gentoo-doc.

Materiał udostępniany na podstawie licencji Creative Commons - Attribution / Share Alike.