The guideXML syntax is lightweight yet expressive, so that it is easy to learn yet also provides all the features we need for the creation of web documentation. The number of tags is kept to a minimum -- just those we need. This makes it easy to transform guide into other formats, such as DocBook XML/SGML or web-ready HTML.
The goal is to make it easy to create and transform guideXML documents.
Let's start learning the GuideXML syntax. We'll start with the the initial tags used in a GuideXML document:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header$ --> <guide lang="en"> <title>Gentoo Documentation Guide</title> <author title="Author"> <mail link="email@example.com">Your Name</mail> </author> <abstract> This guide shows you how to compose web documentation using our new lightweight Gentoo GuideXML syntax. This syntax is the official format for Gentoo web documentation, and this document itself was created using GuideXML. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See https://creativecommons.org/licenses/by-sa/3.0 --> <license version="3.0"/> <version>1</version> <date>2011-11-29</date>
On the first lines, we see the requisite tag that identifies this as an XML
document and specifies its DTD. The
<!-- $Header$ --> line
will be automatically modified by the CVS server and helps to track revisions.
Next, there's a
<guide> tag -- the entire guide document is
enclosed within a
<guide> </guide> pair.
lang attribute should be used to specify the language code of your
document. It is used to format the date and insert strings like "Note",
"Content", etc. in the specified language. The default is English.
Next, there's a
<title> tag, used to set the title for the entire
Then, we come to the
<author> tags, which contain information
about the various authors of the document. Each
allows for an optional
title element, used to specify the author's
relationship to the document (author, co-author, editor, etc.). In this
particular example, the authors' names are enclosed in another tag -- a
<mail> tag, used to specify an email address for this particular
<mail> tag is optional and can be omitted, and at
<author> element is required per guide document.
Next, we come to the
<date> tags, used to specify a summary of the document, the
current version number, and the current version date (in YYYY-MM-DD format)
respectively. Dates that are invalid or not in the YYYY-MM-DD format will
appear verbatim in the rendered document.
This sums up the tags that should appear at the beginning of a guide document.
<mail> tags, these tags
shouldn't appear anywhere else except immediately inside the
<guide> tag, and for consistency it's recommended (but not
required) that these tags appear before the content of the document.
Finally we have the
<license version="3.0"/> tag, used to publish
the document under the Creative
Commons - Attribution / Share Alike license as required by the Documentation Policy. Historically,
<license /> was used, which denoted the 2.5 version of the
license. This is still accepted/allowed.
Once the initial tags have been specified, you're ready to start adding the
structural elements of the document. Guide documents are divided into
chapters, and each chapter can hold one or more sections. Every chapter and
section has a title. Here's an example chapter with a single section,
consisting of a paragraph. If you append this XML to the XML in the previous excerpt and append a
</guide> to the end of the file, you'll have a valid (if minimal)
<chapter> <title>This is my chapter</title> <section> <title>This is section one of my chapter</title> <body> <p> This is the actual text content of my section. </p> </body> </section> </chapter>
Above, I set the chapter title by adding a child
element to the
<chapter> element. Then, I created a section by
<section> element. If you look inside the
<section> element, you'll see that it has two child elements -- a
<title> and a
<body>. While the
is nothing new, the
<body> is -- it contains the actual text
content of this particular section. We'll look at the tags that are allowed
<body> element in a bit.
<guide>element must contain at least one
<chapter>must contain at least one
<section>elements and a
<section>element must contain at least one
Now, it's time to learn how to mark up actual content. Here's the XML code for
<p> This is a paragraph. <path>/etc/passwd</path> is a file. <uri>https://forums.gentoo.org</uri> is my favorite website. Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. </p> <pre caption="Code Sample"> This is text output or code. # <i>this is user input</i> Make HTML/XML easier to read by using selective emphasis: <foo><i>bar</i></foo> </pre> <note> This is a note. </note> <warn> This is a warning. </warn> <impo> This is important. </impo>
Now, here's how the
<body> element above is rendered:
This is a paragraph. /etc/passwd is a file.
https://forums.gentoo.org is my favorite web site.
ls if you feel like it. I really want to go to sleep now.
This is text output or code. # this is user input Make HTML/XML easier to read by using selective emphasis: <foo>bar</foo>
We introduced a lot of new tags in the previous section -- here's what you need
to know. The
<pre> (code block),
<warn> (warning) and
(important) tags all can contain one or more lines of text. Besides the
<dl> elements (which we'll cover in just a bit), these are the
only tags that should appear immediately inside a
Another thing -- these tags should not be stacked -- in other words,
don't put a
<note> element inside a
<p> element. As
you might guess, the
<pre> element preserves its whitespace
exactly, making it well-suited for code excerpts. You must name the
<pre> tag with a
<pre caption="Output of uptime"> # <i>uptime</i> 16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 </pre>
<c> element is used to mark up a command or user
input. Think of
<c> as a way to alert the reader to something
that they can type in that will perform some kind of action. For example, all
the XML tags displayed in this document are enclosed in a
element because they represent something that the user could type in that is
not a path. By using
<c> elements, you'll help your readers
quickly identify commands that they need to type in. Also, because
<c> elements are already offset from regular text, it is rarely
necessary to surround user input with double-quotes. For example, don't
refer to a "
<c>" element like I did in this sentence. Avoiding
the use of unnecessary double-quotes makes a document more readable -- and
As you might have guessed,
<b> is used to boldface some
<e> is used to apply emphasis to a word or phrase; for example:
I really should use semicolons more often. As you can see, this text is
offset from the regular paragraph type for emphasis. This helps to give your
prose more punch!
<uri> tag is used to point to files/locations on the Internet.
It has two forms -- the first can be used when you want to have the actual URI
displayed in the body text, such as this link to
https://forums.gentoo.org/. To create this link, I typed
<uri>https://forums.gentoo.org/</uri>. The alternate form is
when you want to associate a URI with some other text -- for example, the Gentoo Forums. To create
this link, I typed
Gentoo Forums</uri>. You don't need to write
https://www.gentoo.org/ to link to other parts of the Gentoo web site.
For instance, a link to the documentation main index
should be simply
<uri link="/doc/en/index.xml">documentation main
index</uri>. You can even omit
index.xml when you link to a
directory index, e.g.
<uri link="/doc/en/">documentation main
index</uri>. Leaving the trailing slash saves an extra HTTP request.
Here's how to insert a figure into a document --
link="mygfx.png" short="my picture" caption="my favorite picture of all
link attribute points to the actual graphic image,
short attribute specifies a short description (currently used for
the image's HTML
alt attribute), and a caption. Not too difficult
:) We also support the standard HTML-style <img src="foo.gif"/> tag
for adding images without captions, borders, etc.
GuideXML supports a simplified table syntax similar to that of HTML. To start a
table, use a
<table> tag. Start a row with a
tag. However, for inserting actual table data, we don't support the HTML
<td> tag; instead, use the
<th> if you are inserting a
<ti> if you are inserting a normal informational
block. You can use a
<th> anywhere you can use a
-- there's no requirement that
<th> elements appear only in the
Besides, both table headers (
<th>) and table items
<ti>) accept the
rowspan attributes to
span their content across rows, columns or both.
Furthermore, table cells (
<th>) can be
right-aligned, left-aligned or centered with the
|This title spans 4 columns|
|This title spans 6 rows||Item A1||Item A2||Item A3|
|Item B1||Blocky 2x2 title|
|Item E1..F1||Item E2..E3|
To create ordered or unordered lists, simply use the XHTML-style
<li> tags. Lists may only
appear inside the
<li> tags which means
that you can have lists inside lists. Don't forget that you are writing XML and
that you must close all tags including list items unlike in HTML.
GuideXML makes it really easy to reference other parts of the document using
hyperlinks. You can create a link pointing to Chapter
One by typing
One</uri>. To point to section two of
Chapter One, type
<uri link="#doc_chap1_sect2">section two of
Chapter One</uri>. To refer to figure 3 in chapter 1, type
<uri link="#doc_chap1_fig3">figure 1.3</uri>. Or, to refer
to code listing 2 in chapter 2, type
<uri link="#doc_chap2_pre2">code listing 2.2</uri>.
Since all Gentoo Documentation is a joint effort and several people will most likely change existing documentation, a coding style is needed. A coding style contains two sections. The first one is regarding internal coding - how the XML-tags are placed. The second one is regarding the content - how not to confuse the reader.
Both sections are described next.
Newlines must be placed immediately after every
GuideXML-tag (both opening as closing), except for:
Blank lines must be placed immediately after every
<body> (opening tag only) and before every
<impo> (opening tags only).
Word-wrapping must be applied at 80 characters except inside
<pre>. You may only deviate from this rule when there is no other
choice (for instance when a URL exceeds the maximum amount of characters). The
editor must then wrap whenever the first whitespace occurs. You should try to
keep the rendered content of
<pre> elements within 80
columns to help console users.
Indentation may not be used, except with the XML-constructs of which the
parent XML-tags are
<author>. If indentation is used, it must be two spaces for
each indentation. That means no tabs and not more spaces.
Besides, tabs are not allowed in GuideXML documents.
In case word-wrapping happens in
<dd> constructs, indentation must be used for
An example for indentation is:
<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>
Attributes may not have spaces in between the attribute, the "=" mark, and the attribute value. As an example:
Wrong : <pre caption = "Attributes"> Correct: <pre caption="Attributes">
Inside tables (
<table>) and listings (
<dl>, periods (".") should not be used
unless multiple sentences are used. In that case, every sentence should end
with a period (or other reading marks).
Every sentence, including those inside tables and listings, should start with a capital letter.
<ul> <li>No period</li> <li>With period. Multiple sentences, remember?</li> </ul>
Code Listings should always have a
GuideXML has been specially designed to be "lean and mean" so that developers can spend more time writing documentation and less time learning the actual XML syntax. Hopefully, this will allow developers who aren't unusually "doc-savvy" to start writing quality Gentoo documentation. You might be interested in our Documentation Development Tips & Tricks. If you'd like to help (or have any questions about GuideXML), please post a message to the gentoo-doc mailing list stating what you'd like to tackle. Have fun!