DITA and XMetaL Discussion

XMetaL Community Forum DITA and XMetaL Discussion DITA OT error: The entity "nbsp" was referenced, but not declared.

  • Derek Read

    DITA OT error: The entity "nbsp" was referenced, but not declared.

    Participants 1
    Replies 2
    Last Activity 10 years, 2 months ago

    XMetaL Author Enterprise 7.0 (running DITA OT version 1.5.4)
    Later versions will very likely continue to be equally affected.

    Generating output fails and the following error appears in the DITA Open Toolkit output log file (log.xml opened in XMetaL):

    [conref] ::: Fatal Error! Error reported by XML parser Cause: org.xml.sax.SAXParseException: The entity”nbsp” was referenced, but not declared.

    The DITA OT defaults to running the XML parser it uses for transformations with a mode called “parser grammar caching” turned on. When character entities are used that feature will throw this error. Enabling the feature is meant to speed up processing so that the DITA OT can generate output faster.

    Turn off “parser grammar caching”. See the note listed next to the parameter named args.grammar.cache on this page:

    Resolution Instructions for XMetaL Author Enterprise 7.0
    Add the parameter named args.grammar.cache and set its value to “no”.

    1. Launch XMetaL Author Enterprise 7.0.
    2. From the Tools menu select Configure Output…
    3. In the Configure Output dialog switch to the Advanced tab.
    3. On the Advanced tab inside the textbox at the bottom labelled “Other output parameters” add the following on a separate line exactly as follows:
    ANT_PARAM_args.grammar_cache = no
    *Do not change any other settings.*
    5. Select OK to dismiss the dialogs and save this new parameter.

    You should now be able to use in your DITA topics.

    This should only be considered a temporary solution as the DITA TC at OASIS has placed the following note into the DITA DTDs suggesting they plan to remove the declaration for this character entity reference from future versions of the DITA DTDs:

    [quote=DITA 1.2 DTD topic.mod file]

    So, with future versions of the DITA DTDs, DITA files containing this entity would be invalid XML. Any XML parser parsing your files would need to tell you that and terminate processing (part of the XML Recommendation). That would include both XMetaL and the XML parser being used by the DITA OT (regardless of settings) which is usually either Saxon or Xerces.

    Use an actual NO-BREAK SPACE (official Unicode character names are all uppercase) character instead of the entity. If you insert the character itself and not the entity then the DITA OT (specifically, the parser processing your files) will not complain. Your files should also be valid when you move to the next version of DITA, if those DTDs do stop declaring this entity. If they do stop declaring this entity the only way to continue to use it would be to alter the DTDs (I would not recommend that) or to declare the entity in every XML file you wish to use it in.

    You can use your Windows numeric keypad keys and the “numpad Alt sequence” method for entering this character (as you can with most Windows applications). The numpad character entry sequence is: Alt+255.

    An alternative would be to use the Windows “Character Map” tool. You can copy any character and paste it into a document, including a “NO-BREAK SPACE” (which charmap.exe lists in camelcase as “No-Break Space”). If you use an IME (common with complex languages such as Japanese, Chinese, Korean, etc) you may also find a method for inserting this character there.



    Reply to: DITA OT error: The entity "nbsp" was referenced, but not declared.

    Hi Derek,
    I updated the Configure Output as you described. But I am still getting the error because of 'nbsp' when i publish webhelp.
    i attached the screenshot.

    I included that in Configuration Output Option / Advanced tab. I also tried adding it in webhelp output in advanced. but did not help.

    Any idea what could i have done wrong?

    xmetal version:

    will really appreciate,

    with best regards,


    Derek Read

    Reply to: DITA OT error: The entity "nbsp" was referenced, but not declared.

    Not sure. It could be that your version (which I think is the first version of 7 that we released) includes an older version of the DITA OT that doesn't support that parameter. When I tested this and posted this forum posting I was probably running (my mistake for not recording the full version in that post).

    I don't see the same issue with XMetaL Author Enterprise 9 (which includes DITA OT 1.8). It looks like newer versions of the DITA OT actually strip this entity out completely resulting in content being run together without any spaces at all. Perhaps that is one more reason to avoid its use (the other being that your files will eventually be treated as invalid once the DTDs for 2.0 are released and if you use them). Using a NO-BREAK SPACE character still gives you the expected output.


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

Lost Your Password?