Introduction

The st-project is a simple XSL-stylesheet for converting some texts into PDF-files. It tooks a structured XML-file as input and produces with the help of a Formatting Objects Processor a PDF-file. The st-stylesheet tries to support the most common used elements of modern text formatting.
It was the first time that I got in touch with FO and I had a lot of fun developing st. That it can be used for several arts of text is shown on the examples section on the webpagehttp://www.thomas-zastrow.de/st/. Certainly, there are still a lot things to do.
Please feel free to play around with the script. If you have more ideas, critics, suggestions or whatever, don't hesitate to contact me. It would be glad if somebody else will help me with the further development.

Principles

The input for the st-stylesheet is a simple XML-format. Where it is possible, the syntax of this XML-dialect is just HTML. For example, you can add a linebreak to your text with the XML-tag <br />. It was not always possible to use HTML-syntax: in some cases, the specific requirements of scientific texts can not be represented with pure HTML-codes. In this cases, new tags are implemented.
The script will support two modes:

• A simple mode: this mode contains just XML-elements without any attributes. For example, if you want to make something green, around it with the tag <green>
• An advanced mode: The tags in the XML-file can also contain attributes. With the use of them, it will be possible to take more control over the layout. For example, a <color> - tag will have an attribute value which can contain every RGB-value.

Basics

From the text to the finishing PDF-file, it's a two-way process. At first, with the help of a XSL-processor and the st.xsl-file, the XML-file is converted into a FO-file. Than the FO-file is transformed to a PDF-file, using a FO-processor.
/home/tom/a-daten/st/doc/graphic1.svg
Beginning with version 0.23, the developement of the st scripts concentrates completly on the Apache FOP as FO processor. There are some functions which are only working with Apache FOP, for example the integration of MathML formulars. You will need version 0.94 or above of the Apache FOP, former versions will not work! Most functions will still work with other processors - but I can't give a guarantee, also because I didn't test the st scripts with other processors. It is recommended that you use the Xalan-XSL-processorhttp://xml.apache.org/xalan-j/ and FOP, the FO-processor of the Apache-projecthttp://xmlgraphics.apache.org/fop/. If you use the Apache FOP - and this is highly recommended! - you don't need any separate software because the Apache FOP has everything on board. Just make sure that Apache FOP works and then use the fop - executable in the root-directory of FOP with this arguments: fop -xml YourXMLFile.xml -xsl st.xsl -pdf YourPDF.pdf This command produces directly a PDF-file. If you want to take a look at the FO-file, use: fop -xml YourXMLFile.xml -xsl st.xsl -foout YourFOFile.fo

The XML-File

The XML-file is just well-formed: At the moment, it is lacking a DTD, XML-schema or something for validating. While the development of the st-stylesheet is going on, it seems not to be helpful to validate the XML-file. When the project reaches a definite status, it would be also useful to validate it.

The XML-Frame

As every XML-file, it starts with the line: <?xml version="1.0" encoding="UTF-8"?> The root-element is named text: <text>
Your content
</text>

The meta-tags

With the meta tags, you can specify some general settings of the document. At the moment, all of the meta tags are optional. Perhaps this will change in the future.

Font Settings

• <basefont>: this contains the standard-font-family for the document. Possible values: serif, sans-serif, monospace. It depends which fonts are avaulable in your FO-processor. If no basfont is given, the most FO-processors uses a sans-serife font.
• <color>: defines the standard-color of the document
• <highlightcolor>: some elements in the text are highlighted, for example parts of tables, the exp-part of a p-tag, blocks, and, optional, the headers. This defines the color of this highlighting. In this document, it was set to lightgrey.
• <highlightheaders>: if this tag is given, also the headers are highlighted in the highlightcolor-color.
• <basefontsize>: the size of the standard-font. Titles are also calculated with this size as basis
• <headerfont>: this tag specifies a font which is used insetad of the standard font in headers
• <bookmarks>: If this tag is set, the resulting PDF file will contain bookmarks for navigating through the document

Page Settings

• <pagesize>: defines the size of the pages. Nested into pagesize, the tags height and width are taking the values. For example, a page with the size 15 x 15 cm: <pagesize>
<height>15cm</height>
<width>15cm</width>
</pagesize>
If no pagesize is defined, DIN-A-4 is used.
• <author>: contains the author of the text
• <maintitle>: the title of your text
• <affiliation>: will be displayed on the title page below the autor's name
• <adress>: will be displayed in the upper left corner of the title page. All text formattings are allowed

The Starting Pages

• <titlepage>: a page with the author's name and the title
• <toc>: a table of content

The Content

Please notice: from version 0.1 to 0.2, the biggest change was the turnaround from p- and content-tags. A p-tag in version 0.1 is now a content-tag in 0.2, and a content tag in 0.1 is now a p tag! The content <content> is the central element of the text. It is the main structure for your text. It has two child-elements: <h*> and <p>. Their can be an arbitrary number of <content>-elements under the text-node.
The <h*> - element has two functions. First, it's content is the title of the chapter. And second, the * stands for a number between 1 and 4. This is the depth-level of the disposition.
The p-tags takes the content of a paragraph. There are an arbitrary number of p-tags within the content-tag possible. Here all elements of text-formatting are possible. <p> and <h*> tags are possible everywhere in the document. But just nesting them into the <content> - tag ensures that the structure of the document is intact: so, better use them only within the <content> tag! This is an example of a chapter on the highest level (h1): <content>
<h1>Chapter one</h1>
<p>This is the text of chapter one.</p>
</content> As you can see, the <p>- and <h*>-tags are similiar to the p- and h-tags in HTML. There's a special kind of the p-tag. If you add an exp-attribute to it, the content of this attribute is used to add a small column beside the original content with a background in the highlight color: <p exp="This is an explanation">
The content of p [....]
<p> The result:

The content of content. I'll add some more sensless text to this element so that you can see how the content of the content-tag and the exp-attribute will aligned.

Text-Formatting

Within the p-tag, st supports some kinds of common used text-formatting. Just put these tags around the text you would like to emphasize:

• <i>: italic text
• <b>: bold text
• <code>: monospace-font
• <red>, <green> or <blue>: a red, green or blue text

Special characters

XML and all the technologies around it are ready to use unicode. This means that it isn't necessary to quote special charcters in a comlicated way - just use an unicode-able texteditor and type as you like. Some examples: € @ Ää Üü Öö ß © ¾ ¶ † Please notice that it depends on the font you are using which special characters are available!

The color-schema

Additional to the three simple colors defined as red, green and blue, you can define a generic RGB-color in the color-tag: <color value="rgb(100,100,100)">Grey Text</color> This will result in: Grey Text

Breaks

If you need an explicit break, there are three possibilities:

• <br/>: same as in HTML, one carriage-return
• <np/>: simulates two carriage-returns which results in a blank line
• <pagebreak/>: break to the next page

Lists

Bullet-lists are as simple as in HTML. <li>-elements are surrounded by <ul>-tags: <ul>
<li>Your item</li>
<li>Another item</li>
</ul>
The result:

• Your item
• Another item

Footnotes

Footnotes are surrounded with a <fn> - tag. Just put them directly on the text where you need a footnote<fn>This is a footnote</fn>This is a footnote.

Images

Images are included with the img-tag: <img>images/logo.jpg</img> This includes the image logo.jpg from the images-directory. It's also possible to use images from other locations on your harddrive, just use the same conventions as in HTML. Also, an image can be loaded over the internet from an URL. /home/tom/a-daten/st/doc/images/logo.jpg The caption-attribute takes a title for the page, the align-attribute aligns the image. If you specify an attribute scale with a %-value, the image will be scaled proportional to that value. If an attribute width is specified, the image will be scaled proportional to that width. For example, with the width-attribute set to the page width minus the left and right border, the image will be scaled over the whole page width. Be careful: Don't use the attributes scale and width together! With the attribute align, the image can be aligned to left, center or right. /home/tom/a-daten/st/doc/images/logo.jpg When including images into st, there are some things to noticeYou can find more information about supported graphic-formats on
http://xmlgraphics.apache.org/fop/0.20.5/graphics.html:

• Images have to be always a resolution of 72 dpi
• PNGs are not supported without the help of an external library

Borders

A text can have a border with the <border> - Tag: <border>
This text-block has a border!
</border>
This text-block has a border! The border-tag has also a style tag: style="solid" And a color-tag: style="solid", color="red" There are some special rectangulars: an exclamation- and a question mark. If you use a <exmark> respective a <qumark> - tag, the enclosed text will appear in a box with ! / ? - mark on the left side: Here is something important ...! And here something questionable ...?

Blocks

A block can be used to highlight a part of your text, for example code-listings or something else. It has an own title which will not appear in the TOC. The background is grey and it uses an other font.
Surround a block with the tag <block>. The title is marked with <bh>: <block>
<bh>Block-Headline</bh>
This is a block. You can use everything else in a block, for example a list:
<ul>
<li>An item</li>
</ul>
</block>
This results in: Block-Headline This is a block. You can use everything else in a block, for example a list:

• An item

Tables

Especially tables are under a permanent developement. So, it could be that the design of tables can change from day to day! Tables are working nearly the same as in HTML: The table-tag sorrounds the complete table. Every row has a tr-tag and within the row-tags a td-tag defines a cell.
Here are some kinds of attributs are used:

• width="value": The attribute width of the table-tag defines the width of the table.
• style="header": a <tr> - tag can marked as a header with this attribute. The resulting row is formatted as a table-header
• align="left, center or align": within a <td> - tag, this defines the alingment of that cell
• color="value": a table-cell can get an explicit color within the color-tag
• font-size="value": here you can specify a font-size for the table

Mathematic Formulars

The integration of MathML formulars is a special function of the Apache FOP version 0.94, together with the JEuclid library. It will not work with former versions of the FOP! Additionally to the FOP 0.94, you need the JEuclid library installed as Plugin in the FOP. Please find more information on JEuclid and how to integrate it into the Apache FOP on the JEuclid Homepage under http://jeuclid.sourceforge.net/ Here is a very short guide to install JEuclid as FOP plugin:

• Download JEuclid.
• Unzip it.
• Copy jeuclid-core-x.x.x.jar and jeuclid-fop-x.x.x.jar into the lib directory of the FOP.

Interactive PDF features - Links

Links are an interactive feature of PDF files. They will just work in PDF files. In the st-files, links are implemented in a HTML-like way: an a-tag with a href-attribute will expand to an interactive link in the PDF file. For example, <a href="http://www.thomas-zastrow.de">
Homepage of Thomas Zastrow
</a> will expand to: Homepage of Thomas Zastrow

Links

You have downloaded the st scripts from: www.thomas-zastrow.de/st

The Apache FOP can be found: http://xmlgraphics.apache.org/fop/

Extensible Stylesheet Language (XSL): http://www.w3.org/TR/xsl11/

Contact

Please use my homepage to contact me: http://www.thomas-zastrow.de/st