Algorithms Books Patterns Graphics Miscellaneous UNIX Web & XML Windows
Feedback FAQs Changes Submissions
|
C-Scene
Issues 1..9
Authors
Algorithms Books Patterns Graphics Miscellaneous UNIX Web & XML Windows Feedback FAQs Changes Submissions |
by Jürgen Hermann
last updated 2001/08/02
(version 1.1.1.1)
also available as XML
This article is work in progress and not yet finished!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 (http://www.apache.org/).
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:
<s1 title="Outermost section">
<p>This is a paragraph.</p>
<s2 title="This is an <s2 ...> section">
<s3 title="This is an <s3 ...> section">
<s4 title="This is an <s4 ...> section">
<p>This is a paragraph.</p>
</s4>
</s3>
</s2>
</s1>
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 | ||
A note gets special treatment. It should be used for things
that you want to stand out.
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:
Source 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:
<source><![CDATA[ Source display ]]></source>
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 here you will be able
to send me E-Mail. This can be done inserting
<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...
Inserting here a different image, but this time surrounded with
a <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:
<strong> <small> <pre>.
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.
http://xml.apache.org/
Simon St. Laurent, XML - A Primer.
1998, MIS:Press, 348 pages, ISBN 1-55828-592-X.
This article is Copyright © 2000 by C-Scene. All Rights Reserved.
Part of the material presented here is based on the Stylebook documentation,
Copyright © 1999-2000 by Apache Software Foundation.