jonathanblaney
commented
8 years ago Hi @mhbeals. I found this a clear and focused introduction to XSLT basics. The example texts are an excellent basis for demonstrating of the power of XSLT and the additional scripts that you provide as part of the download will be particularly useful for beginners after they have finished the tutorial. The exercises are clear and cover the right first transformations that most people will want to do with XSLT.
It's very condensed and therefore asks a lot of the reader. I think it's reasonable to expect the reader to do some work and reading around, but more pointers to useful resources would be beneficial.
The set-up information is just right: very common tools with no config required. I wonder whether a sentence along the lines of "when you're comfortable with XML technologies you might like to explore dedicated XML editors..." might be useful. Although I found the set-up easy you might consider putting the stylesheet declaration on a line on its own for clarity: on my laptop the line break made it unclear that I should type <?xml-stylesheet type... rather than <?xml-stylesheettype....
I only have a few suggestions for amplification here and there, which I hope might make the course even more useful for readers coming to XML and XSLT with little or no prior knowledge.
- Word and Excel. Given the scenario outlined at the beginning of the tutorial, I think there should be some mention of transforming Word and Excel, especially that docx and xlsx are XML. The XML underlying a simple Word file is a horrible mess, but this is the beauty of XSLT: you can unzip the docx then use XSLT to blow away the bloat. With Excel there are more ways to transform, but I think Excel's own built-in XML transformation tool is the simplest to use.
- The XML introduction is very brisk. Are there are a couple of online tutorials that you can link to? It's a shame that the Programming Historian doesn't currently have a dedicated XML tutorial. The Wikipedia link to XSLT elements here might be confusing for newcomers.
- You ask the reader to open the base XML file in a text editor. I wonder whether you could additionally ask them to open it with a browser, which will display the file in a tree structure that is perhaps more comprehensible to someone new to XML and this data; it would also set up the first transformation you do, which will drop the elements from this display.
- When you discuss the path to
title, is it worth mentioning that this is XPath? Half the time when I get stuck with XSLT I do a web search for XPath syntax, because I'm not hitting the right node. - A brief explanation of why
<xsl:text>is sometimes necessary but sometimes not (as with the brackets in Exercise B) might be helpful. Also in the solution to Exercise C you could add a note that a literal space instead of the hex code you use would also be correct.
I really enjoyed this tutorial and I think newcomers to XSLT will be encouraged by the speed with which it gets them transforming real historical data. This is going to be a very good addition to the Programming Historian.
acrymble
mhbeals
TessaC
ianmilligan1
The Programming Historian has received the following tutorial on 'Transforming Historical Data for Reuse and Republication: A Guide to XML and XSL Transformations' by @mhbeals. This lesson is now under review and can be read at:
http://programminghistorian.github.io/ph-submissions/lessons/transforming-xml-with-xsl
I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.
Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.
I will endeavour to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me. You can always turn to @ianmilligan1 or @miriamposner if you feel there's a need for an ombudsperson to step in.
Anti-Harassment Policy _
_