xmlcourse.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1672bfed-d0cd-4351-89c0-04f1cde426ed",
   "metadata": {},
   "source": [
    "# Preliminaries\n",
    "- install the saxon parser and API library using pip."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0da2a627-0ae8-4d5d-8119-6b9fef1aa2ec",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Requirement already satisfied: saxonche in c:\\python312\\lib\\site-packages (12.5.0)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n",
      "[notice] A new release of pip is available: 24.2 -> 24.3.1\n",
      "[notice] To update, run: python.exe -m pip install --upgrade pip\n"
     ]
    }
   ],
   "source": [
    "!pip install saxonche"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9ce94d1-8244-46bd-b1e7-d93e2ed88dec",
   "metadata": {},
   "source": [
    "- Import the Python library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ca392bf3-90b2-4a51-bd43-737b059031a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from saxonche import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd8f6a6e-20ac-4d69-b773-6f44e1db840e",
   "metadata": {},
   "source": [
    "- Test the Python library and API, the result should be the API version"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "ae28f9ba-8be7-4c4d-a0f1-2e8eb69f7137",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SaxonC-HE 12.5 from Saxonica\n"
     ]
    }
   ],
   "source": [
    "from saxonche import PySaxonProcessor\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    "\tprint(proc.version)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b01c126-821c-48b1-831e-c24b42b89bb0",
   "metadata": {},
   "source": [
    "- Transform the test.xml file using the test_one.xsl transformation stylesheet."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "6e016da4-37d0-4a24-87e9-0c11aa6c88b1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!DOCTYPE HTML>\n",
      "<html>\n",
      "   <head>\n",
      "      <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n",
      "   </head>\n",
      "   <body>\n",
      "      \n",
      "      <hr>\n",
      "      <h1>Postcard</h1>\n",
      "      \n",
      "      \n",
      "      <div class=\"content\">\n",
      "         <h2>Contents</h2>I love marmalade!</div>\n",
      "      \n",
      "      \n",
      "      <div class=\"address\">\n",
      "         <h2>Name and Address</h2>\n",
      "         <ul>\n",
      "            \n",
      "            <li><b>name</b>&nbsp;Paddington Bear</li>\n",
      "            \n",
      "            <li><b>co</b>&nbsp;Mrs Brown</li>\n",
      "            \n",
      "            <li><b>street</b>&nbsp;32 Windsor Gardens</li>\n",
      "            \n",
      "            <li><b>town</b>&nbsp;Notting Hill</li>\n",
      "            \n",
      "            <li><b>county</b>&nbsp;London</li>\n",
      "            \n",
      "            <li><b>country</b>&nbsp;United Kingdom</li>\n",
      "            \n",
      "            <li><b>postcode</b>&nbsp;W9 3RG</li>\n",
      "            </ul>\n",
      "      </div>\n",
      "      \n",
      "      <hr>\n",
      "      </body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('postcard.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     executable = xsltproc.compile_stylesheet(stylesheet_file=\"test_one.xsl\")\n",
    "     output = executable.transform_to_string(xdm_node=document)\n",
    "     print(output)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e44e0e1b-1367-46e8-bee1-1d632023260b",
   "metadata": {},
   "source": [
    "## Exercise 1 (10 minutes approx)\n",
    "\n",
    "For the first exercise, we need to extend the data to reflect the postcard (postcard.xml) more accurately.\n",
    "- Firstly think about ways to enhance the postcard contents.\n",
    "- In the copy of postcard.xml (postcard-exercise.xml), add new elements to the XML data to reflect the enhancements.\n",
    "\n",
    "Test your changes with the codeblock below - if the XML isn't well-formed the parser will fail to process it and you will see errors. If it runs through the parser you will also see the file contents.\n",
    "\n",
    "Remember the tags must fully enclose the elements you want to capture i.e. `<example>text</example>`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "62c11199-df5c-4a21-8b5c-3860abd049f6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!--- root element **REQUIRED** --><root>\n",
      "   <postcard>\n",
      "        <!-- postcard text -->\n",
      "      <content>I love marmalade!</content>\n",
      "      <!-- address details -->\n",
      "      <address>\n",
      "         <name>Paddington Bear</name>\n",
      "         <co>Mrs Brown</co>\n",
      "         <street>32 Windsor Gardens</street>\n",
      "         <town>Notting Hill</town>\n",
      "         <county>London</county>\n",
      "         <country>United Kingdom</country>\n",
      "         <postcode>W9 3RG</postcode>\n",
      "      </address>\n",
      "   </postcard>\n",
      "</root>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard-exercise.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     print(document)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be805a27-0b3c-49ed-8abd-94ad283417ac",
   "metadata": {},
   "source": [
    "## Exercise 2 (5 minutes approx)\n",
    "\n",
    "Now try using attributes to enhance the elements you have added to the postcard-exercise.xml. If you need some assistance take a look at the postcard-enhanced.xml file for some hints about how to use the attributes.\n",
    "\n",
    "Once you have added the new attributes to postcard-exercise.xml run the code snippet below to check for errors\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "4d59628e-0ca0-47ed-b610-9d7e5d61d87a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!--- root element **REQUIRED** --><root>\n",
      "   <postcard>\n",
      "        <!-- postcard text -->\n",
      "      <content>I love marmalade!</content>\n",
      "      <!-- address details -->\n",
      "      <address>\n",
      "         <name>Paddington Bear</name>\n",
      "         <co>Mrs Brown</co>\n",
      "         <street>32 Windsor Gardens</street>\n",
      "         <town>Notting Hill</town>\n",
      "         <county>London</county>\n",
      "         <country>United Kingdom</country>\n",
      "         <postcode>W9 3RG</postcode>\n",
      "      </address>\n",
      "   </postcard>\n",
      "</root>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('postcard-exercise.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     print(document)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b56f9ab-353f-4583-a22e-e5dcc5159360",
   "metadata": {},
   "source": [
    "## Sample XSLT\n",
    "\n",
    "Here's a quick sample of some XSLT in action processing postcard-enhanced.xml into HTML. Apologies, but the images won't render in the HTML (that's a Jupyter issue)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "5dc3c8c7-ad20-418e-a423-c878e26fd360",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!DOCTYPE HTML>\n",
      "<html>\n",
      "   <head>\n",
      "      <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n",
      "   </head>\n",
      "   <body>\n",
      "      \n",
      "      <hr>\n",
      "      <h1>Postcard</h1>\n",
      "      \n",
      "      <div class=\"front_plate\"><img class=\"front_plate_image\" src=\"./paddington.jpg\"></div>\n",
      "      \n",
      "      <div class=\"backplate_stamp\"><img class=\"stamp\" src=\"firstclass.jpg\"></div>\n",
      "      \n",
      "      \n",
      "      <div class=\"content\">\n",
      "         <h2>Contents</h2>I love marmalade!</div>\n",
      "      \n",
      "      \n",
      "      <div class=\"address\">\n",
      "         <h2>Name and Address</h2>\n",
      "         <ul>\n",
      "            \n",
      "            <li><b>name</b>&nbsp;Paddington Bear</li>\n",
      "            \n",
      "            <li><b>co</b>&nbsp;Mrs Brown</li>\n",
      "            \n",
      "            <li><b>street</b>&nbsp;32 Windsor Gardens</li>\n",
      "            \n",
      "            <li><b>town</b>&nbsp;Notting Hill</li>\n",
      "            \n",
      "            <li><b>county</b>&nbsp;London</li>\n",
      "            \n",
      "            <li><b>country</b>&nbsp;United Kingdom</li>\n",
      "            \n",
      "            <li><b>postcode</b>&nbsp;W9 3RG</li>\n",
      "            </ul>\n",
      "      </div>\n",
      "      \n",
      "      <hr>\n",
      "      </body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('postcard-enhanced.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     executable = xsltproc.compile_stylesheet(stylesheet_file=\"test-enhanced.xsl\")\n",
    "     output = executable.transform_to_string(xdm_node=document)\n",
    "     print(output)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "226df5bb-66c2-4041-9a32-4aefec24b0a3",
   "metadata": {},
   "source": [
    "## Exercise 3 (10 minutes approx - optional)\n",
    "\n",
    "Data definitions are the mechanism to control the use of elements and attributes within an XML document. This should (ideally) prevent the document contents becoming inconsistent. It's also the mechanism used to create standards such as MODS/METS, HTML, EPub amongst others.\n",
    "\n",
    "There is no ideal way to create a data definition within the notable environment and hand-coding them is a tricky business. However, if you are feeling bold you can upload your postcard-exercise.xml file to this sites [xsd generator](https://www.freeformatter.com/xsd-generator.html) and create a Schema file for it.\n",
    "\n",
    "You can utilise the schema and apply the data definition by creating the XSD file (example.xsd for example) in your working directory, pasting the created schema into the new file. Then amend the root element to apply the schema.\n",
    "\n",
    "`<root xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n",
    "xsi:noNamespaceSchemaLocation=\"example.xsd\">`\n",
    "\n",
    "Once amended check that the schema is functioning by running the postcard-exercise.xml through the parser using the snippet below. You could also try adding some unconstrained elements to see the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "288543a3-185e-412b-b399-e81a67aaf6fb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!--- root element **REQUIRED** --><root>\n",
      "   <postcard>\n",
      "        <!-- postcard text -->\n",
      "      <content>I love marmalade!</content>\n",
      "      <!-- address details -->\n",
      "      <address>\n",
      "         <name>Paddington Bear</name>\n",
      "         <co>Mrs Brown</co>\n",
      "         <street>32 Windsor Gardens</street>\n",
      "         <town>Notting Hill</town>\n",
      "         <county>London</county>\n",
      "         <country>United Kingdom</country>\n",
      "         <postcode>W9 3RG</postcode>\n",
      "      </address>\n",
      "   </postcard>\n",
      "</root>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard-exercise.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     print(document)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc0a923c-b0aa-495b-9c0a-8c431399727f",
   "metadata": {},
   "source": [
    "## Exercise 3 (alternative)\n",
    "\n",
    "As an alternative I've provided a sample xHTML file which has an existing data definition. Try adding some unconstrained elements into xhtml-sample.xml and the parser will complain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "7425e0e3-8415-4f09-9aa1-623f83ee1a60",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!-- \n",
      "    Using the older DTD definition to provide entities for the document.\n",
      "    In this case the nbsp entity (non-breaking space).\n",
      "--><!-- declarative markup, in this case using the root element of xhtml --><html xmlns=\"http://www.w3.org/1999/xhtml\"\n",
      "      xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n",
      "      xsi:schemaLocation=\"http://www.w3.org/1999/xhtml https://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd\">\n",
      "   <head>\n",
      "      <title>Example of xHTML using the xHTML schema</title>\n",
      "   </head>\n",
      "   <body>\n",
      "      <h1>Example of Declarative Markup</h1>\n",
      "      <p>\n",
      "            This is an example of using a controlled vocabulary to create a datafile of a particular <b>\n",
      "            type</b>.\n",
      "        </p>\n",
      "      <p>\n",
      "            In this case the schema used is the version 1.1 xHTML schema. There are some notable differences \n",
      "            between xHTML and HTML. And although HTML (a form of SGML) is still by far more widespread, xHTML\n",
      "            is still used quite widely. The <b>EPUB standard</b>, for example, is a modified form of xHTML.\n",
      "        </p>\n",
      "      <p>\n",
      "            There are plans at the W3C to align xHTML with HTML5 (xHTML 2.0).\n",
      "        </p>\n",
      "   </body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('xhtml-sample.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     print(document)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b4d9b3f-368c-46b5-b535-4fa95aca4794",
   "metadata": {},
   "source": [
    "# XPath and XSLT\n",
    "\n",
    "Welcome to the section on XPath and XSLT. I've attempted to framework the course around both these elements at the same time as XPath understanding is central the XSLT.\n",
    "\n",
    "However for starters there are some sample XPath expressions below. I would advise ignoring most of the Python code."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d46a9e6e-9701-4447-8dd6-696e488bf27a",
   "metadata": {},
   "source": [
    "## Example XPath\n",
    "\n",
    "Get the addressee of the postcard from postcard.xml. The XPath in this case is in the code block but for clarity it is `/root/postcard/address/name`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "ef9565d6-7719-4e4c-97c7-1034a945df58",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<name>Paddington Bear</name>\n"
     ]
    }
   ],
   "source": [
    "from saxonche import *\n",
    "\n",
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     xpathproc = proc.new_xpath_processor()\n",
    "     xpathproc.set_context(xdm_item=document)\n",
    "     # here's the xpath call\n",
    "     result = xpathproc.evaluate(xpath_str='/root/postcard/address/name')\n",
    "     print(result)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73e47bb0-c08e-4311-a2a2-fb32282cf958",
   "metadata": {},
   "source": [
    "In the example above the XPath expression is `/root/postcard/address/name`. This tells the parser to extract the data element using the full path to the name element using the tags to identify the route. This example represents an *absolute path*\n",
    "\n",
    "There are a few valid alternatives. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "1c727f62-b226-441b-ba1e-0e454f7b696f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<name>Paddington Bear</name>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     xpathproc = proc.new_xpath_processor()\n",
    "     xpathproc.set_context(xdm_item=document)\n",
    "     # here's the xpath call\n",
    "     result = xpathproc.evaluate(xpath_str='//name')\n",
    "     print(result)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdf22601-bca0-4acc-883f-20c4feaf716a",
   "metadata": {},
   "source": [
    "XPath has a variety of ways to select individual data elements. In the example above `//name` informs the XPath processor to find any element in the tree called 'name'. These navigational elements are known as **'Selectors'**.\n",
    "\n",
    "\n",
    "In the example below using postcard-enhanced.xml I'm going to extract the 'image' attribute from the front plate element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "33e63728-f007-44af-b14a-145a1b671efd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "image=\"paddington.jpg\"\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard-enhanced.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     xpathproc = proc.new_xpath_processor()\n",
    "     xpathproc.set_context(xdm_item=document)\n",
    "     # here's the xpath call\n",
    "     result = xpathproc.evaluate(xpath_str='//front/@image')\n",
    "     print(result)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ea1b5f9-0f00-42ba-9a29-8b9ecee34875",
   "metadata": {},
   "source": [
    "Using the '@' character the expression can find and process the attributes of elements. These are known as **'Axes'**\n",
    "\n",
    "There are a variety of different axes available to the XPath processor. These include:\n",
    "\n",
    "- ancestor\n",
    "- ancestor-or-self\n",
    "- attribute (@)\n",
    "- child\n",
    "- descendant\n",
    "- descendant-or-self\n",
    "- following\n",
    "- following-sibling\n",
    "- parent\n",
    "- preceding\n",
    "- preceding-sibling\n",
    "- self\n",
    "\n",
    "However, for now I would recommend using the basic selectors."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01571c21-3269-4a30-b062-b0e34d1f7fde",
   "metadata": {},
   "source": [
    "### Other selectors\n",
    "\n",
    "There are other selector types. For example a wildcard can be used in an XPath expression."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "c5f56f62-83c2-4101-91c1-10684730dce7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "image=\"paddington.jpg\"\n",
      "image=\"firstclass.jpg\"\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard-enhanced.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     xpathproc = proc.new_xpath_processor()\n",
    "     xpathproc.set_context(xdm_item=document)\n",
    "     # here's the xpath call\n",
    "     result = xpathproc.evaluate(xpath_str='//*/@image')\n",
    "     print(result)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5dc03a71-6ea6-4edf-9420-3bc2d62ccbc1",
   "metadata": {},
   "source": [
    "The example above using the wildcard expression '*' finds both the image attributes in the document. But it's also possible to find particular content using XPath as in the example below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "96908b12-901d-44be-85ee-1b3e9f246b07",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<stamp image=\"firstclass.jpg\" origin=\"UK\">first class stamp - United Kingdom</stamp>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('postcard-enhanced.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     xpathproc = proc.new_xpath_processor()\n",
    "     xpathproc.set_context(xdm_item=document)\n",
    "     # here's the xpath call\n",
    "     result = xpathproc.evaluate(xpath_str='//*[@image=\"firstclass.jpg\"]')\n",
    "     print(result)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa51f906-8d34-4113-95f5-294a8a1f5b91",
   "metadata": {},
   "source": [
    "In this particular example the XPath selects the node which contains the matching attribute not the attribute contents. That's the role of the '[]' enclosing braces. It informs the processor the check within the element for the requirements and returns."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a49a12f-63f5-4216-8bd4-c2b063aa0347",
   "metadata": {},
   "source": [
    "## Introduction to XSLT\n",
    "\n",
    "XSLT is another W3C standard for transforming XML. This transformation is typically into another markup standard but potentially can be used to generate an arbitary output. It is not uncommon, for example, to process XML into a PDF or another binary format. It's also worth noting that XSLT is itself a form of XML.\n",
    "\n",
    "The underlying principle of XSLT is that is aligns to the function of the parser (I alluded to it earlier). The parser will process the entire document. XSLT templates will instruct the processor to perform certain actions when an element is reached that matches a template instruction. The matching value is naturally provided to the processor using an XPath expression."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a57fc578-ed9c-4fe0-b6b5-35268cf3cb33",
   "metadata": {},
   "source": [
    "There's a simple XSL file provided that processes the 'postcard.xml' into HTML (as per the preamble). Open it an take a look at the contents."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "85ab3747-1f04-4162-8a0f-9f51ae0b7fd7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<xsl:stylesheet xmlns:math=\"http://www.w3.org/2005/xpath-functions/math\"\n",
      "                xmlns:xd=\"http://www.oxygenxml.com/ns/doc/xsl\"\n",
      "                xmlns:xs=\"http://www.w3.org/2001/XMLSchema\"\n",
      "                xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"\n",
      "                exclude-result-prefixes=\"xs math xd\"\n",
      "                version=\"3.0\">\n",
      "   <xsl:output encoding=\"utf-8\" method=\"html\" omit-xml-declaration=\"yes\"/>\n",
      "   <xsl:template match=\"/\">\n",
      "      <xsl:apply-templates/>\n",
      "   </xsl:template>\n",
      "   <xsl:template match=\"root\">\n",
      "      <html>\n",
      "         <head>\n",
      "                <!-- place head info here -->\n",
      "            </head>\n",
      "         <body>\n",
      "            <xsl:apply-templates/>\n",
      "         </body>\n",
      "      </html>\n",
      "   </xsl:template>\n",
      "   <xsl:template match=\"postcard\">\n",
      "      <hr/>\n",
      "      <h1>Postcard</h1>\n",
      "      <xsl:apply-templates/>\n",
      "      <hr/>\n",
      "   </xsl:template>\n",
      "   <xsl:template match=\"content\">\n",
      "      <div class=\"content\">\n",
      "         <h2>Contents</h2>\n",
      "         <xsl:apply-templates/>\n",
      "      </div>\n",
      "   </xsl:template>\n",
      "   <xsl:template match=\"address\">\n",
      "      <div class=\"address\">\n",
      "         <h2>Name and Address</h2>\n",
      "         <ul>\n",
      "            <xsl:apply-templates/>\n",
      "         </ul>\n",
      "      </div>\n",
      "   </xsl:template>\n",
      "   <xsl:template match=\"name | co | street | town | county | country | postcode\">\n",
      "      <li>\n",
      "         <b>\n",
      "            <xsl:value-of select=\"local-name(.)\"/>\n",
      "         </b> <xsl:value-of select=\".\"/>\n",
      "      </li>\n",
      "   </xsl:template>\n",
      "</xsl:stylesheet>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " with open('test_one.xsl', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     print(document)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f4c89bb-6837-4b8f-9d80-902d95ce0c89",
   "metadata": {},
   "source": [
    "The key elements of the XSL instructions are the `<xsl:template match=\"...\">` tags and `<xsl:apply-templates/>`.\n",
    "\n",
    "The former tells the processor to apply the template instruction when the matching tag is reached. The 'apply-templates' instruction is used to ensure that if an element contains sub-elements with their own template, they will also be processed.\n",
    "\n",
    "These are debatably the two main instructions when considering an XSL transformation.\n",
    "\n",
    "The next instruction to consider is `<xsl:value-of select=\"...\">`. This assigns the value provided by the 'select' attribute. Which, unsuprisingly, is typically an XPath expression. In some of the examples you may see a '.' character in the select attribute. This is shorthand for the current element. \n",
    "```\n",
    " <xsl:template match=\"//name\">\n",
    "    <p><xsl:value-of select=\".\"/></p>\n",
    " </xsl:template/>\n",
    "```\n",
    "So in the example above the currently selected node would be the name element, and the value '.' would also be the contents of the name element."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cac84b8-e551-4d07-8bbb-74dc7e84d4b9",
   "metadata": {},
   "source": [
    "## Exercise 4 (5 minutes approx)\n",
    "\n",
    "The snippet below, executes 'postcard-exercise.xsl'. This outputs only the name in the address block from postcard.xml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "51cbeda1-c94b-49a0-8403-efbf82c1cb07",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!DOCTYPE HTML>\n",
      "<html>\n",
      "   <head>\n",
      "      <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n",
      "   </head>\n",
      "   <body>\n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      <p>Paddington Bear</p>\n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      </body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('postcard.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     executable = xsltproc.compile_stylesheet(stylesheet_file=\"postcard-exercise4.xsl\")\n",
    "     output = executable.transform_to_string(xdm_node=document)\n",
    "     print(output)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99ec56fc-48a3-4a8b-88c2-f5d9374104a5",
   "metadata": {},
   "source": [
    "Take a look at the contents of the 'postcard-exercise4.xsl' file. It has three elements that use the `<xsl:template match=\"...\">` expression to filter the elements that are required in the output file. The first creates the essentials for an HTML document (the root; html and the head and body). The second outputs that name and the third trims out the extraneous elements (such as street and city).\n",
    "\n",
    "The final instruction uses what is termed 'conditional operators' to select a group of elements.\n",
    "{\n",
    "<xsl:template match=\"content | co | street | town | city | country | county | postcode\">\n",
    "        <!-- noop -->\n",
    "</xsl:template>\n",
    "}\n",
    "The '|' character, unlike other computer languages is not an 'OR' expression it's in fact a union. So I would exercise caution using this type of expression. The `<!-- is a comment -->` are comments."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9aa09fb4-3631-469a-9963-0d3d4f0acfd2",
   "metadata": {},
   "source": [
    "For the next exercise, edit the postcard-exercise4.xsl file. In addition to the name of the addressee, output the postcode in a seperate paragraph block. It should be visible in the output of the snippet below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "0e003dfc-0430-410e-ab15-cd8a3a11a761",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!DOCTYPE HTML>\n",
      "<html>\n",
      "   <head>\n",
      "      <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\n",
      "   </head>\n",
      "   <body>\n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      <p>Paddington Bear</p>\n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      \n",
      "      </body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('postcard.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     executable = xsltproc.compile_stylesheet(stylesheet_file=\"postcard-exercise4.xsl\")\n",
    "     output = executable.transform_to_string(xdm_node=document)\n",
    "     print(output)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84afce8c-78a2-494f-b2da-79cee478144d",
   "metadata": {},
   "source": [
    "## Exercise 5. Intermediate XSL (15 minutes approx)\n",
    "\n",
    "The postcard.xml represents a very simple document structure, for the next exercise we will try something more challenging.\n",
    "\n",
    "The document 'A01092.headed.xml' is a transcription document in XML from 'Early English Books Online' (EEBO).\n",
    "\n",
    "Try to extract the title text (TITLE tag) from the document in HTML as a paragraph block `<p>...</p>`. There is a sample XSLT file (eebo.xsl) to assist.\n",
    "\n",
    "Additionally, there are some useful idioms that can be used to overcome some of the issues and help in quickly removing unwanted content.\n",
    "\n",
    "The initial template is an example of this:\n",
    "```\n",
    "    <xsl:template match=\"node()|@*\">\n",
    "        <!-- noop -->\n",
    "    </xsl:template>\n",
    "```\n",
    "It essentially states that if any node (element) or attribute (the @*) is encountered it is ignored. The reason that the subsequent template outputs the html is that in the event of multiple conflicting templates, the *last* template is applied. So when the ETS (root) tag is encountered it will conflict with the initial template but will have precendence.\n",
    "\n",
    "This trick with precedence can be used to control the output of content in large, complex documents.\n",
    "\n",
    "It might take a few tries to get this one right, check the output with the code snippet below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "a8f64a3f-dd78-4a86-a624-aa9ebc8e4b5f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<!DOCTYPE HTML>\n",
      "<html>\n",
      "   <head>\n",
      "      <meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\">\n",
      "   </head>\n",
      "   <body></body>\n",
      "</html>\n"
     ]
    }
   ],
   "source": [
    "with PySaxonProcessor(license=False) as proc:\n",
    " \n",
    " xsltproc = proc.new_xslt30_processor()\n",
    " with open('A01092.headed.xml', encoding=\"utf-8\") as xmlfile:\n",
    "     document = proc.parse_xml(xml_text=xmlfile.read())    \n",
    "     executable = xsltproc.compile_stylesheet(stylesheet_file=\"eebo.xsl\")\n",
    "     output = executable.transform_to_string(xdm_node=document)\n",
    "     print(output)\n",
    "     xmlfile.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96f1c01a-2e21-4772-a6bb-4ad31fc58d71",
   "metadata": {},
   "source": [
    "If correct you should see the full title displayed in the html body. And congratulations are in order. The EEBO document is a complex one."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d23a2cfe-1118-44c5-8187-59c75f32a3b8",
   "metadata": {},
   "source": [
    "# FIN"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f5103943-05fd-48cb-8df0-b084f8292bca",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}