Page 1 of 1

Differences between oXygen XLS and Sourceforge version

Posted: Mon Oct 07, 2013 6:36 pm
by Ioana
I am evaluating oXygen, trying to switch my company's old documentation to one platform. We currently generate PDF from DocBook using Eclipse and a set of XSL stylesheets that are similar to the ones at http://sourceforge.net/projects/docbook/files/. I've noticed that the XSL files in oXygen are a bit different from the files on SourceForge. Both sets seem to be version 1.78.1. Is there a reason for this? I'm trying to figure out if I should be able to use the regular XSL stylesheets or if maybe oXygen needs some special tweaks. I'm getting errors when I try to use the existing stylesheets, but I can generate everything OK with the "DocBook PDF" transformation in oXygen. I'd like to be able to use the existing files (they were customized by someone who is no longer in the company), but I don't know if I'm doing something wrong or not, so I'm trying to eliminate all variables... I'm using DocBook 5 in case it matters (converted from 4.5 using oXygen.)
(Sorry if I'm asking something obvious, I've been working with DocBook for 2 weeks and with oXygen for 1.)

For example:
On Sourceforge, docbook.xsl contains the following line (same in my company's version):

Code: Select all

<xsl:include href="../common/stripns.xsl"/>

But in oXygen, docbook.xsl has:

Code: Select all

<xsl:include href="../common/addns.xsl"/>


OR
Sourceforge and my company's version:

Code: Select all

 <xsl:choose>
    <!-- Hack! If someone hands us a DocBook V5.x or DocBook NG document,
         toss the namespace and continue.  Use the docbook5 namespaced
         stylesheets for DocBook5 if you don't want to use this feature.-->
    <xsl:when test="$exsl.node.set.available != 0
                    and (*/self::ng:* or */self::db:*)">
      <xsl:call-template name="log.message">
        <xsl:with-param name="level">Note</xsl:with-param>
        <xsl:with-param name="source" select="$doc.title"/>
        <xsl:with-param name="context-desc">
          <xsl:text>namesp. cut</xsl:text>
        </xsl:with-param>
        <xsl:with-param name="message">
          <xsl:text>stripped namespace before processing</xsl:text>
        </xsl:with-param>
      </xsl:call-template>
      <xsl:variable name="nons">
        <xsl:apply-templates mode="stripNS"/>
      </xsl:variable>
      <xsl:call-template name="log.message">
        <xsl:with-param name="level">Note</xsl:with-param>
        <xsl:with-param name="source" select="$doc.title"/>
        <xsl:with-param name="context-desc">
          <xsl:text>namesp. cut</xsl:text>
        </xsl:with-param>
        <xsl:with-param name="message">
          <xsl:text>processing stripped document</xsl:text>
        </xsl:with-param>
      </xsl:call-template>
      <xsl:apply-templates select="exsl:node-set($nons)"/>
    </xsl:when>
    <!-- Can't process unless namespace removed -->
    <xsl:when test="*/self::ng:* or */self::db:*">
      <xsl:message terminate="yes">
        <xsl:text>Unable to strip the namespace from DB5 document,</xsl:text>
        <xsl:text> cannot proceed.</xsl:text>
      </xsl:message>
    </xsl:when>


oXygen:

Code: Select all

  <xsl:choose>
   
    <xsl:when test="namespace-uri(*[1]) != 'http://docbook.org/ns/docbook'">
 <xsl:call-template name="log.message">
 <xsl:with-param name="level">Note</xsl:with-param>
 <xsl:with-param name="source"><xsl:call-template name="get.doc.title"/></xsl:with-param>
 <xsl:with-param name="context-desc">
 <xsl:text>namesp. add</xsl:text>
 </xsl:with-param>
 <xsl:with-param name="message">
 <xsl:text>added namespace before processing</xsl:text>
 </xsl:with-param>
 </xsl:call-template>
 <xsl:variable name="addns">
    <xsl:apply-templates mode="addNS"/>
  </xsl:variable>
  <xsl:apply-templates select="exsl:node-set($addns)"/>
</xsl:when>
    <!-- Can't process unless namespace removed -->
    <xsl:when test="namespace-uri(*[1]) != 'http://docbook.org/ns/docbook'">
 <xsl:call-template name="log.message">
 <xsl:with-param name="level">Note</xsl:with-param>
 <xsl:with-param name="source"><xsl:call-template name="get.doc.title"/></xsl:with-param>
 <xsl:with-param name="context-desc">
 <xsl:text>namesp. add</xsl:text>
 </xsl:with-param>
 <xsl:with-param name="message">
 <xsl:text>added namespace before processing</xsl:text>
 </xsl:with-param>
 </xsl:call-template>
 <xsl:variable name="addns">
    <xsl:apply-templates mode="addNS"/>
  </xsl:variable>
  <xsl:apply-templates select="exsl:node-set($addns)"/>
</xsl:when>

Thanks!

Re: Differences between oXygen XLS and Sourceforge version

Posted: Tue Oct 08, 2013 10:45 am
by sorin_ristache
Hello,

Ioana wrote:I am evaluating oXygen, trying to switch my company's old documentation to one platform. We currently generate PDF from DocBook using Eclipse and a set of XSL stylesheets that are similar to the ones at http://sourceforge.net/projects/docbook/files/. I've noticed that the XSL files in oXygen are a bit different from the files on SourceForge. Both sets seem to be version 1.78.1. Is there a reason for this?


The default Docbook transformations that come with the Oxygen install kit include some customizations of the stock DOcbook stylesheets from sourceforge.net/projects/docbook/. I understand that you also use a customized version of the Docbook XSL stylesheets, you just have different customizations than Oxygen.

Ioana wrote:I'm trying to figure out if I should be able to use the regular XSL stylesheets or if maybe oXygen needs some special tweaks. I'm getting errors when I try to use the existing stylesheets, but I can generate everything OK with the "DocBook PDF" transformation in oXygen.


If your Docbook XML documents are valid, which you can check with the action Validate available on the toolbar and on the Document -> Validate menu, the Docbook transformations that come with Oxygen will transform your XML documents without errors.

Ioana wrote:I'd like to be able to use the existing files (they were customized by someone who is no longer in the company), but I don't know if I'm doing something wrong or not, so I'm trying to eliminate all variables... I'm using DocBook 5 in case it matters (converted from 4.5 using oXygen.)


Do you mean the existing Docbook XML files containing your documentation, or your existing customized Docbook XSL stylesheets? Your existing XML files will work without problems with the Oxygen Docbook transformations, if they are valid Docbook XML documents. For your customized Docbook XSL stylesheets, if you want to keep the XSL customizations you have to add them in the Docbook XSL files from directory [Oxygen-install-dir]/frameworks/docbook/xsl.


Ioana wrote:For example:
On Sourceforge, docbook.xsl contains the following line (same in my company's version):

Code: Select all

<xsl:include href="../common/stripns.xsl"/>

But in oXygen, docbook.xsl has:

Code: Select all

<xsl:include href="../common/addns.xsl"/>


OR
Sourceforge and my company's version:

Code: Select all

 <xsl:choose>
    <!-- Hack! If someone hands us a DocBook V5.x or DocBook NG document,
         toss the namespace and continue.  Use the docbook5 namespaced
         stylesheets for DocBook5 if you don't want to use this feature.-->


Oxygen includes the namespace-aware version of the Docbook XSL stylesheets. Your Docbook XSL customizations are applied to the no namespace version of Docbook XSL (stripns.xsl means "an XSL that strips the Docbook namespace", addns.xsl means "an XSL that adds the Docbook namespace if it is missing"). You should skip the namespace related customizations in your XSL stylesheets and add the other Docbook XSL customizations (only of you want to keep their final effect in the transformation result) to the Docbook XSL stylesheets that come in the Oxygen install directory.


Regards,
Sorin

Re: Differences between oXygen XLS and Sourceforge version

Posted: Tue Oct 08, 2013 12:39 pm
by Ioana
Multumesc, Sorin! That's exactly what I was looking for. I'll re-add our customizations to the oXygen templates and hope everything goes well. Thanks a lot for the detailed explanations!

Re: Differences between oXygen XLS and Sourceforge version

Posted: Tue Oct 08, 2013 1:01 pm
by sorin_ristache
You are welcome! Please let us know if you get errors or you have trouble migrating your Docbook XSL customizations.


Regards,
Sorin