Stylebook is a way to convert a set of XML files
into a proper web site with consistent navigation and layout.
The XML data is converted to HTML files in a batch
process that also generates index pages and other
data. The resulting set of HTML pages is independant
of the XML source and can be mirrored easily.
Stylebook was developed by the Apache Software Foundation
(
This article describes how to write an article using Stylebook, or more specifically a modified and extended version of it that is used by C-Scene. From now on, we use the name C-Style to refer to that variation of Stylebook.
When writing articles in XML, there are two main things to keep in mind.
!!! Attribute quotes, closing tags, <tag/> shortcut, case sensitivity, XHTML.
A XML document that conforms to a DTD is called a valid document. Every valid document is also well-formed.
A stylebook document is made of of nested sections, which can be
up to four levels deep. Sections can contain, besides sections of the next level,
the following blocks:
<p>, <note>, <pre>,
<ul>, <ol>, <gloss>,
<table>, <source>, and <anchor>.
Those blocks are described below.
Here is an example of a document using all four levels:
This is a paragraph.
This is a paragraph.
Paragraphs are the containers for the normal text of an article. Besides text, paragraphs can contain hyperlinks and things like emphasis. Please note that to start a list or table, you have to close the current paragraph.
To force a line break within a pargraph, you can use <br/>.
Here we go to the next line without closing the paragraph tag.
<br/> should be used sparingly.
gloss, label, item
table, tr, tn, th, td
| header 1 / 2 | header 3 | header 4 | ||
|---|---|---|---|---|
| header a | data a1 | data a2 | data a3 / a4 | |
| header b / c | data b1 | data b2 | data b4 / c4 | |
| data c1 | data c2 / c3 / d2 / d3 | |||
| header d | data d1 | data d4 | ||
Stylebook provides two tags to mark up source, one for
inline code fragments and one for code listings.
Here is an example of code display:
Note that source code can be embedded directly into XML documents, without the need to encode special chars like "<" to "<", by using an XML CDATA section. The above listing was done using this XML code:
Normal text can be made to stand out in several ways.
You can emphasize by using <em>, and you can make an even
stronger emphasis by using <strong>.
References to external sources like books should
be marked up by using <ref>.
Finally, as was already mentioned, you can use <code> for inline
source code fragments, like variable names
and function() calls.
anchor, link, jump, resource-ref, human-resource-ref
Clicking here you will be transported to the
Readme file. This has been achieved with
<link idref="readme">here</link>.
Note that the idref="..." MUST refer to an
id="..." specified in the book file.
Clicking here you will be transported to the
end of this file. This has been achieved with
<link anchor="bottom">here</link>
and inserting <anchor name="bottom"/> at the end of
this file.
Clicking <jump href="mailto:pier@apache.org">here</jump>.
The jump tag is used whenever you cannot use link, since the target is
outside stylebook domain.
Clicking here you will be
transported to the end of the Sections file. This has been
achieved with
<link idref="sections" anchor="bottom">here</link>
and inserting <anchor name="bottom"/> at the end of
the target file (sections.xml).
Last, but not least, inserting here <img src="logo.gif"/>
we see an image appear in the target html. I know I sound stupid but I
don't know what to write and I need to keep this long...
<jump href="mailto:cscene@cscene.org"/> element,
clicking on the image you will be able to send me mail.
Articles are a wrapper for Stylebook documents... article, copyright, s1, html
The following tags described above are additions to C-Style
and are not found in Stylebook:
.
]]>
Within <source>, the use of <anchor> and <link> is allowed,
so that you can hyperlink into longer code listings from the article text.
Another addition is the <article> wrapper for Stylebook documents,
which have the root tag <s1>.
The use of <pre> within documents is deprecated, it was mainly
added to support the use of <HTML> within <article>.
In general, like all XML document types, Stylebook strives to add semantic information to the document's data. Thus, you don't find those HTML tags that determine mere layout, instead of specifying what the text in those tags means.
By providing only those tags that are really needed to convey information to other people, Stylebook is easier to learn by someone who is not fluent in HTML (and those people do exist). On the other hand, someone who knows HTML will have no problem to use Stylebook, since most elements are the same as in HTML - there is just fewer of them.
Apache Software Foundation, The Apache XML Project.
Simon St. Laurent, XML - A Primer.
1998, MIS:Press, 348 pages, ISBN 1-55828-592-X.