Chemistry: Omit Cover Page and TOC?

[cud]

Hi all... For reasons of my own, I want to generate a DITA Map such that I get a single PDF file with all the topics in place. But I don't want a cover page or a TOC. I just want the first page to begin with the title of the first topic.

Following instructions, I copied the DITA map PDF - WYSIWYG transform and customized my copy -- Is there a way to tell this transform to omit these pages, or does that require a plugin change?

Thanks... cud

[Dan]

You could try something like:

Code: Select all

*[class ~= 'map/map'] > map {

    display:none !important;

}

*[class ~= 'map/map'] > front-page{

    display:none !important;

}

Many regards,
Dan

[cud]

Hi Dan... Thanks.

This works to a point. The cover page seems to be gone and the TOC is gone. However, the PDF begins with a blank page one. But this is closer than I could get otherwise!

[Dan]

Hi,

In the next oXygen version there will be extension points for XSLT processing of the merged DITA map. Until then you can try to modify the post-process.xsl file from the DITA-OT that comes with oXygen:
[OXYGEN_INSTALL_DIR]/frameworks/dita/DITA-OT2.x/plugins/com.oxygenxml.pdf.css/xsl/post-process.xsl

Add the following template at the end of the file:

Code: Select all

    <xsl:template match="*[contains(@class, ' map/map ')]" priority="300">

      <xsl:copy>

        <xsl:apply-templates select="@*"/>

        <xsl:apply-templates select="* except (oxy:front-page, opentopic:map, opentopic-index:index.groups)"></xsl:apply-templates>

      </xsl:copy>

    </xsl:template>

I added the "opentopic-index:index.groups" to skip also the index.

Take care when you are upgrading oXygen.

We are also thinking about some built-in parameters to control the generation of toc, front page and index.
Many regards,
Dan

[carlisaac]

I'm also having this issue but have discovered that the post-process.xsl file doesn't exist under the path given. Any thoughts on how to rectify this?
Thanks!
Carl

[Dan]

In case you are using the WYSIWIG transformation scenario you can add the template to the file:
[DITA-OT-DIR]/plugins/com.oxygenxml.pdf.css/xsl/merged2merged/merged.xsl


In case you are using the HTML5 based PDF transformation (not WYSIWYG), this is the recommended transformation now, you may use an oxygen publishing template package to customize the output. This package allows the specification of XSL extensions to filter out the content. The benefit of the publishing template is that you do not need to change files in the oXygen installation folder.

A complete tutorial may be found here:
https://www.oxygenxml.com/doc/versions/ ... plate.html
And a video presentation is here:
https://www.oxygenxml.com/demo/opt.html

You should place the XSL fragment in a file "my.xsl" inside the publishing template folder:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

    xmlns:xs="http://www.w3.org/2001/XMLSchema"

    exclude-result-prefixes="xs"

    version="2.0"

    xmlns:oxy="http://www.oxygenxml.com/extensions/author"

    xmlns:opentopic="http://www.idiominc.com/opentopic"

    xmlns:opentopic-index="http://www.idiominc.com/opentopic/index"

    >

    

    <xsl:template match="*[contains(@class, ' map/map ')]" priority="300">

        <xsl:copy>

            <xsl:apply-templates select="@*"/>

            <xsl:apply-templates select="* except (oxy:front-page, opentopic:map, opentopic-index:index.groups)"></xsl:apply-templates>

        </xsl:copy>

    </xsl:template>

    

</xsl:stylesheet>

Then refer the file from the publishing template descriptor (the .opt) file:

Code: Select all

...

        <xslt>

            <extension file="my.xsl" id="com.oxygenxml.pdf.css.xsl.merged2merged"/>

        </xslt>

    </pdf>

</publishing-template>

Best regards,
Dan

[cud]

Thanks much, Dan...

I'm finally able to think about this again.

I have updated to 20.1, and I use the HTML5 based PDF transformation. I have to say it is ingenious. One of the hardest things to do in software is produce a configurable, horizontal layer on top of a technology so that people can use it for a variety of results. This template approach does that really well. It's a pleasure to use, compared to tweaking the OT.

It's interesting that the ID you provide in the XSLT reference indicates the transform entry point. Does that mean you can only have one XSLT file per entry point, per template? (Just curious)

That said, I tried your approach, and I still get the same results... It doesn't produce a title page or a TOC, but it does produce a blank page at the start of the PDF file. I would like it to simply start with the first topic in the map. Is there something obvious I'm doing wrong here?

(FYI... I'm trying to produce release notes. I just want a single PDf file that has nothing but the content. The top-level topic that contains all the other topics is the intro topic. It's title should be at the top of page 1, followed by the intro body, and then the titles (and bodies) of the nested topics. Title page and TOC are overkill for this document.)

[Dan]

Please add to your customization CSS the following snippet:

Code: Select all

*[class~='topic/topic'][is-chapter] {

-oxy-page-group : auto;

}

This should fix the page breaking problem.

The customization CSS can be referred from the template descriptor, or passed as the args.css parameter to the transformation scenario.

The XSL extension point cand refer a single XSL file. You can organize the XSL further as you wish, you may use imports and includes.
The other extension point, named "com.oxygenxml.pdf.css.xsl.merged2html5" can be used to override de basic XSLT processing from the org.dita.html5 plugin that is used in the last stage. You just copy here and modify the named templates from this plugin.

Let me know if it worked for you,
Many regards,
Dan

[Dan]

I tested again a snippet from a previous post, and the empty page dissapears if adding the last selector:

Code: Select all

*[class ~= 'map/map'] > *[class ~= 'toc/toc'] {

    display:none !important;

}

*[class ~= 'map/map'] > *[class ~= 'front-page/front-page']{

    display:none !important;

}

*[class~='topic/topic'][is-chapter] {

  -oxy-page-group : auto;

}

In this way there is no need of XSLT processing or customization template. Please confirm that it works for you.
Cheers,
Dan

[cud]

Ta Dah!!! Yes, this works! Thanks much.

Out of curiosity, can you explain what's happening with the last selector and rule? It looks kind of important!

[cud]

I also verified that injecting the XSLT into com.oxygenxml.pdf.css.xsl.merged2merged also works, so long as you include that last selector/rule. So indeed that is the secret sauce. Should I have been able to find this in the docs?

[Dan]

I am glad it worked!

I added more info about your usecase to the userguide of the DITA CSS PDF plugin, it will be available when we release the next version.
The built-in CSS rules contain something like:

Code: Select all

*[class~='topic/topic'][is-chapter] {

  -oxy-page-group : start;

}

The "start" value makes the chapters always start on a new page group (or sequence). In our case it created a forced break between the HTML parts that were before the first topic (the HTML head and other elements with no content) and the first topic.

This property is discussed in the Chemistry processor userguide (not the DITA related one): https://www.oxygenxml.com/doc/versions/ ... page-group

Many regards,
Dan

[cud]

Thanks Dan. So the point is that internally the HTML has "content" that the pagination considers to be on a page? It's odd behvior, so yes -- you should include that use case in the styling docs. I really appreciate the help and quick turnaround.

[carlisaac]

This also works in my case. Thanks for all of your help, Dan!

[cud]

The update to version 21 has an odd effect. If the map has a title, then the process seems to NEED to insert a page for it. Since we suppress the front page, it seems to insert a chapter page instead? And since we don't tell the chapter page to pick anything up, it's just a blank chapter page. Also, the PDF bookmarks include an entry for this page PLUS an empty entry bookmark that is probably for the suppressed TOC (no page to display, no title in the bookmark list -- just a bookmark icon).

Curious behavior. I just stumbled on the fix (delete title from the map element) as I was explaining this problem, and trying to provide details. I wanted to ensure the first page got the bookmark title from the map title so I deleted it. And viola -- problem solved. I'm guessing this is an unexpected side effect of other css-related fixes?

The whole processing flow here is too mysterious, with too many dependencies. I would gladly attend a session that taught me how to think like this process.

As far as I can recall, these are the statements that keep me from showing TOC or Cover Page:

*[class ~= 'map/map'] > *[class ~= 'toc/toc'] {
display:none !important;
}
*[class ~= 'map/map'] > *[class ~= 'front-page/front-page']{
display:none !important;
}

[cud]

Wait, no... I spoke too soon. The wrong result file popped up and I was drugged by optimism. For version 21, if you suppress the front page, then the process insists on posting a blank chapter page that picks up the map's title attr, and then a blank bookmark for a TOC.

If you remove the title from the map, then you still get the empty chapter page, but you only get one blank bookmark.

THis is a show stopper for me -- gotta put out release notes today. Will now try stepping back to the previous version.

[Costin]

Hello,

Note that we've added a dedicated parameter in the new version 21 and which can be used to suppress the front-page, toc, indexlist and glossary.
Maybe this helps, as no blank pages are inserted in the PDF. The parameter can be used without being necessary to write your own CSS rules to achieve this.

Just look in the transformation scenario from v21 (Parameters tab) for the "hide.frontpage.toc.index.glossary" parameter and set it to "yes".

Does this help?

Regards,
Costin

[cud]

Ok, thanks. Found it and it works. After you telling me this, I did search for it in the docs and didn't find it. Probably just that I don't know where to look...

[GLA]

Just look in the transformation scenario from v21 (Parameters tab) for the "hide.frontpage.toc.index.glossary" parameter and set it to "yes".

Does this help?

Regards,
Costin

Hi - I tried this too and it worked like a charm! However, I noticed that the generated PDF has an extra Document Title bookmark (with no nested bookmarks) at the very top. How can I prevent this extra bookmark from generating?

Thanks!

[Costin]

Hi,

Yes, it is intended behavior to always add the title of the DITA Map as the first bookmark in the PDF, because many users would like to know which is the title of the documentation they are currently viewing and to navigate to the top.
There is no parameter you could use to hide it.

However, if it is mandatory for you to hide that title and its corresponding bookmark in the PDF, you could just remove the "title" attribute from the root <map/> element in your .ditamap source file.

Regards,
Costin

[julien_lacour]

Hello,

The single DITA Topic publishing is available starting with Oxygen 22

Transform Individual DITA Topics to CSS-based PDF Output
A new transformation scenario called DITA PDF - based on HTML5 & CSS can be used to transform a single DITA topic to CSS-based PDF output. It automatically detects the current root map to resolve keys properly and detects the current profiling condition set for proper filtering. Similar to the DITA Map version of this transformation scenario, you can use a publishing template or custom CSS to style the output.

Regards,
Julien