Using linebreaks in document title on the title page

Post here questions and problems related to editing and publishing DITA content.
Exotic Hadron
Posts: 25
Joined: Mon Aug 07, 2017 7:46 pm

Using linebreaks in document title on the title page

Post by Exotic Hadron »

Howdy,

I am trying to break the title that's displayed on the title page of my document. From what I've read on this page in the Oxygen guide, it suggests that I do this:
  1. Create a translucent placeholder image that would be 1x1 pixel in size.
  2. Insert this image right within the <title> tag just where I want the title to break.
I did this:
  1. Created a DITAMAP file and defined the references to the 1x1 px image in there:

    Code: Select all

    
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <!-- Copyright (c) 2017 Company2 -->
    <map>
    <title>My software product, version 1.1 Reference Manual
    </title>

    <keydef keys="product-name">
    <topicmeta>
    <keywords>
    <keyword>My software product, version 1.1</keyword>
    </keywords>
    </topicmeta>
    </keydef>
    <keydef keys="copyright1">
    <topicmeta>
    <keywords>
    <keyword>© 2009 Company1</keyword>
    </keywords>
    </topicmeta>
    </keydef>
    <keydef keys="copyright2">
    <topicmeta>
    <keywords>
    <keyword>© 2017 Company2</keyword>
    </keywords>
    </topicmeta>
    </keydef>

    <!-- Reference to the linebreak.png which is a translucent 1x1 px png image -->
    <keydef href="images/linebreak.png" platform="windows" keys="linebreak" format="png"/>
    <topicref href="v11reference.dita">
    <mapref href="topics/introduction/intro.ditamap" format="ditamap"/>
    <mapref href="topics/working_with_software/working_with_software" format="ditamap"/>
    <mapref
    href="../../com.mycompany.myproduct.doc.common/topics/how_to_reach_us/how_to_reach_us.ditamap"
    format="ditamap" toc="no"/>
    </topicref>
    </map>
  2. Created the v11reference.dita file with the following content:

    Code: Select all

    
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
    <topic id="topic_aht_3xs_51b">
    <title>
    <ph>My software product, version 1.1</ph>
    <image keyref="linebreak" placement="break"></image>
    <ph>Reference Manual</ph>
    </title>
    <body>
    </body>
    </topic>
    Now when I apply a PDF transformation, the image inserts everywhere where my DITA files reference the <title> (document heading, text after Contents) but the title page. The title on the title page remains displayed without the inserted PNG.

    I've tried omitting the <ph> tag and referencing like

    Code: Select all

    
      <title>
    My software product, version 1.1
    <image keyref="linebreak" placement="break"></image>
    Reference Manual
    </title>
    All to no avail.
    What is that I am doing wrong?
    How do I make Oxygen/DITA-OT to break only the title on the title page?

    Thank you in advance.
Costin
Posts: 828
Joined: Mon Dec 05, 2011 6:04 pm

Re: Using linebreaks in document title on the title page

Post by Costin »

Hi,

Instead using a workaround, an easier (and also more elegant) way to achieve what you need, would be to use a Bookmap instead a DITA Map. The Bookmap allows for two child elements right in the map root. One of them is "<mainbooktitle>", the other is "<booktitlealt>". The 1st one is the main title of your document, the 2nd can be considered a subtitle.

More exactly, in your bookmap, you should have some line similar to the ones below:

Code: Select all

<booktitle>
<mainbooktitle>Here goes "My software product, version 1.1"</mainbooktitle>
<booktitlealt>Here goes "Reference Manual"</booktitlealt>
</booktitle>
I hope this helps.

Regards,
Costin
Costin Sandoi
oXygen XML Editor and Author Support
Exotic Hadron
Posts: 25
Joined: Mon Aug 07, 2017 7:46 pm

Re: Using linebreaks in document title on the title page

Post by Exotic Hadron »

Hi Costin,

Thank you for your response!

Would you please give a clue how would I manage with keydefs I've used in DITAMAP?

The DITAMAP file I am using has a number of key definitions and references to other DITAMAP files. However, I understand that a DITAMAP file that uses bookmap.dtd supports neither <mapref> nor the <keydef> tag. How do I include references to other DITAMAP files and define variables for usage across the document (like the copyrights used in the posted example file)?

Thank you.
Costin
Posts: 828
Joined: Mon Dec 05, 2011 6:04 pm

Re: Using linebreaks in document title on the title page

Post by Costin »

Hi again,

You could create a separate ditamap which could contain the <keydef> elements.
I.e, your key definitions map should look like:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<title>Keydefs map</title>
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword>My software product, version 1.1</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="copyright1">
<topicmeta>
<keywords>
<keyword>© 2009 Company1</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="copyright2">
<topicmeta>
<keywords>
<keyword>© 2017 Company2</keyword>
</keywords>
</topicmeta>
</keydef>
</map>
This DITA Map could be then referred into the <frontmatter> element of your Bookmap, as it allows <mapref> child elements.
This is also the practice that our technical documentation engineers use in our oXygen User-Guide.

Going further, you could refer any additional .ditamap files in each of your bookmap's chapters. For this you should just use "href" attributes on the <chapter> elements, which should refer the DITA Maps you want to include.
Please note that you should also set a "format" attribute on your chapters and set its value to "ditamap", to help oXygen correctly identify the format of the references maps.

Even more than that, if you need only the content from your referred DITA Maps to be present in the output, but you do not need the map itself to be included neither in the navigation and search results, nor rendered as a topic, you could set an additional "processing-role" attribute to "resource-only" on your chapters that refer .ditamap files.

Your bookmap should be structured like in the below example:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
<booktitle>
<mainbooktitle>Here goes "My software product, version 1.1"</mainbooktitle>
<booktitlealt>Here goes "Reference Manual"</booktitlealt>
</booktitle>
<frontmatter>
<mapref href="reusables.ditamap" processing-role="resource-only"/>
</frontmatter>
<chapter href="product1.ditamap" format="ditamap"/>
</bookmap>
Last but not least if, for specific reasons, you can not place all the referred DITA Maps and all of their related resources in the same parent folder as your main bookmap (though this is always recommended when working with multiple ditamaps), all the references and their related resources should be fixed during the transformation. Oxygen tries to fix such "external" references at transformation time through a dedicated transformation scenario parameter.
Just edit the DITA Map PDF transformation scenario, go into the "Parameters" tab and set the "fix.external.refs" parameter to "true".

Let me know if you need additional assistance.

Regards,
Costin
Costin Sandoi
oXygen XML Editor and Author Support
Exotic Hadron
Posts: 25
Joined: Mon Aug 07, 2017 7:46 pm

Re: Using linebreaks in document title on the title page

Post by Exotic Hadron »

Hi again Costin,

Thank you for your valuable help!

Just so others interested know, here's what I've done to migrate from the DITAMAP scheme to BOOKMAP scheme.
  1. Created a copy of the root DITAMAP file (the one that had keydefs for copyrights and links to chapters): reference1.ditamap
  2. From this reference1.ditamap file I've commented everything except for definitions, so I've ended up with:

    Code: Select all

    
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
    <!-- Copyright (c) 2017 Company2 -->
    <map>
    <title>My Product Reference Manual</title>
    <keydef keys="copyright1">
    <topicmeta>
    <keywords>
    <keyword>© 2016 Company1</keyword>
    </keywords>
    </topicmeta>
    </keydef>
    <keydef keys="copyright2">
    <topicmeta>
    <keywords>
    <keyword>© 2017 Company2</keyword>
    </keywords>
    </topicmeta>
    </keydef>
    <!--
    <topichead navtitle="Reference Manual">

    <mapref href="reference/ref/ref.ditamap" format="ditamap"/>

    <topichead navtitle="Working with the tool">
    <mapref href="reference/component1/comp1.ditamap" format="ditamap"/>
    <mapref href="reference/component2/comp2.ditamap" format="ditamap"/>
    </topichead>
    <topicref href="../com.my.company.doc.common/topics/contact/contact.ditamap"
    format="ditamap" toc="no"/>
    </topichead> -->
    </map>
  3. Created a BOOKMAP file (for unknown reason Oxygen expects it to have the same DITAMAP extension; why so?), named it as reference2.ditamap and copied everything I've commented out in the reference1.ditamap file to this file.
    The markup for this file looks like:

    Code: Select all

    
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
    <bookmap>
    <booktitle>
    <mainbooktitle>My Product</mainbooktitle>
    <booktitlealt>Reference Manual</booktitlealt>
    </booktitle>
    <frontmatter>
    <booklists>
    <toc/>
    <!--
    <figurelist/>
    <tablelist/>
    -->
    </booklists>
    </frontmatter>
    <chapter href="reference1.ditamap" format="ditamap"/>
    <chapter href="reference/component1/comp1.ditamap" format="ditamap"/>
    <chapter href="reference/component2/comp2.ditamap" format="ditamap"/>
    <backmatter>
    <!--
    <amendments href="updatesToTheBook.dita"/>
    -->
    <booklists>
    <trademarklist href="../com.my.company.doc.common/topics/contact/contact.ditamap" format="ditamap" toc="no"/>
    <indexlist/>
    </booklists>
    </backmatter>
    </bookmap>
Thank you for your help!
Post Reply