DITA and XMetaL Discussion

XMetaL Community Forum DITA and XMetaL Discussion How to add custom footer text for PDF?

  • harkavyr

    How to add custom footer text for PDF?

    Participants 5
    Replies 6
    Last Activity 13 years, 11 months ago

    I haven't had much success doing this. Rather than post the steps that I've gone through with the guidance of XMetaL's online help, can someone please tell me what I need to do to simply add a string of text to the existing PDF footer? Thanks.


    Derek Read

    Reply to: How to add custom footer text for PDF?

    Appendix B in the help for XMetaL Author Enterprise 5.1 says one supported method to do what you want is to use parameters that we've configured for use (only) with the “XMetaL Enhanced PDF via RenderX XEP” deliverable type (what you select from the dropdown in the Generate Output dialog). The file it talks about is this one: [xmfo]Customizationfoxslcustom.xsl

    You will need to find the ..xmfo folder installed inside the copy of the DITA OT that was installed with your copy of XMetaL Author Enterprise. The docs try to describe this, but it sounds like they are not clear enough. They are unable to assume you have installed the product to any particular predetermined location or that you are running a particular Windows version or even language so the paths they provide must be figured out by you based on your particular installation. For example, even if you install to the default path suggested by our installer the folder C:Program Files in English has different names on different language versions of Windows. Installing to Citrix will add even more complexity, etc.

    To make things simple for what is possibly the most common scenario, let's hope this matches your setup (if it doesn't please let me know):
    – You are running XMetaL Author Enterprise 5.1 on English Windows XP.
    – You have a folder called C:Program Files where Windows normally installs your software.
    – You accepted the default installation path suggested during installation.
    – You are using the deliverable called “XMetaL Enhanced PDF via RenderX XEP” when you select the option “Generate Output for DITA Map…” on the File menu.

    In that case the path to the file you will place parameter values in, as described in the docs, will (probably) be here:
    C:Program FilesCommon FilesXMetaL SharedDITA_OTdemoxmfoCustomizationfoxslcustom.xsl

    As an example, let's change the footer for the even pages of the “body” section of the PDF document (not the TOC, Index, or elsewhere, which have different sections). I want the three sections of my footer (left, middle and right) to have the proportions 1:10:3 because I plan to cram a bunch of text in the middle but I also suspect that my titles might be fairly long. I'm assuming my page numbers will not take up much room. That 'static' text will be “TESTING TESTING 123 HELLO WORLD”. The left part will contain the current page number and the right will contain the document title (which is extracted from the map). All of the parameters that are currently supported are documented in Appendix B (in the 5.1 help).

    Open C:Program FilesCommon FilesXMetaL SharedDITA_OTdemoxmfoCustomizationfoxslcustom.xsl in a text editor and after the following comment…

    …add these lines:
    [code]1 10 3


    Note that even this sort of assumes some understanding of XSLT. There really is no way around that at this time given the way the DITA OT works (and our integration with it).

    It is very easy to make a typo when editing the XSLT, so I recommend making small changes, generating output, checking the output log file for errors and cycling through that pattern until you get what you want. Making large changes or many changes at once will obviously introduce more chances for typos. Errors in the output log file (if any) will probably mention “FO” or “XSLT”.

    The first page the text “TESTING TESTING 123 HELLO WORLD” will appear on in the PDF is physical page 4, as that is the first even page in the body of the document (which by default appears after the TOC). Page 3 in this case will not have this text because we did not add settings for that section (which is …body_odd_footer…).

    Appendix B (in the 5.1 release) also talks about modifying the “real” XSLT that generates output but I will not get into that here because that really requires a good handle on XSLT / XSL-FO and it is also something you will not want to try using a text editor like Notepad. You would need to do that in cases where we have not parameterized something (like inserting the date for example, or other things that might even be less complex). It is best to have a proper XSLT editor that also ideally includes a good “find in files” feature so you can hunt down all the bits and pieces that control various things. Our Professional Services team does this type of work regularly and on contractual basis for clients.



    Reply to: How to add custom footer text for PDF?

    Okay, I modified C:Program FilesCommon FilesXMetaL SharedDITA_OTdemoxmfoCustomizationfoxslcustom.xsl with those lines and there was no change.

    Afterwards, I went to Tools > Configure Output, selected XMetaL Enhanced PDF via RenderX XEP, chose Edit, and on the Advance tab I specified the XSL file under XSL Style Sheet. Still no change.

    Any ideas?


    Derek Read

    Reply to: How to add custom footer text for PDF?

    The previous instructions in this post were meant for 5.1 (I took a guess because much of our install-base is still running that version).

    XMetaL Author Enterprise 5.5 DITA OT “Deployment”

    NOTE: this post applies to the 6.0 release as well as this functionality has not been altered.

    With XMetaL Author Enterprise 5.5 we have implemented a method of deploying the DITA Open Toolkit so that even “Limited Users” (ie: hopefully anybody) can run it. The XMetaL Author Enterprise 5.5 installer places a copy of the DITA OT in %PROGRAMFILES%. However, the DITA OT needs to write to the location it is installed to so that is a problem. For “Limited Users” %PROGRAMFILES% is typically read-only so running the DITA OT in that location will fail unless you have write permission for that folder. Most “Adminstrators” have this right (but not all and Vista UAC can also be troublesome). We also needed to allow multiple users to run the DITA OT as a Windows machine allows multiple users to use it (by logging in with different user accounts).

    To get around these issues, the first time you generate output XMetaL Author Enterprise 5.5 first deploys a copy of the DITA OT into the Windows %APPDATA% folder structure, which is separate for each logged in user of the machine.

    The closest I can get to a human readable (less geeky) path for %APPDATA% is the following:

    English XP (common, but your IT dept may set otherwise) =
    C:Documents and SettingsApplication Data

    English Vista (common, but your IT dept may set otherwise) =

    To all of the above add the following to the end to find the DITA OT folder on your system:
    SoftQuadXMetaL Shared

    Some examples for %APPDATA% + deployed copy of the DITA OT:
    C:Documents and SettingsApplication DataSoftQuadXMetaL Shared
    C:UsersAppDataRoamingSoftQuadXMetaL Shared
    C:ProfilesAppDataSoftQuadXMetaL Shared

    Typical example for %PROGRAMFILES% + installed copy of the DITA OT:
    C:Program FilesCommon FilesXMetaL Shared

    The contents of the folder %PROGRAMFILES%Common FilesXMetaL Shared will be copied into %APPDATA%SoftQuadXMetaL Shared the first time you generate output.

    So, having (tried) to explain where you can find these things, you have several options for modifying the DITA OT for your end users:

    A. Modify an already deployed copy of the DITA OT
    This only affects one user on this computer. Other logged-in users of the machine will not see these changes as they will have their own deployed copy of the DITA OT.
    1. Install XMetaL Author Enterprise 5.5.
    2. Open a DITA document (topic or map).
    3. Generate output. This is when the DITA OT is first deployed to the currently logged in user's %APPDATA% folder.
    4. Locate the files you wish to modify in the deployed copy of the DITA OT and modify them as desired. All subsequent calls to generate output will use the same deployed copy of the DITA OT.

    B. Modify the installed copy of the DITA OT before deployment
    This will affect any logged in user that is allowed to run XMetaL Author Enterprise. Any user generating output will receive your modified copy of the DITA OT as part of the very firstĀ  deployment phase for that user.
    1. Install XMetaL Author Enterprise 5.5. Do not generate output using the DITA OT via XMetaL Author Enterprise's UI.
    2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired. Now any user that generates output, provided they have not already done so, will have your modified copy deployed to their %APPDATA% folder.

    C. Modify the installed copy after deployment and force redeployment
    This will still work even if a logged in user has done either of the above.
    1. Install XMetaL Author Enterprise 5.5.
    2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired.
    3. Tell any user that wishes to deploy your modified version of the DITA OT to add the following parameter to Tools > Configure Output… > Advanced (tab) > Other output parameters (textbox): cmd_dita_ot_per_user_version =
    needs to be an integer greater than the one they used last (starting with at least 1). Using the date in the form yyyymmdd (ie: 20090309) is one good way to keep track of this, otherwise just add 1 to the last number specified.
    4. The next time any user generates output (provided they have performed step 3) they will be asked if they wish to update the DITA OT. They must answer “OK” to this prompt. The DITA OT will then be redeployed from the %PROGRAMFILES% location (which you modified) to the %APPDATA% location before running it from the %APPDATA% location.

    Administrators automating this process may which to view this post: [url=http://forums.xmetal.com/index.php?topic=180.0]http://forums.xmetal.com/index.php?topic=180.0[/url]

    D. Modify the installed copy and delete any previously deployed version
    1. Install XMetaL Author Enterprise 5.5.
    2. Locate the files you wish to modify in the installed copy of the DITA OT inside %PROGRAMFILES% and modify them as desired.
    3. Delete the copy of the DITA OT deployed to the %APPDATA% folder.
    4. The next time output is generated XMetaL Author Enterprise will see that there is no deployed copy of the DITA OT and will deploy it.

    Note: This is all true only when the following default setting in present in the xmetal55.ini file user_setting_mode=per_user. That INI value should not be altered for the vast majority of installations. The XMetaL Author Enterprise 5.5 install-readme.html file contains information on the usage of this INI variable.

    The following Wikipedia page contains more information on [url=http://en.wikipedia.org/wiki/Environment_variable#Default_Values_on_Microsoft_Windows]Windows Environment Variables[/url].



    Reply to: How to add custom footer text for PDF?

    I am able to modify custom footer for the pdf as you indicate. Is it possible to add number of pages also to the footer?
    I see that the xmPageNumber adds the current page number, but how do I add total number of pages to display something like “Page X of Y” on the footer or header?
    Is there something called $xmPageCount or $xmTotalPages? I tried these variables but output failed with these..


    Derek Read

    Reply to: How to add custom footer text for PDF?

    I don't believe RenderX XEP will allow you to check total number of pages until the intermediary format that XEP uses has been produced. So, to answer your question, there is no easy way to do this (no variable, etc) that I know of. Getting the total page count would probably be fairly complicated to set up as additional processing that the DITA Open Toolkit is not designed to do would probably be necessary.

    Information on the XEP intermediary format is located here:

    There is a element that contains a page-number attribute. Presumably you would just need to extract the last value and then inject it into the rest of the locations in that file you want it to appear (sounds easy but I don't think it will be).

    If you really need this and are not able to do figure it out our Professional Services team or one of our partners might be able to do it for you. Our sales team can put you in touch.



    Reply to: How to add custom footer text for PDF?

    Thanks Derek,
    This was useful information.
    I will get confirmation on criticality of having this and contact you if needed.


  • You must be logged in to reply to this topic.

Lost Your Password?