Wednesday, April 29, 2015

DITA PDF publishing - Force page breaks between two block elements

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Let's say that at some point in your DITA content you have two block level elements, like for example two paragraphs:
        <p>First para</p>
        <p>Second para</p>
and you want to force in the PDF output a page break between them.
Here's how a DITA Open Toolkit plugin which would achieve this could be implemented:
  1. You define your custom processing instruction which marks the place where a page break should be inserted in the PDF, for example:
            <p>First para</p>
            <?pagebreak?>
            <p>Second para</p>
  2. In the DITA Open Toolkit distribution in the plugins directory you create a new plugin folder named for example pdf-page-break.
  3. In this new folder create a new plugin.xml file with the content:
    <plugin id="com.yourpackage.pagebreak">
      <feature extension="package.support.name" value="Force Page Break Plugin"/>
      <feature extension="package.support.email" value="support@youremail.com"/>
      <feature extension="package.version" value="1.0.0"/>
      <feature extension="dita.xsl.xslfo" value="pageBreak.xsl" type="file"/>
    </plugin>
    The most important feature in the plugin is that it will add a new XSLT stylesheet to the XSL processing which produces the PDF content.
  4. Create in the same folder an XSLT stylesheet named pageBreak.xsl with the content:
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:fo="http://www.w3.org/1999/XSL/Format"
        version="1.0">
      <xsl:template match="processing-instruction('pagebreak')">
        <fo:block break-after="page"/>
      </xsl:template>
    </xsl:stylesheet>
  5. Install your plugin in the DITA Open Toolkit by running the DITA OT ANT integrator task.

    If you are running the publishing from Oxygen XML Editor you can use the predefined transformation scenario: http://www.oxygenxml.com/doc/ug-oxygen/#topics/dita-ot-install-plugin.html.

    If you run DITA OT from the command line please follow these guidelines: http://www.dita-ot.org/2.0/dev_ref/plugins-installing.html.

The plugin code was also made available by Roger Sheen on GitHub:
https://github.com/dita-community/org.dita-community.pdf-page-break

Wednesday, April 15, 2015

A set of rules for providing great tech support

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

I've been doing technical support for more than 10 years and I feel that I've gathered a few ideas about what great tech support would be. And doing tech support the right way can be great both for product users and for the product developer as it provides lots of opportunities to further enhance and steer the application.

  1. Never say never. Never assume for certain that a feature request will not get implemented. Just register it and wait for feedback from others. I've had so many cases in which requests which initially seemed not worthy of implementation became important features in later versions.
  2. When asked for a solution to a specific problem, give the solution but also provide a sequence of deductive steps you took in order to find the solution. So give them the fish but also discuss about how they can fish for themselves. Help people evolve and you will have less tech support to do.
  3. Try to steer conversations as much as possible from private emails to forums and public user lists. These become repositories of knowledge and you'll avoid explaining the same thing multiple times if there is already a place on the web explaining it.
  4. In order to avoid answering the same question multiple times you have the following constructive options:
    • Add a topic in the product's User's Manual explaining the problem
    • Improve the product so that it becomes easier to perform those particular tasks.
  5. Some of our users know more and work more with certain aspects of the application than we do. So when certain work-flows are not appropriate for them, it's important that you listen and possibly change the application accordingly.
  6. Whenever an older behavior is changed in the application, even if you consider that the change is for the better, you will get complaints. And you will need to decide if users just need a time to adjust to the changes or if you've taken the application in the wrong direction.
  7. You may get asked questions which are not particularly related to what the application does. But you might still be able to give your personal opinion and a few useful links to get your client moving in the right direction.
  8. You will gain access to various user samples and work with the application to reproduce certain problems. Various times while working with the application to reproduce a problem you will also notice other behaviors which can be improved as well. Contribute all those side-effect suggestions to your issues list as well.
  9. Make it as easy as possible for people to report problems or to ask questions about the product. For example in Oxygen in the Help menu we have a "Report Problem" action which can be used to quickly report to us any issue which may arise while using the application.
  10. Always try to provide a feasible workaround for a bug or for a lack of functionality.

If you have more ideas about this, please share them with me.