John Walkup

Technical writing has long interested me. When I taught physics at Cal Poly, Melody DeMeritt (a member of the English Department faculty) and I co-facilitated a writing workshop as part of the university’s WinGED (Writing in General Education) program.  I not sure who, but someone introduced me to the writing method E-Prime during the workshop. I forgot about E-Prime for the next few years, but picked up the method again roughly two years ago. I am glad I did.

The E-Prime writing method involves recasting sentences to remove all forms of the verb “to be.”  (I have boldfaced and colored red such verbs throughout this blog entry.) Verbs of the form “to be” point to the concept of existence, but dynamic writing typically targets more meaningful actions.

I consider E-Prime challenging, but I think such efforts produce cleaner prose. The process of transforming a passage into E-Prime often forces the writer to re-evaluate his or her position, often to substantial benefit.

Let me demonstrate the process using a passage from an article Gerlinde Olvera* and I recently submitted to a research journal for publication. First, we start with the original passage:

I note two instances of the verb form “to be.”  The verb “is” dominates the first sentence over the action verb “facilitate,” an unfortunate construction. I can recast the first sentence by propelling the main verb “facilitate” to a more prominent position, eliminating “is” altogether.

I love the directness of this sentence, but it contains an ambiguity: Teachers mainly facilitate… as opposed to what?  Or should we interpret the sentence as “Teachers mainly facilitate Level-3 activities…” as opposed to Level-2 activities? In other words, should we consider the verb “facilitate” or the direct object “Level-3 activities” the focus of the sentence? (Note that the original sentence contained this flaw as well.) Let’s try to clarify our position:

Although longer than the original sentence (by roughly one word), our result contains more information.

Now we can consider the second sentence, where I have inserted one of my own proofreading comments in parentheses:

The first problem centers on the verb “expected.” Although stronger than verbs of the form “to be,” the verb “expected” relates to a passive educational process. As teachers, we do not merely “expect” students to think in certain ways; we “guide” or “teach” them.

Students are guided by whom?  The teacher? The school? Here, appearance of the verb “are” points to a passive construction and, therefore, begs for recasting into E-Prime.

Since both sentences begin with the same subject “teacher,” we can simplify the second equation using the pronoun “they”:

Looks good to me! The result removes considerable ambiguity and saves space–a win-win situation. The reader may object that the last instance of the word “them” could refer to the subject “teachers” or the direct object “students,” but to me the sentence reads just fine.

Those seeking help with this writing method should consider visiting the Wiki Encyclopedia entry and the links at the bottom of the page.

Oh, if you think you can offer suggestions for improving my prose or simply want to comment on my efforts, please do so.

_______

* Gerlinde analyzes curricular materials and contributes to our knowledge base (especially in regards to English language learners and 21st Century Skills) here at The Standards Company LLC.

I am becoming more involved in the California Mathematics Council (http://www.cmc-math.org/) and recently presented at both the South and North division conferences.

The South conference was hosted in Palm Springs and I took my daughter with me.  She had been begging to see her favorite metal band Turisas and they were appearing in Pomona, so why not?  They are Finnish and don’t appear in the U.S. very often.  They are also incredible and put together one of the most vivid (and loudest) concerts I have ever witnessed. Another LA-area band called Ironklad was extraordinary as well, and I urge anyone that loves nu-metal (e.g. Disturbed) and lives in Southern California to go see them.

In both Palm Springs and Asilomar, I presented “Avoiding the Most Common Mistakes in Math Instruction,” a compilation of boo-boos that I have witnessed over the years as a professional developer.  Since math is my second main love (behind physics), I especially enjoy presenting this talk, and it was well received.  In summary, here is one portion of the Walk of Shame (I will post more later):

A.  Ineffective questioning strategies — calling on volunteers (raised hands) is a particularly troublesome questioning method that causes much of the discipline problems and mental disengagement taking place inside our classrooms.  With a few exceptions, there is little reason to ask for volunteers to answer a question.  I advocate the following four-step procedure:

1.  Question the entire class (not just a single student)

2.  Wait sufficiently long before choosing students to respond.  (This is where I advocate letting students discuss the answers in pair shares (for DOK-2 questions) or small groups (for DOK-3 and DOK-4 questions).

3.  Sample the class by randomly selecting non-volunteers to answer the question.

4.  Leave No Child Behind–do not simply proceed if the responses indicate students are struggling.

B. Insufficient Concept Development — math teachers often focus too much on procedural knowledge development, which is not only limiting and easily forgotten, it is also a signature of the drill-and-kill method of solving math problems that turns students away from math and science.  (One of my curriculum specialists, Lisa Gibson, wrote an article based on this issue and was recently published by the journal Communicator.)

C. Not Teaching the Importance — too many mathematicians think that students will appreciate the inner beauty of mathematics and love the discipline for its own sake.  As far as students are concerned, Elizabeth Hurley is beautiful, Whittaker functions are not.  My opinion is that if we don’t teach students why the lesson they are learning is important, then why would they want to learn it?  (And no, telling students “You will need to know this on the test” does not count.)

D. Teaching subskills at the expense of grade-level content — yes, students often lack the subskills we think they need to learn grade-level content. However, we can scaffold these subskills while teaching them standards-based content.  For example, when teaching students to calculate powers of integers, I can provide them a multiplication table — the lesson is focused on calculating the powers of integers, not basic arithmetic. Remember, if we have taught students to calculate powers and what the concept “exponential expression” means, they have a chance on the state test; if we have instead focusing on reteaching them basic multiplication, they have no chance at all.

That’s enough for now. If you want the PowerPoint of my presentation, just shoot me a note. And go see Ironklad; they’re great.

Lately I have been reading an article by Andrew Ho in the journal Educational Researcher titled “The problem with `proficiency’: limitations of statistics and policy under No Child Left Behind.” It is a worthwhile article and I encourage others (hint: employees of The Standards Company) to read it.

Briefly, Ho describes a statistical analysis of student proficiency on state assessments. Now, each state defines “proficiency” differently. So while one state may decide that 50% correctness is worthy of a student to be denoted “proficient,” another state may decide 70% is the better choice. Naturally, the cut-off between “proficient” and “not proficient” would dramatically change the percentage of students considered proficient in one state in comparison to another. Who would argue otherwise?

What is not so clear is whether changes in the percentage of students scoring proficient would change between one state and the next if the cut-off point was changed. At first glance it shouldn’t matter: where two race cars begin on a track has little to do with how rapidly one car would gain on the other.

But complications set in when one considers that the race car analogy does not quite hold when examining state test proficiency, which does not map the gains from the same students from one year to the next but rather the same graduating class of students from one year to the next. In other words, we measure a batch of students designated as Grade 6 in one year, and another batch of students designated as Grade 6 the next year. In this case, the arbitrary cut-off point between “proficient” and “not proficient” can affect the growth in the number of students scoring proficient. It all comes down to a basic issue: how many students were on the edge of the cut-off point?

Ho performed a statistical analysis of data collected from a blind state (that is, Ho may know which state is under consideration, but he isn’t telling us) to measure the rate-of-change in student proficiency across two years. He then changed the cut-off point and re-performed the analysis.

Guess what? The rate-of-change changed dramatically, indicating that rate-of-change is overly sensitive to the choice of cut-off point.

There is a direct analogy of this issue in computer simulation. A common measure of the worth of a computer simulation is the sensitivity analysis. For example, suppose I have a computer simulation designed to indicate weather patterns appearing ten years from today. Naturally, I have to feed initial conditions into the computer before I can start the simulation. Suppose that I input the temperature, pressure, humidity, and wind speeds appearing at 5,000 locations spread across the globe. When I run the simulation, I find that a hurricane is blowing through College Station, TX, ten years from today. I can certainly publish my results and have Aggie fans begin upgrading their building codes in preparation for the onslaught of weather.

Now suppose that, for kicks, I decide to run the simulation once again. If I choose the same exact initial conditions, I should get the same result, a hurricane over College Station. (Actually, most simulations feature randomness, either by design or through random error, that would produce a different result if ran again.) However, I decide to modify the initial temperature at one of the 5,000 points by one degree. When I run the simulation once again, I instead get a hurricane over China.

So of what use is my computer simulation? Very little, because there is a fat chance that I would be able to input enough data describing the initial conditions to such precision that would produce a reliable result. Miss one temperature measurement by one degree and the hurricane appears on the other side of the globe.

According to Ho, the same problem exists in state test score proficiency. Small changes in what is arbitrarily termed “proficient” produces marked changes in improvement. So one state that improves rapidly in comparison to the others could be doing so simply because of its choice in the cut-off value, and little else.

As an education researcher, Ho’s findings reinforce my assertion that the real gains in education are made not through test score analysis (which Ho has shown are highly suspect) but through upgrades in curriculum and instruction. Many would then ask how, if we disregard test scores, we can tell if gains are being made in curriculum and instruction? The answer to that question is simple and cuts directly to the core of the beliefs of The Standards Company: direct measurement of curricular materials and teaching based on objective criteria. I would rather judge the teaching taking place in Mississippi or Kansas based on the levels of Bloom’s taxonomy and depth of knowledge appearing in their curricular materials than on student testing proficiency. After all, as a teacher I can control the curriculum I deliver to my students and the strategies I use to teach them.

I made big gains in my understanding of XSLT. One of my biggest stumbling blocks was how to reference bibliography entries cited in one document that referred to a bibliography file. For example, if one had the following LaTeX file main.tex

% main.tex

I am citing Andrew Porter\cite{Porter2004} and Norman Webb.\cite{Webb2007}

The (shortened) bibliography file would look something like:

@BOOK{Porter2004,
AUTHOR = “Porter, A.”,
TITLE = “The Enacted Curriculum”,
YEAR = 2004
}

@BOOK{Webb2007,
AUTHOR = “Webb, N.”,
TITLE = “Depth of Knowledge”,
YEAR = 2007

}

Since the citation of Porter appears first in the text, then it will be denoted as the first citation; the Webb citation would appear as the second. The result would be:

I am citing Andrew Porter[1] and Norman Webb[2].

Notice the numbering scheme: The number 1 is attributed to the first citation that appears in the main text body, not the order in which the entries appear in the bibliography. (This requirement is still giving me some trouble in XSLT.)

To introduce a citation system along these lines, we rely on the count() command in XSL, specifically count(preceding-sibling::attribute_name). This will count the number of sibling elements that correspond to the attribute attribute_name. Let’s take a look at a simple bibliography XML file called bibliography.xml.

<bibliography>
<title>REFERENCES</title>
<biblioentry id=”Webb2007″>Webb, Norman, et al.</biblioentry>
<biblioentry id=”Porter2004″>Porter, Andrew, et al.</biblioentry>
<biblioentry id=”Walkup2000″>Walkup, John, et al.</biblioentry>
<biblioentry id=”Brown1999″>Brown, John</biblioentry>
</bibliography>

Now these entries must be called in another document (which will be the primary document as far as the XSLT stylesheet is concerned), which we will call main.xml.

<para>
We will cite Andrew Porter(<bibref xref=”Porter2004″/>) and Norman Webb(<bibref xref=”Webb2007″/>).
</para>

Here is the XSL stylesheet that will perform the citations:

<xsl:variable name=”secondary_document” select=”document(’bibliography.xml’)”/>

<xsl:template match=”bibref”>
<xsl:variable name=”xref” select=”@xref”/>
<xsl:for-each select=”$secondary_document//bibliography/bibliomixed”>
<xsl:if test=”@id = $xref”>
<xsl:value-of select=”count(preceding-sibling::bibliomixed)+1″/>
</xsl:if>
</xsl:for-each>
</xsl:template>

The result is

We will cite Andrew Porter(2) and Norman Webb(1).

Notice that the reference numbers refer to the place in which the bibliography entries appear in the bibliography file, not the order in which they are cited. This is unfortunate, and something I need to look into further.

As with our examples of using keys, the <xsl:for-each> command forces the stylesheet to open and look into the secondary document, which in this case is bibliography.xml.

If we wanted to cite the entries with the APA style, there is a good (and hard) way to do it, and a cheap (but easy) way to do it. Simply create a node called <abbrev> for each entry and stuff inside it the text that you would want to appear in the output.

Here is the modified version of bibliography.xml.

<bibliography>
<title>REFERENCES</title>
<biblioentry id=”Webb2007″><abbrev>Webb2007</abbrev> Webb, Norman, et al.</biblioentry>
<biblioentry id=”Porter2004″><abbrev>Porter2004</abbrev> Porter, Andrew, et al.</biblioentry>
<biblioentry id=”Walkup2000″><abbrev>Walkup2000</abbrev>Walkup, John, et al.</biblioentry>
<biblioentry id=”Brown1999″><abbrev>Brown1999</abbrev>Brown, John</biblioentry>
</bibliography>

Now we will replace our earlier call to the count() command and simply print the text within the <abbrev> node. That is,

<xsl:if test=”@id = $xref”>
<xsl:value-of select=”abbrev”/>
</xsl:if>

The result is

We will cite Andrew Porter(Porter2004) and Norman Webb(Webb2007).

Probably the most frustrating search this year has been my quest to find a good discussion on using keys in multiple source documents. Let me explain.

Keys are used to “tag” certain elements so that they can be referenced later. In a way, the <xsl:key> command functions like the \label{ } command in LaTeX. To call on a key (in LaTeX, that would be similar to the \ref{ } command), one uses key( ).

\section{Introduction}
\label{intro}

\section{Theory}

This is a reference to Sec.\ \ref{intro}.

So in essence:

<xsl:key> -> \label{}
key() -> \ref{}

Note that in LaTeX, the arguments of both \label{} and \ref{} are the same if they reference the same item. So if a section of text is labeled, say, “intro” then the label declaration would be \label{intro} and the call to the section would be \ref{intro}. LaTeX generates an automatic number and substitutes it for the \ref{} call when it compiles the code.

The way the <xsl:key> command treats its arguments differs. The first glaring difference is that the source code of XML does not contain the key definitions, unlike LaTeX. In LaTeX, it would be similar to using the \label{} and \ref{} as arguments of the compiler call, telling the compiler what parts of the document the \label{} command defines and where the \ref{} command is called. Just to define the \label{} command alone would require something like the following in LaTeX: $latex -label{intro} at section{1}, subsection{2} (This won’t work, so don’t try it).

Let’s look at a sample XSL document that marks up two XML source documents:

<xsl:variable name=”StatesLookup” select=”document(’key_state.xml’)”/>
<xsl:key name=”StateKey” match=”state” use=”@sid”/>
<xsl:template match=”customer”>
<xsl:variable name=”custstate” select=”@stateid”/>
<xsl:variable name=”custname” select=”.”/>
<xsl:for-each select=”$StatesLookup”>
<xsl:value-of select=”$custname”/> lives in <xsl:value-of select=”key(’StateKey’, $custstate)”/>
</xsl:for-each>
</xsl:template>

Here is the first (primary) XML source document:

<customers>
<customer stateid=”03″>Bo</customer>
<customer stateid=”01″>Ty</customer>
<customer stateid=”02″>Jo</customer>
</customers>

Here is the second XML document:

<states region=”Midwest”>
<state sid=”01″>Iowa</state>
<state sid=”02″>Utah</state>
<state sid=”03″>Ohio</state>
</states>

Line 1 of the XSL file simply defines a variable to represent a call to the secondary document key_state.xml. So whenever we see a call to $StatesLookup we will be opening key_state.xml and peering in.

Line 2 defines the key we plan to use when marking up the two XML documents. It is strictly defined for elements of the secondary document key_state.xml, so at this point it functions like a \label{ } command placed inside a LaTeX section. The key pertains solely to any text element belonging to the @sid attribute/state element. In a way, defining the key is like creating a physical key to open all drawers of the file cabinet marked “state.” Each drawer is labeled individually “01,” “02,” and “03.”

Now that we have a key generated that will retrieve any of the text elements in the <state> elements, we have to have certain elements within the first XML (primary) document call on this key. We can’t insert the key( ) call within an XML document; key( ) commands are only found in XSL documents. Therefore, the key( ) is going to have to reference some portion of the primary XML document, which is why the key( ) command has two arguments: the first tells us which key we are using, the second tells us which element of the primary document is calling on the key. In line 7 of the XSL document, the call

key(’StateKey’, $custstate)

tells the style sheet to choose the key called StateKey and apply it to elements lying within the $custstate node, which is defined in Line 4. Since the stateid attribute has particular values for each <customer> element, these values get mapped into the key, thus referencing the appropriate element in the secondary XML document.

And it won’t just do this for the first element: The <xsl:for-each> command will apply the same key mappings for all elements in the <customers> node. In fact, the <xsl:for-each> command serves two purposes: It ensures that each element is processed and it shifts the target of the operations to the secondary document.

Tying it all together

So what does all this mean?

The key( ) command accepts two arguments: The first identifies the key and the second receives some value which is passed to the third argument of the <xsl:key> command, which then retrieves the corresponding value.

Next, I will need to learn how to generate automatic indexes.

My search for a utility that will allow me to reference one part of a document in another has zeroed in on the <xsl:key> command. Essentially, if for example I have a bibliography entry in one part of a document, and I need to reference that entry in another part, I need a utility that will permit it.

The easiest implemention I have found so far is a simplified version of the example found at http://nwalsh.com/docs/tutorials/xsl/xsl/foil68.html. It uses the following xml and xsl examples:

<?xml version=”1.0″ encoding=”UTF-8″?>

<doc>
<para>See <bibref>xyzzy</bibref>.
</para>
<biblio>
<bib abbrev=”xyzzy”>The Great Grue</bib>
<bib abbrev=”abcde”>That Alphabet Song</bib>
</biblio>
</doc>

<?xml version=”1.0″?>
<xsl:stylesheet version=”1.0″ xmlns:xsl=”http://www.w3.org/1999/XSL/Transform” xmlns:fo=”http://www.w3.org/1999/XSL/Format”>

<xsl:key name=”bibkey” match=”//biblio/bib” use=”@abbrev”/>

<xsl:template match=”doc”>
<xsl:apply-templates/>
</xsl:template>

<xsl:template match=”biblio”>
<!– suppressed –>
</xsl:template>

<xsl:template match=”para”>
<xsl:apply-templates/>
</xsl:template>

<xsl:template match=”bibref”>
<xsl:apply-templates select=”key(’bibkey’,string(.))”/>
</xsl:template>

</xsl:stylesheet>

Okay, I am getting a little perturbed at XSL book authors, and I will tell you when I get to my Daily Gripes section. For now, let me just say that this latest gripe centers on the use of static and flow inside a document.

Here is the code I am working with right now, which does not work.

<xsl:template match=”/”>
<fo:root>
<!– layout-master (page setup) –>

<fo:layout-master-set>
<fo:simple-page-master master-name=”body”>
<fo:region-body region-name=”portrait” margin-top=”20pt”/>
<fo:region-after region-name=”xsl-region-after” extent=”20pt”/>
</fo:simple-page-master>
</fo:layout-master-set>

<!– page sequence (containts page content) –>

<fo:page-sequence master-reference=”body”>
<fo:flow flow-name=”portrait”>
<fo:block>
<xsl:apply-templates/>
</fo:block>
</fo:flow>
<fo:static-content flow-name=”xsl-region-after”>
<fo:block>
Text
</fo:block>
</fo:static-content>

</fo:page-sequence>

</fo:root>
</xsl:template>

Why doesn’t this work? Apparently, piling the static content into the footer (called “xsl-region-after” in the above code) after having flowed content into the region body (”portrait”) is a no-no. The compiler complains “Static content… is not allowed after <fo:flow>. Neither of the two books I am referring to currently mention this.

Instead, the page-sequence section of the code needs to be something like this:

<fo:page-sequence master-reference=”body”>
<fo:static-content flow-name=”xsl-region-after”>
<fo:block>
Text
</fo:block>
</fo:static-content>
<fo:flow flow-name=”portrait”>
<fo:block>
<xsl:apply-templates/>
</fo:block>
</fo:flow>
</fo:page-sequence>

Now why does the static have to come before the flow? Not so sure yet.

I have learned another lesson the hard way: Nothing is going to happen unless the XSL template specifies some flow. I initially thought I could mock up a blank PDF template with a filled footer by removing the <fo:flow> call altogether, but no dice. No flow equates to “This program cannot display the webpage.” (We can remove the content between the <fo:block> calls and that would work fine, but we cannot remove the FO blocks altogether. No work-ee.

Let’s go back to the earlier XSLT document from my previous blog. For the purposes of this discussion, we will focus on only one page master for brevity. Note that in the example below, I have set the top margin to 20 points in two different locations: one in the page master declaration, and the other in the region body declaration.

<xsl:template match=”sales”>
<fo:root>
<!– layout-master (page setup) –>

<fo:layout-master-set>
<fo:simple-page-master master-name=”body” margin-top=”20pt”>
<fo:region-body region-name=”portrait” margin-top=”20pt”/>
</fo:simple-page-master>
</fo:layout-master-set>

<!– page sequence (containts page content) –>

<fo:page-sequence master-reference=”body”>
<fo:flow flow-name=”portrait”>
<fo:block>
<xsl:apply-templates select=”truck”/>
</fo:block>
</fo:flow>
</fo:page-sequence>

</fo:root>
</xsl:template>

The effects of the two margin spacings are cumulative: the resulting document has a 40 point top margin spacing. What is going on here? And since only one region body can be declared within a given page master, why would XSL allow a margin spacing command to be placed in both? Which is preferable? Is there ever any difference between one and the other?

Evidently, I need to explore this issue further, but later. I have gotten away from my earlier goal of understanding the relationship between template matches and FO layouts.

In many ways, XSL uses a fairly straightforward method for defining the manner in which text is “flowed” into a page. In other ways, I find it positively goofy (but more on that later).

Consider the following XSLT style sheet. I have dispensed with the usual XSLT boiler plate for brevity, so this snippet begins with the <xsl:template match=”table”> declaration (although that alone is a sore point with me, but more on that later.)

Also, I have not printed the contents of the corresponding XML page either, although I will mention that it contains a node element called <date>. At this point, we are not concerned about what is being printed, but rather how it is being processed. Note that there is one layout master defined (XSL won’t allow multiple layout masters), but two page masters.

<xsl:template match=”sales”>
<fo:root>
<!– layout-master (page setup) –>

<fo:layout-master-set>
<fo:simple-page-master master-name=”body”>
<fo:region-body region-name=”portrait” margin-top=”9pt”/>
</fo:simple-page-master>

<fo:simple-page-master master-name=”appendix”>
<fo:region-body region-name=”landscape” margin-top=”5pt”/>
</fo:simple-page-master>
</fo:layout-master-set>

<!– page sequence (containts page content) –>

<fo:page-sequence master-reference=”body”>
<fo:flow flow-name=”portrait”>
<fo:block>
<xsl:apply-templates select=”truck”/>
</fo:block>
</fo:flow>
</fo:page-sequence>

<fo:page-sequence master-reference=”appendix”>
<fo:flow flow-name=”landscape”>
<fo:block>
<xsl:apply-templates select=”date”/>
</fo:block>
</fo:flow>
</fo:page-sequence>

</fo:root>
</xsl:template>

I called one page master “body” (that is, the main body of the paper) and the other “appendix,” which correspond to two sections of a large-scale document that could require their own special treatment. I also called one region body “portrait” and the other “landscape,” although I am not sure why anyone would want an appendix typeset in landscape mode. Note that I have not declared anything in the “landscape” region body that would typeset it in landscape form, at least not yet.

From what I can tell so far, declaring a page master is similar to selecting certain attributes in the File/Page Setup command in Microsoft Word, or creating text boxes within Adobe InDesign. (I don’t think LaTeX has a similar functionality in this regard.)

The result of this transformation is to create two pages, with the contents of the <truck> element of the XML file spilling into the “body” page master on the first page and the “appendix” page master on the second page.

Now, here is what I don’t fully understand: Since page masters cannot contain more than one region body, then what is the purpose of naming the region body? Would the name of the page master not suffice since it has to be unique within the XSL template? In the examples I have seen in books, authors are ascribing the same name to the region body as to the page master, which seems only natural, but also superfluous.

Since layout masters can contain more than one page master, then why do authors avoid introducing this added sophistication in their books at the time the concept of the page master is being developed? To me, showing a layout master with two page masters, with each page master having a unique

Gripe of the day

I realize that computer book authors like to show off bells and whistles, but too much of it can get out of hand. For example, in the above code I only showed one change in the style format for each region body. Sure, I could have set the left margins, right margins, bottom margins, and so on, but what would that teach? I suggest showing one bell or whistle, then referring the reader to the others. This keeps the code simple and saves space.

The Luddite movement of the early 1800s offers lessons on company management. The increased use of modern textile machinery compelled some to form militant gangs opposed to their use, with the result of smashed equipment, beatings, and executions. The Luddites were wrong — there was, and still is, room for skilled craftsmen in today’s society. But given the environment they faced at the turn of the nineteenth century, it is easy to understand their fears. With all of their talent concentrated in a single skill (making textiles), their fears of being shoved aside were easy to understand.

It is never easy parting with that you feel comfortable or skilled doing. For many years (close to 15) I have been a staunch advocate of the typesetting software LaTeX, becoming quite proficient in programming in its environment to produce professional looking documents. LaTeX is an incredibly powerful typesetting utility that has its uses, especially in scientific and mathematical publication. Our first two state-wide contracts were garnered with proposals created in LaTeX, but it will not serve our needs at The Standards Company LLC much longer, except for special cases.

The software at The Standards Company is primarily based in XML, and that is the direction our company is pointed. The stylesheet language XSL offers many advantages over LaTeX, but none more important to my typesetting goals than its ability to post up raw data in a uniform, dynamic manner. So while LaTeX is what I am comfortable using, it is time to move on.

I am not altogether new to XML (my Director of Research, Ben Jones, lives and breathes it on an hourly basis), but typesetting XML documents using its style sheet companion XSLT is not something I am used to. But if that is what the company needs, then “very well.” To do otherwise is to apply for membership to the Luddites, an option our company does not offer.

Knowing LaTeX has helped me learn to typeset in XSLT. My experience with Adobe InDesign has helped too. Both incorporate the same structure — the use of box and inline structure to flow text into pre-defined regions of the page.

You may be wondering about our company’s position on Microsoft Word. Well, Word is great for letters and small documents. That’s about it. For a grant or RFP response, we would just as soon use a hammer and chisel.

In the future, I plan to post some of my own tutorials on XSLT as I learn it, especially the way this style/markup language relates to LaTeX and InDesign.

Gripe of the day

Example XML documents appear in every tutorial, but authors are often careless in their creation of example XML documents. One problem I see is to use sample XML code as text entries in the example. (See Listing 9.1 in Lovell, D. XSL: Formatting Objects, SAMS, 2003.)

Another mistake is to create XML example documents that are too long and complex. Not only does this make discerning elements from the document difficult, it takes a long time to type in the example text in one’s own files. I realize that some of you XSL authors like Shakespeare, but is there a real good reason to use a three-page XML example of a Shakespearean sonnet when a half-page example will do?

To me, the best example XML files are ones that have limited text, but just enough sophistication in the hierarchy to give flexibility to the discussion. For example:

<sales year=”1980″>
<car>
<ford plate= “2XMP”> Taurus </ford>
<chevy plate= “3YE”> Cavalier </chevy>
<dodge plate=”8EY”> Charger </dodge>
</car>
<truck>
<ford plate= “1YU”> Bronco </ford>
<chevy plate= “1TY”> Tahoe</chevy>
<chevy plate= “2ZX”> Tahoe</chevy>
</truck>
</sales>

This example XML file has all the sophistication one needs to show off the capabilities of XSL, and none of the elements can be confused with XML or XSL nomenclature. (Note: I had used “Silverado” earlier, but replaced it with “Tahoe” to save space. I also trimmed the plate numbers to three characters. The smaller the sample text, the better.) Note the repeating <chevy> element under the <truck> parent. Note also that the <car> and <truck> elements share the same child elements.