Delivering Docs

DocAsCode embed an Ant runner and exposes custom targets, tasks, types and macros. The build file is restricted to be delivery.xml at root of the repository. To use DocAsCode Tasks and Type, use the antlib namespace antlib:org.docascode.ant:

<project name="my-project" default="delivery"  basedir="."
         xmlns:docascode="antlib:org.docascode.ant">
    <!-- define your build here -->
</project>

DocAsCode uses two directory for build process:

${build} the working directory
${bin} the final directory

For readability reasons, it is recommended to define those properties in delivery.mml.

Targets

DocAsCode provide predefined targets for easy build process. To load DocAsCode targets, you need to declare <docascode:targets/> in delivery.xml. Some properties

`clean` target

Clean-up delivery directories

Table 1. `clean` target parameters
Ant Property	Description	Mandatory
bin	The final directory	Yes
build	The working directory	Yes

`copy` target

Copy files designated by their id into the working directory. All attached files are also copied.

Table 2. `copy` target parameters
Ant Property	Description	Mandotory (default value)
copy.list	Comma-separated list of ids	Yes
build	The working directory	Yes
output	The naming rule to apply	No ("default")

`convert` target

Convert all files located in ${build} into PDF format. Only .docx source files are supported.

Table 3. `convert` target parameters
Ant Property	Description	Mandatory
build	The working directory	Yes

`diff` target

Compute a comparison of .docx files against their LATEST Maven version.

Hence, the files must be registered as DocAsCode artifacts in chrono.xml and remote server must be registered in settings.xml. The generated files are located in ${build}/DIFF.

Table 4. `diff` target parameters
Ant Property	Description	Mandatory (default value)
diff.list	Comma-separated of artifact id to diff	Yes
build	The working directory	Yes
output	The naming rule to apply	No ("default")

`acid` target

Encrypt the files in ${build} into ${bin}/${acid.basename}.acidcsa. Public keys are taken from the ${acid.keys.dir} directory.

The full path of acidcmd.exe must be set in the $PATH variable.

Table 5. `acid` target parameters
Ant Property	Dexcription	Mandatory
build	The working directory	Yes
bin	The directory containing the generated archive	Yes
acid.keys.dir	Public keys directory	Yes
acid.basename	Basename of the generated archive	Yes

`zip` target

Compress the working directory ${build} into ${bin}/${zip.basename}.zip

Table 6. `zip` target parameters
Ant Property	Description	Mandatory
build	The working directory	Yes
bin	The final directory	Yes
zip.basename	Basename of the archive	Yes

`deploy` target

Deploy the selected artifacts to remote server.

[IMPORTANT]: Each Artifact to deploy must be registered in chrono.xml

Table 7. `deploy` target
Ant Property	Description	Mandatory
deploy.list	Comma-separated list of artifacts to deploy	Yes

Ant Tasks, Types & Macros

DocAsCode offers many Ant tasks,types and macros which are automatically loaded by adding namespace antlib:org.docascode.ant into your project declaration.

Tasks

`update` task

Update properties of OpenXml files.

Table 8. `update` task attributes and/or nested element
Parameter	Description	Type
file	The file to act on	XML Attribute
property	A property to set	Nested Property

`properties` task

Load properties of OpenXML files into Ant properties

Table 9. `properties` task attributes and/or nested element
Parameter	Description	Type
file	The file to read	XML Attribute
prefix	The prefix to prepend to all read property	XML Attribute

For instance, if myDoc.docx contains the custom property myProperty with value myValue, then the following ant script:

<docascode:properties file='myDoc.docx' prefix='myPrefix'/>

will create the Ant property myPrefix.myProperty with value myValue.

`convert` task

Convert all selected files to PDF format. Only .docx files are supported.

Table 10. `convert` task attributes and/or nested element
Parameter	Description	Type
destDir	The target directory	XML Attribute
fileset	The selected files	Ant FileSet
mapper	A mapper for renaming	Ant FileNameMapper

`diff` task

Compute a comparison of .docx files given files against their LATEST Maven version.

Hence, the files must be registered as DocAsCode artifacts in chrono.xml and remote server must be registered in settings.xml. The generated files are located in ${build}/DIFF.

Table 11. `diff` task attributes and/or nested element
Parameter	Description	Type
toDir	Target directory	XML Attribute
fileset	The selected files	Ant FileSet
mapper	The naming rule to apply	Ant FileNameMapper

Without a specified mapper, the files are renamed from myFile.docx to DIFF/myFile.docx.

`acid` task

Encrypt the selected files into a signed archive with specified public keys.

The full path of acidcmd.exe must be set in the $PATH variable.

Table 12. `acid` task attributes and/or nested element
Parameter	Description	Type
destDir	The target directory	XML Attribute
basename	The archive basename	XML Attribute
pubkeydir	The public keys directory	XML Attribute
dir	The directory containing the files to encrypt	XML Attribute

`deploy` task

Deploy the selected artifacts to remote server.

Table 13. `deploy` task attributes and/or nested element
Parameter	Description	Type
ids	Comma-separated list of registered artifacts to deploy	XML Attribute
profile	Maven profile to activate for deployment	XML Attribute
artifacts	Comma-separated list of registered artifacts to deploy	DocAsCode artifacts

`process` task

Allow to execute any nested task while scanning chrono.xml.

Table 14. `process` task attributes and/or nested element
Parameter	Description	Type
ids	Comma-separated list of registered artifacts to process	XML Attribute
name	Selected hard-coded output naming rule	XML Attribute
actions	The actions to perform	Actions

Types

`property` type

A key-value pair to set OpenXML file properties.

Table 15. `property` type attributes
Attribute	Description	name
The property name	value	The property value

`propertymapper` type

A filename mapper converting all occurence of @my-property@ by its value in the specified OpenXMl file.

Table 16. `property` type attributes
Attribute	Description
file	The file to read for resolving properties
from	The string to evaluate

`chainedmapper` type

This mapper implementation act as Ant chainedmapper, but it keeps OpenXML properties along.

Table 17. `chainedmapper` type attributes
Attribute	Description
file	The file to read for resolving properties

`chronomapper` type

This mapper implementation return the hard-coded naming rule specified in chrono.xml.

Table 18. `chainedmapper` type attributes
Attribute	Description
ids	Comma-separated list of identifiers

`chronoselector` type

This selector implementation allow to filter filesets w.r.t. files given in chrono.xml.

Table 19. `chronoselector` type attributes
Attribute	Description
ids	Comma-separated list of identifiers

`artifacts` and `artifact` type

artifacts type allow ta aggregate mutiple artifact. An artifact a declaration of Maven artifact via its coordinates groupId:artifactId:version

Table 20. `artifact` type attributes
Attribute	Description
file	The fiel location
groupId	The groupId, can be resolved with `@my-property@` internal property
artifactId	The artifactId, can be resolved with `@my-property@` internal property
version	The verion, can be resolved with `@my-property@` internal property
classifier	The classifier, can be resolved with `@my-property@` internal property
extension	The file extension. Its default value corresponds to the file extension.

Macros

Plugins

You may need to share some targets and/or custom macros. DocAsCode allow to use project plugins you can easily duplicate in other DocAsCode repositories. A plugin is structured as follow:

A plugin is located in a directory inside .docascode/plugins
A plugin is declared in the mandatory file .docascode/plugins/my-awesome-plugin/tasks.xml
- You can use any DocAsCode tasks provided you declare the antlib namespace antlib:org.docascode.ant
- You can use any resource file located in .docascode/plugins/my-awesome-plugin

To load the plugins you need to set <docascode:plugins/> in delivery.xml.

Delivering Docs

Targets

clean target

copy target

convert target

diff target

acid target

zip target

deploy target

Ant Tasks, Types & Macros

Tasks

update task

properties task

convert task

diff task

acid task

deploy task

process task