Open amclark42 opened 1 year ago
The new stylesheet generate_static_articles.xsl
already uses the TOC to generate HTML of every DHQ article. It also generates a single XML file, which attempts to map each article's source directory to its expected home upon publication. This mapping needs to be replaced.
In order for Ant to make use of file mapping, the XSLT must generate a new Ant build file, structured like this:
<project name="dhq_articles">
<target name="copyArticleResources">
<copy todir="${toDir.path}">
<fileset dir="${basedir}${file.separator}articles"/>
<firstmatchmapper>
<regexpmapper from="^000654/(.*)$" to="vol/17/1/000654/\1" handledirsep="true"/>
<regexpmapper from="^000116/(.*)$" to="vol/7/2/000116/\1" handledirsep="true"/>
</firstmatchmapper>
</copy>
</target>
</project>
Once the derived build file is available, the main build file can run the task to copy article resources into their static directories:
<ant antfile="..${file.separator}${toDir}${file.separator}article-mapper.xml"
target="copyArticleResources" inheritRefs="true"/>
The Ant build file in the static_site_generation
branch has these main targets:
previewArticle
: Create an HTML preview version of a single article.
article.id
wasn’t provided, requests an article ID for processing.dhq-preview
directory inside the repository.template_article.xsl
on the specified article, saving the output to dhq-journal/dhq-preview/
.zipPreviewArticle
: Create a ZIP file which contains the HTML preview for a single article, as well as the separate assets.
article.id
wasn’t provided, requests an article ID for processing.previewArticle
on the specified article.dhq-journal/dhq-preview/dhq-article-######.zip
.generateIssues
: Generate static HTML versions of the DHQ issues, using XSLT on toc.xml
.
dhq-static
directory next to the journal repository.dhq/vol/#/#/
directory structure in the static directory.dhq-static
directory. (This will copy article XML and resources from the repository articles
directories into the expected dhq/vol/#/#/######
directories.)generateSite
: Generate a full static copy of DHQ intended for the DHQ server. This is NOT a standalone copy. (Also runs generateIssues
; you don’t have to run that one separately if you don’t want.)
generateIssues
.dhq-static/article-map.xml
to copy article resources into the expected dhq/vol/#/#/######
directories.lib
and tests
).starter.html
in the static directory.template_static_pages.xsl
on pages in about
, contact
, news
, people
, and submissions
folders, saving the output to dhq-static/dhq/
.dhq-static/dhq/
into dhq-static/dhq.zip
.The default target is previewArticle
. All targets rely on XSLT processing, and so, they require the XML resolver JAR to be on the classpath when Ant is called. If the JAR file is missing, the build file will stop and provide instructions for loading the JAR.
To run an Ant target, use this command: ant -lib common/lib TARGET
. For example, this would generate a compressed, standalone preview of article 000600:
ant -lib common/lib zipPreviewArticle -Darticle.id=000600
Because this command provides the value of article.id
ahead of time, zipPreviewArticle
will not prompt for it.
Some guidance on testing static site generation:
generateIssues
Ant target. (Useful if you want to examine how this task relates to generateSite
.)
dhq-static
directory and poke around in it.generateSite
Ant target.
dhq-static
directory.dhq-static/dhq/
./dhq
. This is useful for seeing at a glance if the web assets are in a comparable state to those on DHQ, and for testing some links.about
directory.For Windows testing, be especially attentive to file structure and paths. Are dhq-static
and its contents in a reasonable place? Are issue indexes and article HTML files in the right places? If you examine the HTML, do links have forward slashes (/
) and not back-slashes (\
)? The Windows ZIP should definitely be tested by loading it into a server.
As you’re going through this, think about maintainability and quality-of-life. Could anything be made more transparent, or easier? Are there additional preventative measures that could be taken to head off errors or mistakes?
Replace Apache Cocoon's dynamic transformations with static web pages and resources, compiled though an Apache Ant build file. For additional context, see the DHQ infrastructure meeting notes and the specification document.
Tasks:
We still need to decide what to do with the editorial section (which requires authentication) and redirected URLs.