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

table

A Table to edit

Nested Table

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

table type

A hierarchical description of rows to insert into existing table. .table attributes and/or nested element

Parameter Description Type

num

index of the table to edit

XML Attribute

row

description of the row to insert

Row

Table 16. row nested element
Parameter Description Type

paragraphFormat

style rule applied to nested cells

paragraphFormat

cell

description of the cell to insert

Cell

Table 17. paragraphFormat nested element
Parameter Description Type

justification

Justification to apply

"LEFT", "CENTER", "RIGHT", "BOTH", "MEDIUM_KASHIDA", "DISTRIBUTE", "NUM_TAB", "HIGH_KASHIDA", "LOW_KASHIDA" or "THAI_DISTRIBUTE"

spaceAfter

Space after paragraph

long

Table 18. cell nested element
Parameter Description Type

paragraphFormat

style rule applied to nested cells. Override nested paragraphFormat of parent row

paragraphFormat

text

The text to set into the cell

XML Attribute

The following example will perform a 5 cells row insertion in the first table.

<docascode:table num="0">
    <docascode:row>
        <docascode:paragraphformat justification="LEFT" spaceAfter="0"/> <!-- All cells are LEFT justified by default-->
        <docascode:cell text="t1"/>
        <docascode:cell text="t2"/>
        <docascode:cell text="t3">
            <docascode:paragraphformat justification="CENTER" spaceAfter="0"/> <!-- This cell is CENTERED justified -->
        </docascode:cell>
        <docascode:cell text="t4"/>
        <docascode:cell text="t5">
            <docascode:paragraphformat justification="RIGHT" spaceAfter="0"/> <!-- This cell is RIGHT justified -->
        </docascode:cell>
    </docascode:row>
</docascode:table>

propertymapper type

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

Table 19. 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 20. 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 21. 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 22. 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 23. 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.