Include comments in PDF output

[P4jjb]

Hi,

My team's engineers prefer to review using PDFs.
How do I include both comments and link text in PDF output for their review?

Comments are excluded from the default PDF transforms, but you can use File > Print to create a PDF that displays comments. However, this PDF doesn't include the link endterm text.

Or is there an option I can set in a duplicated PDF transform scenario that enables comment display?

Thanks.

[Radu]

Hi,

You are using Docbook, right?

If you use Oxygen's own way of adding comments (the "Add Comment" toolbar action), what Oxygen does to mark comments in the XML code is to add custom processing instructions which do not influence the published content of the XML in any way. If you want to see these comments in the Docbook PDF output you would need a customization stylesheet which would somehow convert our processing instructions to specific XSL-FO elements, this would not be an easy task.

Other two workarounds:

1) If you use File->Print indeed you get the comments in the printed output (and you can print to PDF this way). And in Oxygen 14.2 when editing content in the Author mode the links will also show static text which is obtained from the target elements. So the printed version should also have the link text in place.

2) Docbook has a special element called remark:

http://www.docbook.org/tdg/en/html/remark.html

You could use that element to add comments to Docbook content. The PDF output does not show them by default but you can edit the PDF transformation scenario, click the "Parameters" button and set the parameter draft.mode to yes. These comments are not as pretty or flexible as Oxygen's comments though.

Regards,
Radu

[P4jjb]

Hi Radu,

Thanks! Some followup questions:

1. Do remarks appear only in a PDF with draft.mode set to "yes"? I duplicated a WebHelp transform and set the draft.mode, but the remarks did not appear in the WebHelp output.

2. Which XSL do I need to modify so the remark text displays in red in the PDF? As it currently displays as black italicized font, it's easy to miss it or mistake it for a book reference.

[Radu]

Hi,

1. Do remarks appear only in a PDF with draft.mode set to "yes"? I duplicated a WebHelp transform and set the draft.mode, but the remarks did not appear in the WebHelp output.

Sorry, it seems that the actual parameter which controls remarks is show.comments which by default is set to "1" (which means that it shows the remarks). You can set it to "0" to hide them.

About making this work in WebHelp, the WebHelp publishing is done using an ANT script. In Oxygen 14.2 (which will be released in a couple of weeks) you will be able to configure this draft.mode parameter by editing the transformation scenarios directly but right now you must edit the ANT build file:

OXYGEN_INSTALL_DIR/frameworks/docbook/xsl/com.oxygenxml.webhelp/build_docbook.xml

and set the draft.mode parameter as an XSLT parameter when the XSLT stylesheets are called.

2. Which XSL do I need to modify so the remark text displays in red in the PDF? As it currently displays as black italicized font, it's easy to miss it or mistake it for a book reference.

In this XSL OXYGEN_INSTALL_DIR/frameworks/docbook/xsl/fo/inline.xsl there is an xsl:template like:

Code: Select all

<xsl:template match="d:comment|d:remark">

  <xsl:if test="$show.comments != 0">

    <fo:inline font-style="italic">

      <xsl:call-template name="inline.charseq"/>

    </fo:inline>

  </xsl:if>

</xsl:template>

which you can change (or create an XSLT customization which overrides the template) something like:

Code: Select all

<xsl:template match="d:comment|d:remark">

  <xsl:if test="$show.comments != 0">

    <fo:inline font-style="italic" color="red">

      <xsl:call-template name="inline.charseq"/>

    </fo:inline>

  </xsl:if>

</xsl:template>

You should also try to join the Docbook users List, it is also a good place where to ask customization questions.

Regards,
Radu

[Frank Ralf]

We have the same feature request for DITA content transformed to PDF. The users want to see the review comments from oXygen also in PDF. Is there a similar workaround for DITA?

TIA
Frank

[Radu]

Hi Frank,

When you edit with Oxygen a DITA topic there are two ways in which you can add comments to your content:

1) Using the Oxygen toolbar->Add Comment action. This action adds the comment as an XML processing instruction which can only be properly rendered by Oxygen. So this comment will not be visible in the PDF output if you publish the DITA Map to PDF.

2) Adding DITA-specific draft-comment elements. If you take this approach and edit the transformation scenario used to publish to PDF from Oxygen, in the Parameters list there is a parameter called args.draft which can be set to yes and the published PDF will also contain the comments.

Regards,
Radu

[Frank Ralf]

Hi Radu,

Thanks for the pointers!

Cheers,
Frank