Make internal preview version of DHQ for proofing the static site

[amclark42]

Besides reviewing my code changes, I’d like my reviewer(s) to try using the makeInternalPreview build target in the command line, as well as the exported oXygen scenarios. I’d like to know:

• Does it work?
• Is it easy to use? Are there any terms or steps that might trip up a DHQ editor?
• Did I miss any main-content links (not in the DHQ header or sidebar) that should be relative?
• Are there other improvements I should consider making before we switch to a static site publication system?

Background

The main goal here: to allow DHQ editors and continuous integration to generate a proofing copy of the articles listed in the “editorial” section of the DHQ TOC. This is accomplished with a new Ant build target, makeInternalPreview.

makeInternalPreview allows the user to choose between generating a copy of just the unpublished articles (the default), or the entire DHQ site plus the internal preview section. Under the hood, the target customizes the behavior of generateIssues and generateSite. In either case, the results are saved to dhq-proofing, a new directory inside dhq-static.

Other improvements

Because DHQ editors will use the new Ant build target in oXygen, I’ve made a few improvements:

• Within most TOC-derived pages, links within the main content of each page should be relative. The proofing copy must be navigable in a browser without a server or special setup.
  • I did not attempt a thorough deep-dive into the DHQ XSLT. However, I did try to ensure that all links within a single issue were relative to other resources in that directory.
• Each HTML page is created with “proofing copy” displayed prominently across the header, as well as a sepia filter on the header image. It should be harder to confuse the unofficial copy with the static site generated for publication.
• An export of oXygen transformation scenarios is available in common/xslt/static-site.scenarios. Once imported, an oXygen user will be able to run the makeInternalPreview, previewArticle, or zipPreviewArticle scenarios from any file in their local copy of dhq-journal.
  • Instructions for importing the scenarios are in the wiki.
• I’ve completely refactored article_list.xsl, the stylesheet which produces a table of all DHQ articles in the TOC for proofing purposes. The resulting HTML seems cleaner and more useful (to me, anyway), and the stylesheet itself should be significantly easier to read, understand, and maintain.
  • I’ve done my best to try to model the kind of refactoring I think the rest of the DHQ stylesheets will eventually need: moving away from XSLT 1.0; reducing the amount of duplicated code; adding context through comments; etc.

I’ve also tried to aid maintainability by moving the ant help documentation into a single <echo> (making its contents easier to read and edit). I also broke out the Ant property ${toDir} into three settings in the build-properties.xml, so that individual directory names will be easier to edit. And I added a toggle to turn off certain XSLT messages where they would only distract from more useful info or urgent warnings.

[sydb]

BUILD FAILED
/home/syd/Documents/dhq-journal/build.xml:286: Directory does not exist: /home/syd/Documents/dhq-static/dhq-proofing

I am going to create that directory so I can continue testing. (As you might have guessed, I am testing the commandline interface, using bash.)

[amclark42]

@sydb Good catch, thank you! I fixed that bug.

[juliaflanders]

I've tested the three scenarios and they all seem to work as planned :-) To respond to Ash's questions above:

1. It does work
2. It seems very easy to use. The Managing Editor workflow already includes using XSLT to generate a proofing copy, so this would simply replace and expand on that functionality, using a familiar process. The mechanisms for specifying an individual article and for choosing how much to generate (whole site or just preview) are both easy and clear. I like the fact that the default is "just the internal site" so hitting return does what people most often need.
3. I did not find any broken/problematic links in the generated HTML articles, but the link from the article XML (in the generated site) to the schema is broken, I think because of the introduction of the vol/ layer?
4. I can't think of any other improvements at this point.