Help with Dita debug-filter build step

[ann.jensen]

Hi,
Our automation team are running the Oxygen WebHelp transformation plugin against our DITA source in SVN via a call to the dita.bat command.

I recently reorganised the structure of our DITA content in order to simplify the folder structure and now there are wierd things happening during the dita.bat build.

The following is the initial output from the build log file:

Code: Select all

log-arg:

     [echo] *****************************************************************

     [echo] * basedir = E:\Dita\dita-ot-2.4.6

     [echo] * dita.dir = E:\Dita\dita-ot-2.4.6\bin\..

     [echo] * transtype = webhelp-responsive

     [echo] * tempdir = E:\TCA\20G\work\657b72094042c918\TempDITAProcess

     [echo] * outputdir = E:\TCA\20G\work\657b72094042c918\rollout

     [echo] * clean.temp = true

     [echo] * DITA-OT version = 2.4.6

     [echo] * XML parser = Xerces

     [echo] * XSLT processor = Saxon

     [echo] * collator = ICU

     [echo] *****************************************************************

I can then see the issues starting in the build log file output from the debug-filter section. This is the first time I see any processing in relation to the folder specified for the -temp build parameter i.e. TempDITAProcess

Code: Select all

debug-filter:

   [filter] Processing file:/E:/TCA/20G/work/657b72094042c918/system/Address_Book/t_upload_ins_user.dita to file:/E:/TCA/20G/work/657b72094042c918/TempDITAProcess/657b72094042c918/system/Address_Book/t_upload_ins_user.dita

For some reason, there is a duplicate folder called 657b72094042c918 generated in the TempDITAProcess folder and I don't understand why.

Can anyone shine any light on this for me?
Thanks in advance,
Ann Jensen

P.S. I have also posted this on DITA Users Group.

[ionela]

Hi Ann,

As you've reorganized the structure of the DITA content it is recommended to perform the 'Validate and Check for completeness' action, to see if your DITA Map is still valid.
https://www.oxygenxml.com/doc/versions/ ... idate.html

Also, for DITA projects it is recommended to store all referenced resources inside your ditamap folder. So, when you perform the Validate and Check for Completeness action, make sure that the 'Report references to resources outside of the DITA map folder' option is selected. If this is the case, then you can either move the resources inside your ditamap folder or use the "fix.external.refs.com.oxygenxml" parameter:
https://www.oxygenxml.com/doc/versions/ ... -refs.html

Regards,
Ionela

[ann.jensen]

Hi,
The link states
The fix.external.refs.com.oxygenxml parameter is only supported when the DITA OT transformation process is started from Oxygen XML Editor.

How are such references handled when building using Oxygen WebHelp plugin configured on a build server?
Thanks,
Ann

[Costin]

Hi Ann,

Please note that only the second instruction in the "Topic References Outside the Main DITA Map Folder" section in our User-Guide refers the parameter that can be used only from oXygen, but the first instruction covers specifically the situation when you use the command line.
If you produce WebHelp output outside of oXygen, then you should make sure you have a top level DITA Map in the same folder or a parent folder of all the other DITA Maps and resources referred.

Regards,
Costin

[ann.jensen]

Hi Costin,
Yes all my maps are in the root folder so no map will ever by looking "up" to find any referenced topics.
I do have links to external web files ...but this shouldn't be a problem.
For some reason given the following setup in my build log output:

Code: Select all

log-arg:

     [echo] *****************************************************************

     [echo] * basedir = E:\Dita\dita-ot-2.4.6

     [echo] * dita.dir = E:\Dita\dita-ot-2.4.6\bin\..

     [echo] * transtype = webhelp-responsive

     [echo] * tempdir = E:\TCA\05A\temp\buildTmp\temp20171117143411995

     [echo] * outputdir = E:\TCA\05A\work\7f92a63154f10e56\rollout

     [echo] * clean.temp = true

     [echo] * DITA-OT version = 2.4.6

     [echo] * XML parser = Xerces

     [echo] * XSLT processor = Saxon

     [echo] * collator = ICU

     [echo] *****************************************************************

     [echo] #Ant properties

     [echo] #Fri Nov 17 14:34:12 GMT 2017

     [echo] args.breadcrumbs=yes

     [echo] args.copycss=No

     [echo] args.default.language=en-US

     [echo] args.filter=E\:\\TCA\\05A\\work\\7f92a63154f10e56\\ditavals\\m_ags_filter.ditaval

     [echo] args.grammar.cache=no

     [echo] args.input=E\:\\TCA\\05A\\work\\7f92a63154f10e56\\supermap.ditamap
     

When processing gets to

Code: Select all

debug-filter:

stage
the following is happening

Code: Select all

debug-filter:

   [filter] Processing file:/E:/TCA/05A/work/7f92a63154f10e56/system_folder/job/c_job_tt.dita to file:/E:/TCA/05A/temp/buildTmp/temp20171117143411995/7f92a63154f10e56/system_folder/job/c_job_tt.dita
 

An extra folder called 7f92a63154f10e56 is being appended to the temp folder and I just can't figure out why.

Any advice appreciated,
Regards,
Ann

[ionela]

Hi Ann,

This extra folder can be caused by a resource referred in the ditamap and located outside the ditamap directory into a upper level folder.

However, this problem should be reported if you perform the 'Validate and Check for completeness' with the 'Report references to resources outside of the DITA map folder' option enabled.

Regards,
Ionela

[ann.jensen]

Hi,
My problem turned out to b a path reference that navigated up above the folder containing the root ditamap and then navigated back down to a sibling topic
This doesn't cause any alerts in the Validation or build.
However, our TeamCity build appends an auto generated folder to the root folder during it's build and therefore the path reference was no longer valid.
I will try to add a Schematron test to check for this type of path and alert it during development.
Regards,
Ann