The XSLT processor xsltproc is probably already installed with the libxslt package. http://xmlsoft.org/XSLT/

To call xsltproc xsltproc<my>.xml when the stylesheet is referenced inside the xml file. The output appears on the screen, to put it into a file do simply (or add alternatively the -o option):

xsltproc <my>.xml > <my>.html

And to call a stylesheet on the command line

xsltproc<my>.xsl <my>.xml

To write into a file and ignore downloading the dtd:

xsltproc --novalid -o<output-file>.html <stylesheet>.xsl <input-xml-file>.xml

Docbook stylesheets have lot of options. An example that uses a xml docbook file and stylesheet and produces multiple html files with he file name coming from the <sect1 id=<filename>> tag, this is done by passing some variables modifying the defaults to the stylesheet using --stringparam:

xsltproc --stringparam use.id.as.filename 1 /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl<name>.xml

Or to put the resulting html files somewhere else:

xsltproc \

--stringparam use.id.as.filename 1 \

--stringparam base.dir /<destination directory>/ \

/usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl <filename>.xml

To see what happens some options can be added:

--profile shows what matched in a sequence

--load-trace shows what files got loaded

--noout can be added when no file should be created and no output is desired

It uses java and is therefore much slower than xsltproc. It is well documented and used in other tools. It and has also a gui kernow: https://sourceforge.net/projects/kernowforsaxon/

To call saxon with a hello.xml that contains the link to hello.xsl:

saxon8 -a -o hello.html hello.xml

Or when having all 3 files separated

saxon8 -o hello.html hello.xml hello.xsl

Many different Xslt processors are around as:

The biggest problem is to install a working version of eclipse and its (eclipse web developer tools) WTP. Very many combinations with already installed plug-ins and versions exist. It is not very important what version gets installed but it is important that XSLT support is included or gets otherwise installed manually using eclipses GUI. See http://wiki.eclipse.org/XSLT_Project

As usual in eclipse a project need to be created that puts at the minimum an empty subdirectory in the workplace (eclipse directory ~/eclipse-workspace). A good start is opening in the project explorer XMLExample. The files of this projects are under ~/eclipse-workspace/XMLExample.

Then add a copy of your xsl and xml files and do not forget if required dtd files underneath ~/eclipse-workspace/<some dir> using import and creating a new directory.

xsl file can be run where a xml file (from the eclipse-workspace) is required to be passed.

However it is best to create a XSL configuration with all the settings. This XSL configuration can then be run and debugged with some mouse clicks. In this configuration the output file can be configured to be html and then the standard web browser opens it.

Eclipse has some perspectives, those are basically view configurations, so when debugging the Debug perspective opens. Perspectives can be changed under Window > Perspective

When debugging with the not debug capable default JRE XSLT processor a request pops up to switch to Xalan. See http://wiki.eclipse.org/XSLT_Project/UserGuide/Launching.

Figure 11.4. xslt debugging with eclipse

Instead of using a debugger you can generate messages (similar as printf when developing a c program).

Text that ends up in the output file

<xsl:text> 
Hello 
</xsl:text>   

Or add it into a template to create a function:

<xsl:template name="hello">
  <xsl:text> Hello </xsl:text>
</xsl:template>   

And then call it from anywhere you want as:

<xsl:call-template name="hello"/>

More advanced is the use of message see https://www.ibm.com/developerworks/xml/library/x-debugxs/index.html

Text that ends up in the console

<xsl:message>
  some text
</xsl:message>

Some item

<xsl:message>
  <xsl:copy-of select="$<what to look at>"/>
</xsl:message>

terminate here

<xsl:message terminate="yes" /> 

The xsl style sheets are xml and start therefore also with the xml version used and the character encoding

<?xml version="1.0" encoding="ISO-8859-1"?> 

The next line the xsl prefix for the tag stylesheet and adds attributes for version and xmlns (namespace).

<xsl:stylesheet 
  version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 
    "
    " 
</xsl:stylesheet>

Finally the stylesheet closes with the </xsl:stylesheet> tag. Xmlns creates the namespace xsl and therefore all tags inside the stylesheet must be prefixed with the xsl prefix.

How the xslt processor works is difficult to understand since it is not sequentially, it is rule based. With such an empty stylesheet the xsl processor would just remove all tags from the elements and would print out all text of all elements one after an other.

To do something different and have the possibility to replace xml, rules have to be added. A rule is an element with the xsl prefix and the template tag.

<xsl:template ....> 
<some stuff>
</xsl:template>

The xsl processor does not sequentially read and process a xsl file. It checks for rules defined in template elements as seen above and processes its contents. Templates as above are usually nested, this means out of the template other rules set in other templates will be evaluated, therefore the xslt processor recursively processes a tree of templates.

To read any further the details about xpath expressions are not necessary to be understood, since you can easily be lost when reading about xpath. xpath is nothing else than selecting elements in a tree of elements following an approach as selecting a file inside a tree of directories using a path to the file (relative or absolute). However you need to learn the syntax when writing your own not trivial stylesheets.

The most common rule is the match rule.

<xsl:template match="<xpath-expression>">

When the xml file is processed the xml tags are observed and basically drawn away and the rest is printed onto the screen or in a file. If a match template matches with the xml tag processed, then not the tag but the complete element and its child elements are drawn away. This can also be done intentionally to not process an element and its child elements.

<xsl:template match="/"> 

selects the root of the document, therefore everything. Alternatively the match could select the root tag, since all xml files should have just one root element.

Instead of drawing away everything something should be done. The most easiest thing is just adding text (that could also contain <tag>) to the match element. Other thins are:

Read the attributes and write then out

<xsl:attribute name="href">
      <xsl:value-of select="@href"/>
</xsl:attribute>

Write the text of the element

   <xsl:value-of select="."/>

Process all child elements

 <xsl:apply-templates/>

Process just some child elements this can be used as a fork to go down a branch in a tree

 <xsl:apply-templates select="<some tag>"/>

Having match rules everything between the template tag of the stylesheet is written to the output but the matched element and its child elements are not processed.

To have the child elements processed the following instruction is necessary to add inside the match rule:

 <xsl:apply-templates/>

<xsl:template match="echo">   
  <h1 align="center">     
    <xsl:apply-templates/>   
  </h1>
</xsl:template> 

Elements could be added as text

<xsl:template match="www">
   <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <xsl:apply-templates />
</xsl:template>

or with xsl:element to be checked and have higher quality

<xsl:template match="www">
  <xsl:element name="html"
    xmlns="http://www.w3.org/1999/xhtml">
    <xsl:attribute name="lang">en</xsl:attribute>
    <xsl:apply-templates />
  </xsl:element>
</xsl:template>

HTML and XML do not care if line breaks exist. But if you open a automatic produced HTML file you do not like to read everything in a single line. To be able to insert line breaks add first

<xsl:template name="Newline">
  <xsl:text>
  </xsl:text>
</xsl:template>

and then you can produce in your code line breaks by inserting

<xsl:call-template name="Newline" />

An other problem is that you like to insert a or more blanks, but the xslt processor ignores the blanks. Therefore where you like to have the blank insert:

<xsl:text> </xsl:text>

As you see it is as for line break, there a cr character is inserted.

Anything can be printed out using a xpath expression

<xsl:value-of select="<xpath-expression>"/>

To print out the value/text of the selected element use:

<xsl:value-of select="."/> it usually has the same effect as <xsl:apply-templates/> the difference is that it does not go down the tree any further. It prints out the text ignoring any other included elements, instead of processing the text and additional elements.

and the value of an attribute:

<xsl:value-of select="@<attribute name>"/>

Or and the value of an child element:

<xsl:value-of select="./<child element>"/>

Or a neighbor element

<xsl:value-of select="../<neighbor element>"/>

The following example shows how to insert an attribute. The matched element text has to be put as attribute:

<xsl:template match="homepage"> 
 <para>Homepage: 
  <ulink> 
   <xsl:attribute name="url">
    <xsl:value-of select="."/>
   </xsl:attribute>
   <xsl:value-of select="."/>
  </ulink>
  <xsl:apply-templates select="*"/>  
 </para> 
</xsl:template>

The example inserts the url text in the desired places with the <xsl:value-of select="."/> command and avoids that the text is printed else were by just processing the child elements using <xsl:apply-templates select="*"/>

A stylesheet might be less statical and get some variable text. This variable text can be passed to the stylesheet when calling the xslt processor as: xsltproc --stringparam <name><value> ...

To use this parameter, the stylesheet needs a definition:

<xsl:param name="<name>"/>

The parameter can then be used in the stylesheet as $<name> to use the value in the text

<xsl:value-of select="$<name>"/>

The following shows how to add the parameter to an attribute

<img>
  <xsl:attribute name="src">
    <xsl:value-of select="$rel"/>image/logo.gif
  </xsl:attribute>
  <xsl:attribute name="alt">Linurs</xsl:attribute>
</img>

Or more simple

<img src="{$rel}image/logo.gif" alt="Linurs">

Other useful commands are: for-each, sort, if, choose

And now here a simple xsl style sheet

<?xml version="1.0" encoding="ISO-8859-1"?> 
<xsl:stylesheet version="2.0"  
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
xmlns="http://www.w3.org/TR/REC-html40"> 
  <xsl:output method="html"/> 
  <xsl:template match="/"> 
    <html> 
      <body>    
        <xsl:apply-templates/>   
      </body> 
    </html> 
  </xsl:template> 
</xsl:stylesheet>

<xsl:output method="html"/> used the output tag of the xsl namespace. The output tag has all necessary attributes to have or modify a html header.

Here all attributes of the output tag:

<xsl:output 
method = "xml" | "html" | "text" 
version = "string" 
encoding = "string" 
omit-xml-declaration = "yes" | "no"  
standalone = "yes" | "no"  
doctype-public = "string"   
doctype-system = "string" 
indent = "yes" | "no" 
media-type = "string" /> 

Usually you have one stylesheet (or a set of it) an you apply it to many xml files. This is the way as it supposed to be: Write it once (without worry about how it is later visually presented) and then transform it to whatever using stylesheets.

The disadvantage is that you can not simply send a single file to somebody that is not aware of how to deal with XML and this are most humans on our planet. Therefore it is possible to add an xsl stylesheet to your xml data and have a regular web browser to convert it. See http://www.w3.org/TR/xslt/

Since XSLis xml it can be easily included using an other namespace the xsl namespace. However it must also be processed when opened, this is done with a process instruction as

<?xml-stylesheet type="text/xml" href="#stylesheet"?>

The href points to the stylesheet and used id attribute of it

<xsl:stylesheet 
       id="stylesheet"
       version="1.0"
       xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

A little trick remains, stylesheets to not have an an attribute id and parsing would fail. This can be fixed with:

<!DOCTYPE www [
<!ATTLIST xsl:stylesheet
  idID#REQUIRED>
]>

So a simple xml file with an embedded stylesheet looks as:

<?xml version="1.0"?>
<?xml-stylesheet type="text/xml" href="#stylesheet"?>
<!DOCTYPE www [
<!ATTLIST xsl:stylesheet
  idID#REQUIRED>
]>
<www>
 <xsl:stylesheet 
  id="stylesheet"
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="xsl:stylesheet" />
  <xsl:template match="www">
    <html xmlns="http://www.w3.org/1999/xhtml"> 
     <head>
      <meta name="author" content="Urs Lindegger" />
      <title>
       <xsl:value-of select="./head/title" />
      </title>  
      <style type="text/css">
       p.text {color: red; background-color: white;} 
      </style>
     </head>
     <body>  
      <h1> 
       <xsl:value-of select="./head/title"/>
      </h1>
      <xsl:apply-templates select="body"/>    
     </body> 
    </html> 
  </xsl:template>
  <xsl:template match="text">
   <p xmlns="http://www.w3.org/1999/xhtml" class= "text">
     <xsl:apply-templates /> 
   </p>  
  </xsl:template>
 </xsl:stylesheet>

 <head>
    <title>Example how an embeddedd xsl stylesheet</title>
    <description>Embed xsl in xml</description>
    <keywords>xsl, xml</keywords>
  </head>
  <body>
    <text>If it works this text is changed to red</text>
  </body>
</www>

To use the apache formatting object processor emerge fop. See: https://xmlgraphics.apache.org/fop/.

Other formatting object processors are: XMLmind XSL FO that can convert FO to Office Open, OpenOffice and RTF therefore opens the door to the Microsoft World.

An other FO is https://sourceforge.net/projects/xmlroff/

Converting to HTML is much less picky than converting to pdf. One reason is pdf is meant to be paper and html computer screen. If it done not fit to the screen, there is no problem, just use the scroll bars. However if it does not fit to the paper, then there is a serious error.

To convert docbook to formatting object, the fo file:

xsltproc -o<my file>.fo /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xsl <my file>.docbook

And to add a paper format parameter

xsltproc --output bootfromusb.fo --stringparam paper.type A4 /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xsl BootFromUsb.xml

and then to pdf:

fop -fo<my file>.fo -pdf <my file>.pdf

Fop could also convert xml to fop and the to pdf with one call: fop -xml <my file>.xml -xsl <my stylesheet>.xsl -pdf <my file>.pdf

A common warning is:

WARNING: Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400".

700 is the font weight telling how fat bold should be. The font installed does not allow the setting for 700 so 400 is taken this probably give a nicer output. Possible weights are: normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 where normal = 400, bold = 700. This shows that the FOP warning does not find bold and replaces it with normal. This is rated as WARNING but could be considered also as INFO and could therefore ignored.

However it is nice to process data without getting warnings.

A radical way of getting rid of these warnings is to tell xsltproc to not use that fonts by font substitution xsltproc --output doc.fo --stringparam paper.type A4 --stringparam dingbat.font.family serif --stringparam symbol.font.family serif /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xsl doc.xml

It is possible to pass a xml config file with the -c command line option. The file fop.xconf can be found inside apaches fop package, on gentoo it can be taken from /usr/portage/distfiles/fop.

The file holds the default values and therefore should have no effect until it gets modified. However, it changes the path for relative links to the location of this file and therefore troubles as not finding pictures to be included might occur. It also gives out some messages that it changes the page size.

Using font substitution (added right on top not in the <render> sections) the warning can be resolved

<fop version="1.0">
 <fonts> 
   <substitutions> 
     <substitution> 
       <from font-family="Symbol" font-weight="bold"/> 
       <to font-family="Symbol" font-weight="400"/> 
     </substitution>
     <substitution> 
      <from font-family="ZapfDingbats" font-weight="bold"/>        <to font-family="ZapfDingbats" font-weight="400"/> 
     </substitution> 
   </substitutions> 
 </fonts>
</fop> 

Using this file fop is called as: fop -c fop.xconf <..............>

PDF must support the following fonts: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats.

It can happen that it will not find the desired fonts and then default to Times-Roman and showing a # character in the pdf.

If other fonts (as asian) are to be used then they need to be installed first on the PC and then imported to the fop.xconf file.

<renderer mime="application/pdf">
 <filterList>
  <value>flate</value>      
 </filterList>
 <fonts>
  <font kerning="yes"
  embed-url="file:///usr/share/fonts/kochi-substitute/kochi-gothic-subst.ttf"
  encoding-mode="single-byte">
  <font-triplet name="DejaVuSans" 
                style="normal" 
                weight="normal"/>
  </font>      
 </fonts>
</renderer>

The fo file contains the fonts to be used, however the new font will not be in the fo file. So a font substitution is required.

<fop version="1.0"> 
  <fonts> 
    <substitutions> 
     <substitution> 
        <from font-family="serif" /> 
        <to font-family="kochi-gothic-subst" /> 
      </substitution> 

Now the font is ok for asia, but the The Euro sign as unicode € is no more understood and replaced by a dot.

To fix that both fonts the default serif and kochi-gothic-subst need to be used. This can be achieved xsltproc with the command line option:

--stringparam body.font.family serif,kochi-gothic-subst

As result the fo file will contain both fonts and give serif priority:

font-family="serif,kochi-gothic-subst

To not get hyphenation errors emerge offo-hyphenation for apache fop see http://offo.sourceforge.net/ https://xmlgraphics.apache.org/fop/faq.htmland https://xmlgraphics.apache.org/fop/2.1/hyphenation.html. The xml files from offo-hyphenation are not directly used and just put into the /usr/share/offo-hyphenation directory. During the fop compilation they get packed into /usr/share/fop/lib/fop-hyph.jar. To make this happen on gentoo set the hyphenation use flag. This explains why offo-hyphenation needs to be compiled before fop

aunpack -l /usr/share/fop/lib/fop-hyph.jar from atoolshows what hyphenation patterns are available

Pdf means being able to print on paper and this means the pictures must fit within the paper dimension. So the pictures printsize must be smaller than the printable paper size. This sounds easy but:

A good strategy is to agree for portrait format on x pixel resolutions of 640, 320, 160 for the picture dimensions 14cm, 7cm, 3.5cm and have then the y resolution respecting the x/y ratio.

High resolution picture are nice but take some time to download on a web page and when printing on paper the printer must support the resolution.

This gives then a dot per inch resolution of 640/14cm*2.54cm/1inch= 116 dpi or for people that like it simple 100dpi.

identify -units "PixelsPerInch" -format "%w x %h %x x %y" <picture>.<ext> from imagemagick prints out both resolution and dpi

mogrify -resize 320x236! <picture>.<ext> changes the resolution and for exact pixel counts the ! character ignores x/y ration of the original picture.

mogrify -units "PixelsPerInch" -density 100 <picture>.<ext> fixes the dpi (mogrify works on the same file, convert would require two files an input file and an output file)

Newer fop versions have the command line option -a that enables accessibility features as (Tagged PDF and produce additional warnings helping to improve the document). Alternatively fop.xconf can get

<accessibility>true</accessibility> 

However then pictures need alternate text and this is a bit complicated. If used the <graphic> tag needs be replaced by <mediaobject>

<mediaobject>
 <imageobject>
  <imagedata align="center" fileref="pics/<some>.png"/>
 </imageobject>
  <textobject>
    <phrase><some text></phrase>
  </textobject>
</mediaobject>

This works for html but not for fop. For fop the fop extension fox must be added as with xsltproc --stringparam fop1.extensions 1 .... resulting in:

fop <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" 
xmlns:fox="http://xmlgraphics.apache.org/fop/extensions"

then in the fo document it must made be sure that the graphics get the alt-text attribute

<fo:external-graphic src="url(pics/pibs.png)" fox:alt-text="logo"

Unfortunately this is not done automatically by the style-sheets and there is also a reason for it. Not all Formatting Object Processors use fox:alt-text.

A fundamental question. When having XML then why not focus on accessibility friendly and HTML and keep pdf just targeted to print it on paper?

A FO file is pure xml and after its xmlns declaration, it can be separated different parts. The first part defines page layout templates and gives those templates some names:

<?xml version="1.0" encoding="UTF-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">   
   <fo:layout-master-set>                                 
      <fo:simple-page-master master-name="DefaultPage"
         page-width="210mm" 
         page-height="297mm" 
         margin-top="0.5in" 
         margin-bottom="0.5in" 
         margin-left="1in" 
         margin-right="1in" >    
         <fo:region-body/>                      
      </fo:simple-page-master>
   </fo:layout-master-set>
   <fo:page-sequence master-reference="DefaultPage">      
      <fo:flow flow-name="xsl-region-body">               
         <fo:block>Hello World</fo:block>             
      </fo:flow>                        
   </fo:page-sequence>
</fo:root>

After the printable region is defined on the sheet, the region can be divided further in region-before, region-after, region-start, region-end and what is left over is the the region-body that holds the main contents of the page. In the simples form the empty element

<fo:region-body/>

needs to be added. The individual pages can then be added using the page-sequence tag and passing the layout template name using master-reference.

<fo:flow flow-name="xsl-region-body"> 

tells that the text has to go into the region body.

The element block holds what appears on the page. In the simples case it is text. A picture can be added as:

<fo:block>
   <fo:inline>                        
      <fo:external-graphic src="pic.jpg" 
        content-width="159.2mm"
        content-height="271.6mm"/>            
   </fo:inline>
</fo:block>      

There are many more options as choosing different page templates depending on odd or even page numbers.

Finally fop -fo sample.fo -pdf sample.pdf converts it to pdf

Links: https://www.data2type.de/xml-xslt-xslfo/xsl-fo/ http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html and there is also a WYSIWYG editor https://code.google.com/p/fop-miniscribus/

There is https://www.w3.org/TR/WCAG20/ and tools as http://wave.webaim.org/ or with called by the following http://wave.webaim.org/report#/http://www.linurs.org/ evaluates the accessibility of a web page. It allows easily browsing from one page to an other of a web site. There are also plug-ins for web browsers as firefox so with a click a web page can get analyzed.

Errors and Alerts are shown including their reasons. Having created the web site with style sheets allows easily improving the stylesheets and then having all web pages cleaned up.