Caveat Lector

I don’t want to admit how long it took me to get this right. Weeks. A small glitch elsewhere in the stylesheet that would occasionally throw a wobbly and occasionally not did not help matters. (Have I mentioned that debugging XSLT server-side is an inordinate pain in the posterior? I haven’t? Well, it is.)

Still. If you hate as much as I do that community and collection logos live inside the community/collection box and not in the h1 of the page the way $DEITY intended, read on.

I actually had to comment out the ds-logo-wrapper bit in DS-METS-1.0-DIM.xsl, because nothing I did in my theme seemed to override it. The other sneaky way to dispense with it is to set it to display:none in your CSS.

For our first trick, we will fossick around in the METS and the DRI to determine whether there’s a logo at all, and whether we’re actually on a community or collection page. Add the following variables to the top level of your theme’s stylesheet (look for the context-path variable and put them beside those):

<!-- Whether the current page has a logo associated with it. -->
    <xsl:variable name="has_logo" select="boolean(/dri:document/dri:meta/dri:objectMeta/dri:object/mets:METS/mets:fileSec/mets:fileGrp[@USE='LOGO'])”/>

<!–  Whether the current page is a community or collection home page. –>
     <xsl:variable name=”is_comm” select=”boolean(/dri:document/dri:body/dri:div[@n='community-home'])”/>
    <xsl:variable name=”is_coll” select=”boolean(/dri:document/dri:body/dri:div[@n='collection-home'])”/>

Next, we will go into the template where we want the logo to live and add this to it:

<xsl:if test="$is_coll or $is_comm">
  <img>
    <xsl:attribute name="src">
      <xsl:value-of select="/dri:document/dri:meta/dri:objectMeta/dri:object/mets:METS/mets:fileSec/mets:fileGrp[@USE='LOGO']/mets:file/mets:FLocat[@LOCTYPE='URL']/@xlink:href”/>
    </xsl:attribute>
    <xsl:attribute name=”class”>logo</xsl:attribute>
    <xsl:attribute name=”id”>commcollogo</xsl:attribute>
    <xsl:choose>
      <xsl:when test=”$is_comm”>
        <xsl:attribute name=”alt”>xmlui.dri2xhtml.METS-1.0.community-logo-alt</xsl:attribute>
        <xsl:attribute name=”attr” namespace=”http://apache.org/cocoon/i18n/2.1″>alt</xsl:attribute>
      </xsl:when>
      <xsl:when test=”$is_coll”>
        <xsl:attribute name=”alt”>xmlui.dri2xhtml.METS-1.0.collection-logo-alt</xsl:attribute>
        <xsl:attribute name=”attr” namespace=”http://apache.org/cocoon/i18n/2.1″>alt</xsl:attribute>
      </xsl:when>
    </xsl:choose>
  </img>
</xsl:if>

There is an additional wrinkle if (as I did) you want the logo to live in the ds-div-head with the community’s name in it. For this, you need to test whether a given head on the page is an h1, or you’ll get the damn logo on every head on the page. (Yep. I made that mistake.)

The fix is relatively easy; just change the xsl:if line above to <xsl:if test="$head_count=1 and ($is_coll or $is_comm)"> and you’re golden.

I hope somebody else uses this. Figuring it out drove me crazy for weeks.

So the new DSpace Foundation wants people with plain-vanilla DSpace installations to chime in and say how long it took ’em to get set up.

Plain-vanilla? I said. Who the heck stops at plain vanilla? Why is that even a useful benchmark?

Naughty Dorothea, no biscuit. (Note to SourceForge: friendly URLs for mailing-list threads, plzkthx.) “Given your experience, passion and know how it would be great if you could work with us in a positive fashion,” quoth the Foundation’s head honcho.

I don’t even know what to say about this, it’s so goofy. Except to note that I do believe there’s a bit of a gender issue lurking, as I’ve never seen a male participant called out for anything by anyone except when I’ve done it myself—good old unladylike me.

I’m willing to stand on my record vis-a-vis DSpace: even if we leave all my snark and criticism aside as wholly unproductive (which I dearly hope is arguable!), I’ve couple-three patches, two extremely successful customization workshops (and wikifying the handouts to boot), a number of how-to blog posts, and some mailing-list answers to my credit. That’s all I need to say, really.

One of the (sadly few) nice things that DSpace’s JSP interface did was call out the link for the page you happened to be on in the navigation sidebar. The magic was a class attribute on the current page’s link, plus a bit of CSS.

Manakin doesn’t do that out of the box. But it can, and I just spent entirely too much time making it do so. Y’all get the benefit of my cussing streak.

The first trick is to figure out just what the address of the current page is. Go up to the top level of your theme’s XSLT stylesheet and add this:

<xsl:variable name="currentpage">
  <xsl:value-of select="$context-path"/>
  <xsl:text>/</xsl:text>
  <xsl:value-of select="/dri:document/dri:meta/dri:pageMeta/dri:metadata[@element='request' and @qualifier='URI']“/>
</xsl:variable>

(Incidentally, could somebody with more XSLT-fu than I have kindly explain what the difference is between dri:metadata[@element='request' and @qualifier='URI'] and dri:metadata[@element='request'][@qualifier='URI']? I know there is one, because it keeps tripping me up.)

Now you need your <dri:xref> transformation to take notice. Here’s how it works:

<xsl:template match="dri:xref">
  <a>
    <xsl:attribute name="href"><xsl:value-of select="@target"/></xsl:attribute>
      <xsl:if test="($currentpage)=(@target)">
        <xsl:attribute name="class">
          <xsl:text>current</xsl:text>
        </xsl:attribute>
      </xsl:if>
    <xsl:apply-templates />
  </a>
</xsl:template>

And then you may style at will.

This only works for side navbar links. It doesn’t currently work for the alphabet links at the top of browse-by pages, because they’ve got parameters attached. (If I recall correctly, there may be some URL-space rearrangements in current Manakin versions that might fix this.) Happy designing!

The default Manakin install, just so you know, doesn’t put subject terms on the short item-display page. It’s not hard to add them back, and I recommend it; you’ll see what I did with them in a moment.

Making authors and subjects clickable is a bit trickier. Up-front warning: what I’m about to show you is apparently not in line with the latest version of Manakin, but if you get the idea, making the necessary fixes won’t be hard.

The first problem is that the names need to be URL-encoded or browsers will break amusingly. This leads to the second problem, which is that XSLT 1 doesn’t have a built-in URL encoder. Fortunately, Cocoon does, and you can enable it for your Manakin themes. In your main sitemap.xmap file, add the following just below the root <sitemap:xmap> element:

<map:components>
  <map:transformers>
       <map:transformer name="encodeURL"
src="org.apache.cocoon.transformation.EncodeURLTransformer"/>
  </map:transformers>
</map:components>

Then, between Steps 4 and 5 of the <map:pipeline>, add:

<map:transform type="encodeURL"/>

URL encoding problem solved. (Note: if you mouse over links with this working, they don’t look encoded—that’s okay, everything still works.)

Now you need to go into your theme’s XSLT stylesheet and look for the <xsl:template> with the name “itemSummaryView_DS-METS-1.0-DIM”. If it’s not there, go into DS-METS-1.0-QDC.xsl, find it there, and copy it into your theme’s stylesheet.

After breaking things amusingly several times, I found out what works. Note carefully that I am not using Manakin-default table markup for metadata, because I despise table markup. I’m using definition lists instead, and I’ve made them look like tables with CSS. (Hell, my metadata display is prettier than WorldCat’s. Right-justify your labels, people! It helps the eye.)

<xsl:if test="$data/dim:field[@element='subject']“>
<dt><xsl:text>Subject(s):</xsl:text></dt>
<dd>
  <xsl:for-each select=”$data/dim:field[@element='subject']“>
    <a>
      <xsl:attribute name=”href”>
        <xsl:value-of select=”concat($context-path,’/browse-subjects?subject=’)”/>
        <xsl:copy-of select=”text()”/>
      </xsl:attribute>
      <xsl:copy-of select=”text()”/>
    </a>
    <xsl:if test=”count(following-sibling::dim:field[@element='subject']) != 0″>
<xsl:text>; </xsl:text>
        </xsl:if>
  </xsl:for-each>
</dd>
</xsl:if>

Taking that a bit at a time… frankly, you should wrap all your metadata declarations in <xsl:if> statements as I just did, because otherwise they will show up in Manakin whether they actually have values or not! This is just silly.

I put the bare text “Subject(s)” in the code instead of doing something in messages.xml for it. This is bad, it will be fixed, and you should not do it. Use messages.xml instead.

The rest works out to “for each subject, put a link to the corresponding browse-by-subject page, and add a semicolon and space if it’s not the last subject in the list.” It doesn’t take a whole lot of XSLT-fu to see how it works.

This works just as nicely for authors, and I’ve got that enabled too. (I’ve also split out real authors from advisors, translators, editors, etc. in the code. This took a little doing, and may be worth a separate post.) You can do it too—have fun!

(I posted a lengthy polemic to the DSpace-Tech mailing list in response to a gentle question about projected DSpace support for electronic theses and dissertations. I think the content is relevant to more than just the DSpace community, so I reproduce it here, with an added link or two.)

With the understanding that I’m not a DSpace committer and not involved in any way with DSpace or the DSpace Foundation except as DSpace user and occasional bug or patch submitter…

My sense is that DSpace development has only vaguely and loosely been guided by real-world use cases not arising from its inner circle of contributing institutions. E.g., repeated emails to the tech and dev lists concerning metadata-only deposits (the use case there generally being institutional-bibliography development), ETD management, true dark archiving, etc. etc. have not been answered by development initiatives, or often by anything but “why would you even want that?” incomprehension or “just hack it in like everybody else!” condescension.

There are hacks for some of these uses, yes… but from a sysadmin’s perspective, hacks endanger smooth upgrade paths, and from the perspective of many librarians, hacks are entirely out of reach because IT rather than the librarian controls the box DSpace lives on.

When innovation has occurred around DSpace, it has generally died on the vine because of the aforementioned threat to smooth upgrade paths. TAPIR and Researcher Pages may serve as the requisite gruesome warnings here; they died not because the ideas underlying them were bad (they emphatically weren’t! if we still had TAPIR, Susan wouldn’t have had to ask the question she just did!), but because almost nobody dared adopt them. I see all kinds of nifty conference presentations involving DSpace mods — but they provide me no practical benefit whatsoever, because the code isn’t out there and I probably couldn’t use it if it were!

DSpace’s lack of a plugin/mod API, coupled with the amazing spaghetti dinner under its hood, has stifled service innovation in the repository space for years, and will continue to do so until the defect is rectified. Neither EPrints nor Fedora is in a much better position just now, but in all honesty, I predict that the first platform to have a half-decent mod API (especially one that welcomes mods written in friendlier languages than Java) will experience an explosion of innovations that will eat the other platforms’ lunch. Manakin assuredly helps, but not quite enough.

SWORD may also help, rather backhandedly, by providing an ingest path that doesn’t rely on the horrendous web UI or the awkward batch ingester. We’ll see; I’m hopeful. I’d far rather build an ETD app that used SWORD to drop ETDs into DSpace than try to hack DSpace for ETDs myself, much less try to push the committer group to do so.

It may be worth noting at this point that I put my votes where my mouth is; when the DSpace development survey came out, I put a mod API at the very top of my desiderata. I encourage other repository managers with unmet needs to speak up for this! It’s vastly more important for the long-term health of DSpace and the services we are building around it than are (for example) controlled vocabularies.

As batch projects accumulate, I have slowly been building up little bits of Python hackery that make the path to a batch import a little smoother. I have a Name class for parsing author names (and I can see a Namelist class on the horizon, because I do more damn HTML screenscraping than any six people should), I have a DC class for writing DSpace’s goofy little dublin_core.xml file without me having to think about it (and I can see a Contents class on the horizon—that one’s pretty easy, but I shouldn’t be rewriting the code all the time as I do now), and I’ve got a fair amount of actual code from previous import projects to analyze.

And it gives me to think more broadly about the repository’s getting-started and ingest processes and how they may be getting in my way. Call it my techie bias speaking if you will, but when Stevan Harnad quite rightly says “the only thing that has been standing between us and 100% OA for years now is keystrokes,” my response does not accord with his “an administrative keystroke mandate is all that is needed.”

My response is “Fewer keystrokes!”

It isn’t just keystrokes, though. It’s the notion of cognitive load, and it’s a simple notion: the more we make people think about putting stuff in the repository, the less of it they’ll actually do, because don’t we all have too much to think about?

I already reduced some of the cognitive load involved in getting set up to use the repository by shortening and clarifying the forms involved. Now I’m thinking to myself, “… forms?” I should find a way to get rid of them. It would help if I could bless other people to create DSpace communities and collections, or at least to access the web form involved and have me bless the creation later—that way they could actually do something instead of filling out a form to have me do it.

But, honestly, even that is too much. A faculty member interested in depositing content is interested in depositing content, not in navigating stupid DSpace hierarchies. So to hell with the hierarchies, to hell with forms, to hell with communities and collections. I want a bucket collection that any person signing up with an appropriate email address automatically gets deposit rights to. I’ll deal with the oversight, moving, and mapping myself, as need be. I’m the librarian; organization is my job. When they’re ready to move beyond the bucket and have a space of their own, damn straight they’ll let me know, and I’ll be happy to oblige.

What scares me about the above possibility (and it is technically feasible to do this, with the repository I run at least) is the vast undergraduate horde… but Shibboleth may be coming soon to a repository near me, so that would presumably solve the problem. Faculty, academic staff, or grad student? You’re in. Undergrad, check with the librarian first.

Also, this licensing thing, argh. It’s ridiculous to do this on a per-item basis. The relationship between faculty and repository is an ongoing one. It shouldn’t be formalized per-item. It should be formalized via something more like a memorandum of understanding, or—hey! Websites have those! They’re called Terms of Service agreements! So I want me one of them, and the legalese to back it up, and the tech to make new registrants click through it once when they sign up, record that they have done so, and never bother them with licensing again. Just as legal, and less cognitive load on every single deposit. Win!

(Creative Commons licensing does have to be done per-item, and I don’t have a problem with that. But the contract between the depositor and the IR doesn’t change—or shouldn’t—per item, so let’s just deal with it once, okay?)

The other big cognitive-load problem is, in a word, backfiles. Everybody but the newest, greenest faculty has a publication history. Nearly everybody who has come to me with a collection idea has some kind of backfile to deal with. Nobody wants to face the hassle of doing all that themselves, and quite right, too. Hassle is my job.

So I need another bucket, probably outside the repository altogether (because the thought of hacking DSpace to do this gives me heartburn), where they can just dump the backfiles and let me deal with them, with my little library of Python hacks and a lot of patience. Additionally, I need some kind of workflow that involves the least metadata-typing possible on my part. (Bum wrists, don’t you know.) Once I’m through with a project I’m doing now that involves an EndNote RIS export (and that I’m very happy about because it’s essentially simple, unlike HTML screenscraping!), I believe I am going to investigate what Zotero can do for me. I think it’s within my capacity to write an export filter for it that dumps stuff out in dublin_core.xml, and once that’s done its metadata-sucking capability should save me a lot of typing and get me better metadata than the usual run. Win!

And Zotero is something that I could teach other people to use. Since I’ve got 26 campuses to worry about, that’s a major desideratum.

So. Anybody in the LazyWeb, especially DSpace hackers, interested in helping me with any of this? I’ll be bringing up the policy and legal parts at my next DSpace meeting.

EPrints just put out a statistics app that doesn’t suck and will supposedly work with DSpace.

I want this. I want it a lot. Unfortunately, it’s got a dependency on commercial charting software. See my occasional rants about “no budget.”

It’s BSD-licensed. Can’t somebody rip out the dependency and substitute JFreeChart or something?

My stupid, for once. I broke Manakin by creating a false XSLT analogy: because there is a last() function, I assumed there had to be a first() function.

Nope. position()=1 is what I wanted, and if I’d been thinking I would have guessed as much.

For the record, Manakin kicks back a really weird error when something breaks in a theme’s XSLT; it pretends that it can’t find a “transaction handler” for the theme. Now I know.

So the Manakin problem that had me tearing my hair out last week was a constellation of Tomcat configuration issues. Tomcat, as I believe I have mentioned before, gives me ulcers. The problems are solved, however, and I hope not to run into them again. If you want to know what they were, ask the local sysadmin, who groks Tomcat so I don’t have to.

Anyway, so Manakin was up, but it wasn’t paying the least attention to my new theme. I scratched my head. I fiddled. I checked out the DSpace wiki. I IMed Tim, who didn’t know what to tell me.

And then I figured it out. The xmlui.xconf file has to be replaced in the working DSpace directory, not in dspace-source. I did that, and hey presto! I have one deathly ugly Manakin theme up and running.

Holy hell, is it ever ugly. Where did my navbar go, for starters? And my logo?

But at least now I can beat on it until it works!

And in other good news, I was wrong! Yep, sometimes that’s good news. The conference organizers weren’t in the market for happytalk, so I am back on the menu. More news when I have it.

So I built what I thought was the crude beginning of a workable Manakin theme and dumped it up on the test server. Whereupon it stubbornly failed to work.

Here we go again. I’ve been fighting with this thing for nearly a week. No quick answers, just “500 I can’t find dspace.cfg.” Which is horse manure. The tech lists are no help: “it’s some kind of a configuration problem, not sure what.” Yeah. Thanks. Guessed that.

Next step is to do this the slow way. There’s a known-good DSpace/Manakin combo on that server. I’m going to restore it, copy it to my local drive, compare it to what I’ve got, and if I have to, start replacing files bit by bit until it breaks again, whereupon I’ll at least have narrowed down the problem!

Would be easier if the compile-deploy cycle weren’t such an amazing pain in the posterior. Die, -D, die!

I’ll let y’all know what it was once I get this licked.