transpectdoc Ⓐ – transpectdoc

transpectdoc Ⓐ transpectdoc

transpectdoc/xpl/transpectdoc.xpl

This pipeline documents all pipelines and library that are used in a project.

The source documents are considered as the front-end pipelines. All other imported libraries and steps will be crawled.

For each of the steps’ input and output ports, a linked list will be generated that points to the ports in other pipelines that are connected to these ports.

Sample invocation (from a Makefile):

FRONTEND_PIPELINES = adaptions/common/xpl/idml2hobots.xpl adaptions/common/xpl/hobots2epub-frontend.xpl crossref/xpl/process-crossref-results.xpl crossref/xpl/jats-submit-crossref-query.xpl
transpectdoc: $(addprefix $(MAKEFILEDIR)/,$(FRONTEND_PIPELINES))
	$(CALABASH) $(foreach pipe,$^,$(addprefix -i source=,$(call uri,$(pipe)))) \
		$(call uri,transpectdoc/xpl/transpectdoc.xpl) \
		debug=$(DEBUG) debug-dir-uri=$(call uri,$(MAKEFILEDIR)/transpectdoc/debug)

Set the svn property svn:mime-type for the transpectdoc.css in your documentation output directory to text/css, if you want to view the generated documentation online, not only locally.

For customizing transpectdoc, there are three XSLT passes whose templates etc. may be overridden by specifying, e.g.:

		-i crawling-xslt=$(call uri,adaptions/common/transpectdoc/xsl/pubcoach-crawl.xsl) \
		-i connections-xslt=$(call uri,adaptions/common/transpectdoc/xsl/pubcoach-connections.xsl) \
		-i rendering-xslt=$(call uri,adaptions/common/transpectdoc/xsl/pubcoach-render-html-pages.xsl) \

within the calabash.sh invocation (provided the files reside there, of course).

Adding Examples for Dynamically Evaluated Pipelines

If your pipeline loads and executes pipelines at runtime, i.e., pipelines that are not known statically in advance, you may provide examples for these pipelines. Example:

<transpect:dynamic-transformation-pipeline load="hub2hobots/hub2hobots">
  …
  <p:pipeinfo>
    <examples xmlns="http://www.le-tex.de/namespace/transpect"> 
      <collection dir-uri="http://customers.le-tex.de/generic/book-conversion/adaptions/" file="hub2hobots/hub2hobots.xpl"/>
      <generator-collection dir-uri="http://customers.le-tex.de/generic/book-conversion/adaptions/" file="hub2hobots/hub2hobots.xpl.xsl"/>
    </examples>
  </p:pipeinfo>
</transpect:dynamic-transformation-pipeline

Please note that the generator-collection element is not implemted yet. It is meant for holding pointers to XSLT stylesheets that generate the dynamically evaluated pipelines.

There is an optional attribute @for on the examples element:

<transpect:evolve-hub name="evolve-hub-dyn" srcpaths="yes">
  …
  <p:pipeinfo>
    <examples xmlns="http://www.le-tex.de/namespace/transpect" 
      for="http://transpect.le-tex.de/book-conversion/converter/xpl/dynamic-transformation-pipeline.xpl#eval-pipeline">
      <collection dir-uri="http://customers.le-tex.de/generic/book-conversion/adaptions/" file="evolve-hub/driver.xpl"/>
      <generator-collection dir-uri="http://customers.le-tex.de/generic/book-conversion/adaptions/" file="evolve-hub/driver.xpl.xsl"/>
    </examples>
  </p:pipeinfo>
</transpect:evolve-hub>

Since the examples to the evolve-hub transpect:dynamic-transformation-pipeline will vary from project to project, it is impractical to provide one single set of examples for this pipeline. Instead, you provide the examples at the transpect:evolve-hub invocation in your project’s pipeline. In the @for attribute, you tell transpectdoc that the examples are for the input port called 'pipeline' of transpect:dynamic-transformation-pipeline (provided that this port has an xml:id of 'eval-pipeline').

Visualisation

The pre-creation of this SVG image needs the Graphviz software installed. Please inform your project maintainer.

Input Ports

Name	Documentation	Connections
sourceⓅⓈ	The front-end pipelines of the transpect installation.
crawling-xslt
connections-xslt
plantuml-xslt
rendering-xslt

Output Ports

none

Options

Name	Documentation	Default
debug		'yes'
debug-dir-uri		'debug'
output-base-uri		replace( static-base-uri(), 'transpectdoc/xpl(/.*)?$', 'doc' )
project-name	XSLT should generate title according to default rules if empty string is submitted	''
project-root-uri		resolve-uri('../..', static-base-uri())

Subpipeline

Step				Inputs	Outputs	Options
p:variable base-dir-system-path The operating system path for the output directory (with forward slashes). Whitespace is not supported.						replace( $output-base-uri, '^file:/+(([a-z]:)/)?', '$2/', 'i' )
p:xslt crawl				source source on transpectdoc p:documentlib/xproc-1.0.xpl parameters p:empty stylesheet crawling-xslt on transpectdoc	result	template-name = 'crawl'
letex:store-debug d11e184				source result on crawl	result	pipeline-step = 'transpectdoc/1.crawl' active = $debug base-uri = $debug-dir-uri
cx:message d11e191				source result on d11e184	result	message = '*** Connecting primary ports ...'
p:xslt connections Makes implicit primary port connections explicit. As an unrelated side effect, will normalize plain text and DocBook markup within p:documentation elements to HTML.				source result on d11e191 parameters p:empty stylesheet connections-xslt on transpectdoc	result	initial-mode = 'connect'
letex:store-debug d11e207				source result on connections	result	pipeline-step = 'transpectdoc/2.connect' active = $debug base-uri = $debug-dir-uri
p:xslt connections2plantuml Generates plantuml text syntax wrapped in plantuml elements.				source result on d11e207 parameters p:empty stylesheet plantuml-xslt on transpectdoc	result	initial-mode = 'plantuml'
cx:message d11e231				source result on connections2plantuml	result	message = '*** Creating svg representations ...'
p:sink d11e233				source result on d11e231
p:for-each create-plantuml				result on connections2plantuml
	p:try plantuml-to-svg
		p:group d11e244
		p:group d11e244	cx:plantuml d11e246			format = 'svg'
		p:catch d11e252		error
		p:catch d11e252	p:identity d11e254	source `<c:plantuml-lib-error/>`	result
	p:add-attribute d11e267			source	result	match = ':svg' attribute-name = 'xml:id' attribute-value = //@xml:id
p:wrap-sequence svg-seq-wrapping				source	result	wrapper = 'svg-wrapper'
letex:store-debug d11e278				source result on svg-seq-wrapping	result	pipeline-step = 'transpectdoc/2.plantuml' active = $debug base-uri = $debug-dir-uri
cx:message d11e285				source result on d11e278	result	message = '*** Creating html rendering ...'
p:sink d11e288				source result on d11e285
p:xslt render				parameters p:empty source result on connections result on svg-seq-wrapping stylesheet rendering-xslt on transpectdoc	result	initial-mode = 'render-transpectdoc'
cx:message d11e312				source result on render	result	message = '*** Copying html, css and javascript files ...'
p:sink d11e314				source result on d11e312
p:for-each d11e316				secondary on render
p:for-each d11e316	p:store d11e323			source current on d11e316	result	omit-xml-declaration = 'false' method = 'xhtml' href = base-uri()
cxf:mkdir d11e329 Always create the output directory. Otherwise (i.e. first time) a java.io.FileNotFoundException will raise.					result	href = $output-base-uri
cxf:copy d11e338					result	href = resolve-uri('../css/transpectdoc.css', static-base-uri()) target = concat($output-base-uri, '/transpectdoc.css')
cxf:copy d11e345					result	href = resolve-uri('../lib/jquery-2.1.1.min.js', static-base-uri()) target = concat($output-base-uri, '/jquery.js')
cxf:copy d11e352					result	href = resolve-uri('../js/transpectdoc.js', static-base-uri()) target = concat($output-base-uri, '/transpectdoc.js')
letex:unzip unzip-highlight-js					result	overwrite = 'yes' zip = replace( resolve-uri('../lib/highlight.zip', static-base-uri()), '^file:/+(([a-z]:)/)?', '$2/', 'i' ) dest-dir = concat($base-dir-system-path, '/highlight')
p:sink d11e370				source result on unzip-highlight-js

transpect-demo