DITA: conref, TOC/Index in PDF not generated

[David Winter]

Hello,

this is my first post on the Oxygen forums; please don't shoot...

I am currently playing around with a 30 day trial of Oxygen. I try to build and customize a DITA project. Some of it works, some of it doesn't, and I hope a kind soul can help me find out if I am encountering DITA- or Oxygen-specific problems here.

I have a DITA map with a few dozen topics nested under headings in the map. They all validate.

I tried to build XHTML and PDF versions using Oxygen's integrated transformation scenarios.

Problem #1:

During both transformations (XHTML and PDF), a simple conref (<p conref="sometopic.xml#someid"/>) produces an error:

"[xslt] [DOTX010E][ERROR]: Unable to find target for conref="sometopic.xml#someid". Check to make sure that the target element is available, and that it is a 'xxxx' element."

This is odd, as *within* Oxygen, the conref replacement works just fine: In the editor's Author view, the conref is replaced by the target's content just as expected.

Any ideas where this problem might come from? I already tried changing the relevant topics' file extensions (.XMl/.dita) to no avail.

Problem #2:

PDF generation basically works, but there are two problems:

a)

The PDF's table of content does not list all the topics that are nested under topic headings in the DITA map - only those that are on the root level. (All topics do, however, appear in the sidebar of the PDF Reader).

b)

The PDF has no index, although I have made several entries.

There are no errors in the log file for the transformation. Does this mean I am looking at restrictions of the Apache FO processor, or is there something else missing?

Thanks in advance.

[Radu]

Dear David,

Thank you for contacting us.

About the conref element which does not show up:

It is possible the conref is seen as resolved in Author but is not resolved at the transformation time because the DITA Open Toolkit ANT transformation imposes additional constraints on the content references. Are you sure you are referring the same element using the conref?
Can you zip some sample files and send them to us so we can have a look at them?
http://www.oxygenxml.com/techSupport.html

About the PDF output customizations:
Oxygen integrates DITA Open Toolkit 1.4.2.1 to run ANT transformations on DITA Maps. The Toolkit is located in the {OXYGEN_INSTALL_DIR}/frameworks/dita/DITA-OT directory.

I assume you are using the PDF - DITA OT transformation.
You should try to use the second PDF transformation we make available: 'PDF2 - IDIOM FO Plugin' (preferably using XEP) as it has more active contributors and does not have this problem.

If you do not want that, please read the workaround below:
About the first generation problem:
This seems to be the default behaviour using DITA Open Toolkit PDF transformation.
You can customize the dita2fo-shell.xsl stylesheet located in the "DITA-OT/xsl" directory and replace the "gen-toc" template with this modified one which should include also the first-level topic heads.

Code: Select all

  <xsl:template name="gen-toc">

    <xsl:for-each

      select="//bookmap/*[contains(@class,' topic/topic ')]|//map/*[contains(@class,' topic/topic ') or contains(@class, ' mapgroup-d/topichead ')]">

      <xsl:variable name="isTopicHead" select="contains(@class, ' mapgroup-d/topichead ')"/>

      <fo:block text-align-last="justify" margin-top="6pt" margin-left="4.9pc">

        <fo:inline font-weight="bold">

          <xsl:choose>

            <xsl:when test="$isTopicHead">

              <xsl:value-of select="@navtitle"/>

            </xsl:when>

            <xsl:otherwise>

              <xsl:value-of select="*[contains(@class,' topic/title ')]"/>

            </xsl:otherwise>

          </xsl:choose>

        </fo:inline>

        <fo:leader leader-pattern="dots"/>

        <xsl:if test="not($isTopicHead)">

          <xsl:variable name="id-value">

            <xsl:choose>

              <xsl:when test="@id">

                <xsl:value-of select="@id"/>

              </xsl:when>

              <xsl:otherwise>

                <xsl:value-of select="generate-id()"/>

              </xsl:otherwise>

            </xsl:choose>

          </xsl:variable>

          <fo:page-number-citation ref-id="{$id-value}"/>

        </xsl:if>



      </fo:block>

      <xsl:call-template name="get-tce2-section"/>

    </xsl:for-each>

  </xsl:template>

About the index problem, you should probably ask this on the DITA Open Toolkit users list:
http://tech.groups.yahoo.com/group/dita-users/

Here is a link to another PDF customization post you may find useful:
http://www.oxygenxml.com/forum/topic3092.html

Regards,
Radu

[David Winter]

Hello Radu,

thank you for your feedback.

I was able to sort out the conref problem; I had referenced a section where it could not be used.

And regarding the PDF customization - I will probably switch to RenderX (or buy DocBench right away).

I'm not sure if I'll stick with DITA, but I like Oxygen more with every hour I am using this trial version. Frankly, I don't see any alternatives for the Mac right now.

Also let me say that it's very noble of you guys to help out not only with your product, but also with all the XML-based languages it supports... Much appreciated!

[Radu]

Hi David,

Indeed, if you want both Oxygen and XEP Docbench is the economical way to go.
I am not sure that the Docbench package contains the latest version of Oxygen (9.3) but you will receive a license for Oxygen 9.x and then you will be able to download and install the latest Oxygen 9.3 separately.

Regards,
Radu

[David Winter]

Indeed, if you want both Oxygen and XEP Docbench is the economical way to go.

Right now, what I see as a very attractive alternative is a $500 product called Prince XML (http://www.princexml.com/). It takes standard XML or XHTML files and generates beautiful PDF documents using CSS. This means you don't have to jump through all the XSL hoops (I find XSL-FO mind-boggingly complex, but maybe that's just me) to get print-quality output.

I am currently playing around with it, but if it works as I hope it does, I could author in XHTML, DITA or cook up my own little XML Schema, feed it to Prince and get very attractive PDFs.

I'll let you know how this goes. Thanks again.

[Radu]

Hi David,

As the Oxygen Author page presents the XML contents also using CSS you can find CSS files for each document type supported by Oxygen in the OXYGEN_INSTALL_DIR/frameworks directory.

Regards,
Radu

[hdenk]

Right now, what I see as a very attractive alternative is a $500 product called Prince XML (http://www.princexml.com/)

hello david, i firmly agree with you "xslt is over complex".
my situation seems exactly the same as yours. i am also doing
evaluations of dita + oxygen now and today had some problems
with conrefs .

as im not convinced of dita so far ... i'am very thankful
for hint's like yours. i will definitly look into prince too.

would be nice to hear from the outcome of your efforts ...

thank you & have a nice day

[David Winter]

would be nice to hear from the outcome of your efforts ...

Well, I'm still evaluating various options, and I'm torn to say the least.

I see all the theoretical potential of DITA - the semantic approach, all the efforts to generate help documents that will work on all relevant platforms etc.

On the other hand, I see that the typical DITA production chain will make me jump through a lot of hoops - and the files I get at the end still look considerably worse than what I get from a proprietary app like Help & Manual out of the box. And when things break, it's relatively hard to pinpoint the source.

To quote Star Trek: “I’m an author, Jim, not a coder.”

I currently think that I will move my technical documentation and translation business to an XML based format, and if I do, Oxygen will be my weapon of choice - it is available for Mac and Windows, it has good documentation, and obviously the support tries to keep/make users happy.

But I may consider an alternative to DITA - e.g. a home-brew format with less restrictions and a simple, yet aesthetically pleasing XHTML output.

To be continued.