Part of Plans for DITA Open Toolkit 1.5

Design for allowing file names to include spaces in the DITA-OT 

What user need will be met by this feature?

The toolkit can support spaces in file names now. This means that users of DITA-OT can type spaces in file names and directories, while in the previous version, spaces in file names or directories will generate warning and error messages.

What is technical design for this change?

Attribute @includes of <xslt> task in ANT doesn’t support file name which contains spaces, because Ant regards the space in @includes as separate character, while attribute @includesfile can support space. The value of @includesfile is a file, each line of this file is taken to be an include pattern. Here we specify each line with a filename, so the space won’t be a problem any more.

First, we should continue to generate the dita.list information, because many builds rely on this file. Second, in order to support the @includesfile, we should generate corresponding list files in the dita.list, for example “fullditatopiclist=a.xml, b.xml” is specified in the dita.list, then we generate a file whose content are “a.xml” and “b.xml”, they are separated by a newline. We name this file fullditatopic.list, the name is also added in the dita.list. Then part of dita.list is becomes:

fullditatopiclist=a.xml, b.xml

fullditatopicfile=fullditatopic.list

The works above are carried out by GenMapAndTopicListModule, it generates the list file while writing the properties to dita.list. The logic is very easy. The DebugAndFilter unify the file extension name of dita topic to “.dita” or “.xml”, so we should update the list files meanwhile. And the chunking updates the dita.list due to the @chunk used in the ditamap file, so we should also update the list file meanwhile.

Core ant build files should be updated, use the @includesfile instead of @includes.

XALAN seems not support spaces and the back slash, so even if we can successfully pass the filename(directory) containing space or back slash to XALAN, it can not read the file. So we should replace spaces with %20 and "\" with "/".

What sections of the toolkit will be impacted by the change?

Two modules and some core ant build files are impacted by this change.

Two modules are GenMapAndTopicListModule, DebugAndFilterModule and ChunkModule, they all handle the file names, the first module generates common file lists, and the last module updates the list generated by the GenMapAndTopicListModule due to the chunk attribute specified in the map file. DebugAndFilterModule replace the file extension name and unify the file extension name of dita topic to “.dita” or “.xml”. After the refactor, any module which manipulated dita.list or dita.xml.properties will be updated to generate another copy of the content in dita.list to new generated list files.

Many ant build files use includes attribute in the <xslt>task, such as includes="${user.input.file}", ant regards spaces in includes attribute as separate character, so it doesn’t support spaces in file name and directories. So these need to be updated.

See also

None