How to customize DocBook to DITA conversion using the Batch Documents Converter add-on

[rtimkovi]

I'm trying to use the Batch Documents Converter add-on to convert DocBook-based content to DITA. The <title> tag in our <chapter> and <section> tags is nested under an <info> tag:

Code: Select all

<chapter id="foo"><info><title>Foo title</title> ... other tags... </info>
<para> .... 

Which causes the default processing to not find any topic titles during conversion:

Code: Select all

System ID: jar:file:/Users/rtimkovi/Library/Preferences/com.oxygenxml/extensions/v25.0/plugins/com.oxygenxml.resources.batch.converter.plugin/oxygen-batch-converter-addon-5.0.1/lib/oxygen-batch-converter-core-25.0-SNAPSHOT.jar!/stylesheets/docbook2dita/ditaWriter/topicOutput.xsl
Description: [Saxon-HE] required  topic/title  not supplied within  topic/topic
Start location: 10527:23

How can I adjust the conversion to handle my case?

Rick

[Cosmin Duna]

Hi Rick,
I created this sample file:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<chapter xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
    <info>
        <title>Chapter Info</title>
    </info>
     <para>Some content here</para>
    <section>
        <info>
            <title>Section Title</title>
        </info>
        <address>Address</address>
    </section>
</chapter>

and I cannot reproduce the problem. That message wasn't presented and titles were preserved in the resulting DITA.
Could you send me a sample file where this problem can be reproduced?

Best regards,
Cosmin

[rtimkovi]

Hi, Cosmin.

Try this:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"
[
   
]>

<book id="container-build-lens">
   <info>
      <title>Container Build Lens</title>
       <subtitle>AWS Well-Architected Framework</subtitle>
   </info>
   <toc/>
    <chapter id="container-build-lens" role="topic">
        
        <info><title id="container-build-lens.title">Container Build Lens</title>
            <titleabbrev>Abstract and introduction</titleabbrev>      
        </info>
          
        <para>Publication date: <emphasis role="bold">October 20, 2022</emphasis> (<xref
            linkend="document-revisions"/>)</para>  
        <para>
            This lens whitepaper is intended for those in technology roles,
            such as chief technology officers (CTOs), architects, developers,
            and operations team members. After reading this paper, you will understand AWS best practices and the strategies to use when designing container images.
        </para>
        
        
        
        <section id="introduction">       
            <info><title id="introduction.title">Introduction</title>
                <titleabbrev>Introduction</titleabbrev>
            </info>
                  
            <para>The AWS Well-Architected Framework helps you understand the pros and cons of decisions you make while building systems on AWS. Using the framework, you will learn architectural best practices for designing and operating reliable, secure, efficient, cost-effective, and sustainable systems in the cloud. It provides a way for you to measure your architectures against best practices and identify areas for improvement. We know that having well-architected systems greatly increases the likelihood of business success.
            </para><para> The Container Build Lens will focus specifically on the container design and build process.
                    Topics such as best practices for container orchestration architecture design principals and
                    general best practices in software development are considered out of scope for this lens.
                    These topics are addressed in other AWS publications. See the <emphasis role="bold"
                        >Resources </emphasis>sections under <xref
                            linkend="pillars-of-the-well-architected-framework"/> for more information.</para>
            
        </section>
    </chapter>

    <chapter id="document-revisions" role="topic">
        
        <info><title id="document-revisions.title">Document revisions</title>
            <titleabbrev>Document revisions</titleabbrev>      
        </info>
        
        <para>To be notified about updates to this whitepaper, subscribe to the RSS feed.</para>  
       
    </chapter>

</book>
      

[Cosmin Duna]

Hi Rick,

You have a custom DTD for DocBook 4 and the converter doesn't expect to find the "info > title" structure in this version of DocBook.
The DocBook to DITA conversion is based on XSLT and it's made in 2 steps:

• first, DocBook 4 is converted to DocBook 5
• second, DocBook 5 is converted to DITA

You should make some changes in the first step for handling this info>title structure. For this, do the following:

1. Open the following jar file into the "Archive Browser" view from Oxygen: /Users/rtimkovi/Library/Preferences/com.oxygenxml/extensions/v25.0/plugins/com.oxygenxml.resources.batch.converter.plugin/oxygen-batch-converter-addon-5.0.1/lib/oxygen-batch-converter-core-25.0-SNAPSHOT.jar
2. In the view, search for the "stylesheets/docbookUpdate/db4-upgrade.xsl" file and open it in the main editor
3. Download this file: files/1416221115025847.zip (I modified the xls file that converts DocBook4 to DocBook 5)
4. Unzip the downloaded file and open the "db4-upgrade.xsl" file in Oxygen.
5. Copy all content from the xsl file that was found in the downloaded zip over the one opened at the second step and save the file.
6. Restart Oxygen

After these steps, the conversion should handle the "info" element.

Best regards,
Cosmin

[rtimkovi]

Thanks, Cosmin. That got me past the initial hurdle.
Now it's complaining about trailing spaces in titles/links and such, but I should be able to make progress from here.
Rick