<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
          "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
   <title>Teach the Tech or Teach the Tools?</title>
   <link href="../main.css" rel="stylesheet" type="text/css">
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
   <style type="text/css">
      /* Styles for the Zotero classes and my annotation class */
      .csl-bib-body {
         line-height: 1;      /* the default, but MLA normally uses 2 */
         padding-left: 2em;
         text-indent: -2em;   /* hanging indent */
      }
      .csl-entry {
         font-size: 115%;
      }
      .annotation {
         font-size: 95%;
         margin-bottom: 2em;
         text-indent: 0;
      }
      .annotation h3 {
         font-size: 93%;
      }
   </style>
</head>

<body>
<div id="container" style="width: 1100px">
   <div id="header">
      <h1 class="banner"><a class="banner" href="/">ideoplast.org</a></h1>
      <h2 class="banner">milling ideas since 1968</h2>
   </div>

   <div id="pagename" class="sidebar">
      <ul>
         <li>T</li>
         <li>e</li>
         <li>c</li>
         <li>h</li>
         <li>&nbsp;</li>
         <li>o</li>
         <li>r</li>
         <li>&nbsp;</li>
         <li>T</li>
         <li>o</li>
         <li>o</li>
         <li>l</li>
         <li>s</li>
      </ul>
   </div>

   <div id="content">

      <h1>Teach the Tech or Teach the Tools?<br>
          <span class="subtitle">An annotated bibliography</span></h1>

      <p>
         With the annotated citations below I am attempting to capture
         at least some of the published conversation from the past
         decade or so around an issue which has proven rather durable
         in both "new media" composition pedagogy and professional
         writing. It can be seen a classic example of computing's
         religious wars (though rather more muted in academia than
         among the populace of general practitioners); or as the old
         tussle between scientific and romantic perspectives carried
         over into web design; or simply as a specific case of the
         ubiquitous question, for tool-using creatures, of how abstract
         we may properly make our tools &mdash; when we can allow them
         to be black boxes, and when their surfaces must be transparent
         and their inner workings revealed to their users.
      </p>

      <p>
         That debate is the question of whether content creators for
         the web should have a thorough understanding of the technologies
         they use &mdash; HTML, CSS, and so forth &mdash; or whether
         it's acceptable for them to deal with those technologies (the
         "tech") indirectly and even in blissful ignorance of the details
         of their specifications and implementations, through higher-level
         software (the "tools") which presents a more abstracted view,
         often an ostensibly WYSIWYG one, of the material.
         I've framed this here primarily as a pedagogical question (hence
         "teach the tech", etc.), to give it a practical gloss rather
         than an ethical one &mdash; that is, I want to avoid letting
         the discussion degenerate into contention over the sins, real
         or imagined, of established practictioners. Casting it as a
         pedagogical choice lets us see it in terms of future options
         rather than present errors. But in reality this makes little
         difference to the main issue, because practitioners learn their
         craft somehow, and presumably we want pedagogy to reflect what
         we believe are best practices.
      </p>

      <p>
         Of course as with all religious wars there is not likely to be
         a single satisfactory answers. There are any number of possible
         pat responses ("horses for courses", for example, or "the proof
         of the pudding is in the eating" &mdash; the right approach
         depends on contingencies of the situation, or the approach can
         only be justified by the outcome), but those lead to little
         useful insight. Similarly, there will be those who take a hard
         stance somewhere in the field and defend it against all comers;
         while that often does result in some interesting ideas, it moves
         us no closer to better action. Thus having reviewed these
         sources I now believe it is important to continually maintain a
         reflective and critical stance of any position on a question
         like this one; to both hold some (hopefully informed and
         sophisticated) beliefs about what makes for good web pedagogy
         and practice, and to continually review those beliefs in each
         new situation. We must remember that continual ideological
         vigilance is impossible and undesirable, and that all of us
         must work at multiple levels of abstraction. No one can consider
         simultaneously and continuously all of the interwoven technologies 
         that go into building, serving, retrieving, and rendering web
         content &mdash; to say nothing of imagining and interpreting it.
         And by the same token, no web content is ever entirely original;
         we do not mint our own bits.
      </p>

      <h2>Summary of the Conversation</h2>

      <p>
         Early in this project I posted a query to the
         <a href="http://www.interversity.org/lists/techrhet/subscribe.html"
            >TECHRHET</a>
         listserv, asking about sources on this question that subscribers
         particularly liked or felt should not be missed. At least one
         person noted that it would likely be hard to find academics
         arguing for the "teach the tools" position. And indeed I found
         far more arguments for the tech side. There are likely several
         reasons for this. One is that the tools are, at first glance,
         the easier option; certainly they let students produce their first
         work faster, they provide more integrated assistance, they offer
         instructors consistency, and they're more visually appealing
         to most users. Thus they largely make their own argument and
         there's little reason for an instructor to advocate on their
         behalf. More than that, though, academics are professional
         knowers of things, and what we might call the "code layer" of
         web documents is an ideal object of academic knowledge. It
         sits beneath the visible surface and determines much of that
         surface; it follows its own obscure rules; it takes the form
         of an argot for initiates. It's the hermeneutic filling in
         web-design cake.
      </p>

      <p>
         Nonetheless, some academics do admit &mdash; often somewhat
         guiltily &mdash; that exigencies have forced them to rely on
         tools in the classroom. Sometimes that is because the
         instructors themselves lack the leisure to become experts in
         the technology. In other cases, it's because employment-oriented
         students insist on learning whatever is popular in the
         workplace, or because instructors believe that training students
         for the workplace is the correct ethical choice. (I hardly
         need note that this is a question of long tradition itself.)
         Or the course schedule may simply not have the time required to
         teach this material to students, many of whom are likely to
         find it rather alien and difficult.
      </p>

      <p>
         It's worth noting, I think, that tool-based production is
         certainly in demand in the industry, as is training for it.
         The Association for Computing Machinery recently noted that
         its introductory course on Dreamweaver &mdash; likely the best-known
         WYSIWYG web authoring tool &mdash; is the ACM's most popular
         offering in its "Graphic Design" series ("ACM Member Technical
         Interest Service" email newsletter, February 2011). Since the
         ACM is a technical organization that caters to coders and
         scientists, this is not insignificant; it's likely that many
         ACM members, perhaps a majority, would disdain Dreamweaver
         and other WYSIWYG tools on principle.
      </p>

      <h2>Bibliography</h2>

      <div class="csl-bib-body">

         <!--
            Following PHP code is amateurish. It should be refactored into
            decent OO code, with sensible method breakdown, error handling,
            etc. It might also make sense to use a class such as Tidy to
            generate an HTML DOM tree for the Zotero report document, to
            process it in a sensible way.
         -->

         <?php
            /*
               Pull notes from the Zotero report document, associating
               them with bibliographic entries by a key formed from
               author and title. Implemented using a simple state machine.
            */

            $matches = array();
            $notes = array();

            define("START", 0);
            define("IN_ENTRY", 1);
            define("AUTHOR_ROW", 2);
            define("IN_NOTE", 3);
            $state = START;
            $notestream = fopen("bibliography.html", "r");
            while ($noteline = fgets($notestream))
            {
               // Check to see if we have a note and entry
               if (preg_match("/^[ \t\r\n]*$/", $noteline) && $state != START)
               {
                  //echo "<p>author is \"${author}\"</p>\n";
                  //echo "<p>title is \"${title}\"</p>\n";
                  $key = $bibkey? $bibkey : preg_replace
                     ("/[^a-z]/", "", strtolower($author . $title));
                  //echo "<p>insertion key is \"{$key}\"</p>\n";
                  if ($note != "") $notes[$key] = $note;
                  $state = START;
                  continue;
               }

               switch ($state)
               {
                  case START:
                     $title = ""; $author = ""; $note = ""; $bibkey = null;
                     if (preg_match("/ id=.*class=\"item /", $noteline))
                        $state = IN_ENTRY;
                     break;
                  case IN_ENTRY:
                     // echo "<p>IN_ENTRY</p>\n";
                     if (preg_match("/<h2>/", $noteline))
                     {
                        // Take up to 20 chars of title
                        if (preg_match
                              ("/<h2>(.{0,20}).*<\/h2>/", $noteline, $matches))
                           $title = $matches[1];
                     }
                     else if (preg_match
                                 ("/ class=\"(presenter|author)\"/", $noteline))
                     {
                        $state = AUTHOR_ROW;
                     }
                     else if (preg_match("/ul class=\"notes\"/", $noteline))
                     {
                        $state = IN_NOTE;
                     }
                     break;
                  case AUTHOR_ROW:
                     // echo "<p>AUTHOR_ROW</p>\n";
                     if (preg_match("/<td>/", $noteline))
                     {
                        // Take last word of author
                        if (preg_match
                              ("/<td>.* ([^ ]*)<\/td>/", $noteline, $matches))
                           $author = $matches[1];
                        $state = IN_ENTRY;
                     }
                     else if (preg_match("/<\/tr>/", $noteline))
                     {
                        $state = IN_ENTRY;
                     }
                     break;
                  case IN_NOTE:
                     // echo "<p>IN_NOTE</p>\n";
                     // Accumulate everything except <li> or bibkey
                     if (preg_match("/<\/li>/", $noteline))
                     {
                        $state = IN_ENTRY;
                     }
                     else if (preg_match
                                ("/<p>bibkey:(.*)<\/p>/", $noteline, $matches))
                     {
                        $bibkey = $matches[1];
                     }
                     else if (! preg_match("/<li id=/", $noteline))
                     {
                        $note .= $noteline . "\n";
                     }
                     break;
               }
            }

            /*
               Build a list of regular expressions and replacement text
               to clean up the input lines.
            */

            $patterns = array();
            $replacements = array();
            $patidx = 0;
            function addReplacement($pat, $rep)
            {
               global $patterns, $replacements, $patidx;
               $patterns[$patidx] = $pat;
               $replacements[$patidx] = $rep;
               $patidx++;
            }

            /*
               Zotero MLA-with-URL style puts "Print." at the end of every
               entry that doesn't have a URL. Get rid of that.
            */
            addReplacement("/ Print\./", "");

            // Change Unicode "smart quotes" to HTML quote entities
            addReplacement("/\xe2\x80\x9c/", "&ldquo;");
            addReplacement("/\xe2\x80\x9d/", "&rdquo;");

            // Change the three-hyphens same-author leader to a continuous line
            addReplacement("/---\./", "&ndash;&ndash;&ndash;.");

            // Make links out of URLs
            addReplacement("/&lt;(http:\/\/.*?)&gt;/",
                           "&lt;<a href=\"$1\">$1</a>&gt;");

            /*
               Now read the exported bibliography file, pulling out the actual
               entries (all of which are conveniently single lines which
               contain just a div with the "csl-entry" class), performing our
               replacements, and adding them to this document.
            */
            $author = "";
            $lastauthor = "";
            $title = "";

            $bibstream = fopen("mla-with-url.html", "r");
            while ($bibline = fgets($bibstream))
            {
               if (preg_match("/class=\"csl-entry\"/", $bibline))
               {
                  // Extrace author-title key for note retrieval
                  if (preg_match("/<[^>]*> *([^,.]*)/", $bibline, $matches))
                     $author = $matches[1];
                  if (preg_match
                        ("/[^.]*\.[^a-zA-z]*([^.]{0,20})[^.]*\./",
                         $bibline, $matches))
                     $title = $matches[1];
                  if ($author == "---")
                     $author = $lastauthor;
                  else
                     $lastauthor = $author;
                  $key = preg_replace
                     ("/[^a-z]/", "", strtolower($author . $title));
                  if (array_key_exists($key, $notes))
                     $note = $notes[$key];
                  else
                     $note = "<p>No annotaion for retrieval key \"{$key}\"</p>";

                  // Perform replacements and emit bibliography line
                  $bibline = preg_replace($patterns, $replacements, $bibline);
                  echo "{$bibline}\n";

                  // Emit note details, if any
                  if ($note)
                  {
                     echo "<div class=\"annotation\">\n"
                        , "{$note}\n"
                        , "</div>\n";
                  }
               }
            }
            fclose($bibstream);
         ?>

      </div>

      <h2>Appendix: Implementation Details</h2>
      <p class="notice">
         This section is purely for nerds who want to know how this page
         was constructed. Others may go do something productive.
      </p>

      <p>
         This annotated bibliography page was constructed from materials
         exported from my Zotero database, processed by a PHP script.
         Zotero currently has no support for doing proper annotated
         bibliographies (one of the most-requested features, but apparently
         difficult to implement due to architectural infelicities). I
         cobbled this system together in order to use Zotero for research
         and writing the annotations. It's not fancy and makes no effort
         to be user-friendly (but then, neither do I), but for this project
         it worked.
      </p>

      <p>
         Here's the process and tool chain:
      </p>
      <ul>
         <li>
            I collected items for this bibliography in Zotero, and organized
            them in a Zotero folder so I could export just the ones that
            applied to the bibliography.
         </li>
         <li>
            I created the annotation for each item as a Zotero note. There
            has to be no more than one note per item, and if an item doesn't
            have a note you'll get an "annotation" complaining about the
            lack of an annotation.
         </li>
         <li>
            I created a Zotero "report" from the bibliography folder, and
            saved the resulting HTML page as
            <a href="bibliography-source.html"><tt>bibliography.html</tt></a>.
            (Input filenames are hard-coded in the PHP script, so it must
            have this name, and it must be located in the same directory as
            the PHP script on the server.) The Zotero report includes the
            annotation notes.
         </li>
         <li>
            I exported the bibliography folder using the Zotero "MLA with
            URL" style, as
            <a href="mla-with-url-source.html"><tt>mla-with-url.html</tt></a>.
            This file contains the actual bibliography entries, without
            annotations, and with some enveloping HTML that will be discarded
            by the PHP script.
         </li>
         <li>
            All these files get uploaded to the server. (I also run a script
            that creates the pretty-printed "source" versions of the HTML and
            PHP files, for your edification.)
         </li>
         <li>
            The PHP script,
            <a href="tech-or-tools-source.html"><tt>tech-or-tools.php</tt></a>,
            is run each time the bibliography is retrieved from the server.
            It would be more efficient for me to run it as part of the build
            process and upload the HTML output; but it's not worth the extra
            effort on my part, since it runs quite quickly.
         </li>
         <li>
            The PHP file begins with a short embedded stylesheet. This imposes
            some styles that clean up the Zotero MLA-style bibliography output,
            and otherwise style bibliogrpahy entries appropriately. (Most of
            the styling for the page comes from my site-wide stylesheet.)
            It continues with the first user-visible content, the static
            content of the header, sidebars, and bibliography preface.
         </li>
         <li>
            Then the real work begins. First the script reads
            <a href="bibliography-source.html"><tt>bibliography.html</tt></a>,
            processing entries using a regular-expression-based lexical
            analyzer and a simple state-machine parser. For each entry it
            computes an "entry key" from the author and title information,
            and extracts the annotation. Annotations go into an associative
            array indexed by entry key.
         </li>
         <li>
            While processing the annotation, if the script finds a line
            that begins with "<tt>bibkey:</tt>", it takes the next word as
            the entry key (overriding the one it computed from author and
            title) and discarding the line. This is necessary to get
            annotations to match with bibliography entries later, if the
            bibliography entry is complicated&mdash;for example, if there's
            more than one author. That's because the Zotero report format
            is quite different from the MLA bibliography format, and it's
            not trivial to figure out how to compute the same entry key for
            the two formats when the bibliographic data isn't simple.
            <p>
            Note
            this also means that I have to generate the bibliography, look
            to see what annotations it couldn't match with the corresponding
            entries, and manually add the appropriate <tt>bibkey:</tt> lines
            to those annotations. That's one reason why this system isn't
            production-quality.
         </li>
         <li>
            When the PHP script has processed the report file, it moves on to
            the Zotero exported bibliography file
            (<a href="mla-with-url-source.html"><tt>mla-with-url.html</tt></a>).
            It reads that line-by-line, performing a number of edits driven
            by regular expressions:
            <ul>
               <li>
                  The MLA style puts "Print." at the end of every print
                  entry; I delete that nonsense.
               </li>
               <li>
                  I change Unicode quotation characters to HTML quotation
                  entities. This avoids infelicities with character encodings,
                  and looks better in the source.
               </li>
               <li>
                  I change the "---" notation used for multiple works by the
                  same author to a solid line.
               </li>
               <li>
                  I wrap displayed URLs in hyperlinks.
               </li>
            </ul>
         </li>
         <li>
            The script looks for an annotation that corresponds to the key it
            generates for this entry.
         </li>
         <li>
            The script then adds the entry and annotation to the HTML output
            stream, and goes on to the next entry in the bibliography.
         </li>
         <li>
            Finally, the script ends the main body text. The script file
            concludes with static content: this appendix, the footer, etc.
         </li>
      </ul>

      <p>
         And <i>that's</i> how we do things at ideoplast.org. Or at least
         that's how we do things for this particular page. I've built other
         bibliography systems for other classes that are also hosted on 
         this site, including the
         <a href="/apps/multibib/recent.php">MultiBib</a>
         application and the ad hoc tool chain used to produce my
         "Used Without Permission"
         <a href="/wra417/used-without-permission.html">improprietography</a>.
         No hobgoblin consistency here.
      </p>

      <p>
         You can download
         <a href="sources.zip">the sources for this system</a>,
         if you want the them for some unguessable reason. My usual
         <a href="/license.html">license</a>
         (do whatever you want, blah blah blah) applies.
      </p>

   </div>      <!-- end main content -->

   <div id="footer">
      <div id="leftfoot">
         <p>
            Copyright &copy; 2011
            <a href="mailto:mwojcik@newsguy.com">Michael Wojcik</a>.
            See the <a href="/license.html">license page</a>
               for more information.
         </p>
      </div>
      <div id="rightfoot">
         <ul>
            <li><a href="http://www.w3.org/TR/1999/REC-html401-19991224/">HTML 4.01</a></li>
            <li><a href="http://www.w3.org/TR/CSS21/">CSS 2.1</a></li>
         </ul>
      </div>
   </div>

</div>
</body>
</html>