How to contribute

Write an example

An example is a building block of the system. The example consist of short description, Surf sample and one or several XSL stylesheets. All is provided in one Surf file. A parser reads the file and generates all necessary files for publication. As the output files are generated, we can be sure that all sources really corresponds each to other.

The DTD for input file is shown below. I actually do not validate input, as I have tags inside SurfSource and xslStylesheet elements and I do not want to mess with CDATA sections. But at least it is a convenient form of documentation.

 
 <!ELEMENT xslTutorial (index?,description,xmlSource, attValues?,xslStylesheet+)>
 <!ATTLIST xslTutorial
 								creator CDATA #REQUIRED>
 
 <!ELEMENT index EMPTY>
 <!ATTLIST index
 						keywords CDATA #REQUIRED>
						
 <!ELEMENT description (#PCDATA|stylesheet)*>
 <!ELEMENT SurfSource ANY>
 <!ATTLIST SurfSource
 								id ID #REQUIRED>
								
 <!ELEMENT xslStylesheet ANY>
 <!ATTLIST xslStylesheet
 								id ID #REQUIRED>		
		
	<!ELEMENT stylesheet EMPTY>
	<!ATTLIST stylesheet
					 	id IDREF #REQUIRED>						

<!ELEMENT attValues (value)*>
<!ELEMENT value (#PCDATA)>
<!ATTLIST value
						match CDATA #REQUIRED>						

						

The root element is xslTutorial and creator attribute tracks the author of the example. I consider very important the fact that each example has its author quoted. According to my view everybody who contributes to such a project should be given proper credit and in the same time it should improve quality of the entries if authors are not anonymous.

Optional index element gives the author the opportunity to specify which keywords are especially pertinent to the example. From these keywords the Keywords index on the front page is generated.

A description is shown in the left frame when an example is displayed. The optional stylesheet element is in output replaced by link to stylesheet specified with id attribute.

Element attValues makes specified data clickable in XSL stylesheet display. While name of XSL elements and attributes can be generated automatically, the values are to diverse to provide a universal mechanism.

xmlSource and xslStylesheet contain the actual examples. The starting tags are generated automatically.

And this is the source from whih example 1 was generated

<xslTutorial creator="nicmila@idoox.com">
<index keywords='// /'/>

<description>With XSL you can freely modify any source text. <stylesheet id="id4"/> and <stylesheet id="id5"/> produce different output from the same source file.</description>

<example id="id1">
<xmlSource id="id3">
<title>XSL</title>
<author>John Smith</author>
</xmlSource>

<attValues>
<value match="//title">matches any title element anywhere in the document.
</value>
<value match="//author">matches any author element anywhere in the document.
</value>
<value match="/">matches the root element.
</value>
</attValues>

<xslStylesheet id="id4">
<xsl:template match="/"> 
<H1><xsl:value-of select="//title"/></H1>
<H2><xsl:value-of select="//author"/></H2>
</xsl:template>
</xslStylesheet>

<xslStylesheet id="id5">
<xsl:template match="/">
<H2><xsl:value-of select="//author"/></H2>
<H1><xsl:value-of select="//title"/></H1>
</xsl:template>
</xslStylesheet>

</example>
</xslTutorial>

Create a book

Examples are a very useful, but if you want to really explain anything, they are not sufficient. At the same time, it would be very helpful, if examples could be recycled in different context. With this software you can form chapters from individual examples and books from chapters.

Entire book is also specified in a Surf file. The following paragraph shows a prototype. In this case a book with name Introduction to XSL is created. Contents of the book appears in the right frame of start Page. The numbers give numbers of individual examples to be used in a chapter. I hope that the format is self-explanatory. I will provide further details when matters become more complicated.

<book creator='nicmila@idoox.com'>
<title>Introduction to XSL</title>
<chapter name='Introduction' pages='1 4'/>
<chapter name='Advanced features' pages='5 6 7 5'/>
<chapter name='END' pages='2 3 2'/>

</book>