BUG: Serna Free and "Serna: Critical Error" fo controller error

I'm blogging this here because I encountered this error with Serna Free XML Editor before, and when I went back to search for it on their forums it was nowhere to be found. This bug was found in the Serna Free 4.3 version, packaged as an RPM. It has taken me a good 5 hours to diagnose this issue in a user guide I was working on. I'll record my findings in a bug-style format. Hopefully it helps you diagnose this issue if you find it.

tl:dr

The solution for me was to ensure entities containing XML markup were not nested in tags like <literal> or similar XML markup. Even though my XML code was valid to DocBook 4.5, it seems Serna has a problem rendering this element combination in WYSIWYG mode.

If you choose an Entity file to store all your entity declarations (rather than declaring entities in each XML file comprising your book), you must ensure each XML file has a parameter entity in the DOCTYPE declaration of each XML file that points to the file. Serna needs this to parse entities correctly.

Read on for the full brain dump below and more info about the stuff I mentioned above.

Issue

Serna Free v4.3 (referred to as Serna from this point on) can not open a large XML file in "Open Normally" mode without crashing with an "fo controller" error.

Details


I have a guide that is over 200 (serna) pages long, and after adding some entities to replace long file paths, the guide would not open.

This problem started to present after replacing some file names with a local entity containing a full file path, complete with XML markup.

<!FILEPATH "<filename><replaceable>VERY</replaceable>/long/<replaceable>path&</replaceable>/to/the/config-file.xml</filename>">

I went to lunch while Serna was open and when I came back and tried to resume adding the local entities to the book, the Add Entity catalog would not display the local list of entities.

I closed Serna. That is when I found the problem in $Issue.

Serna would try to open the document and expand all sections, however it got to about (serna page) 71 and then the Serna: Critical Error displayed.

Troubleshooting

Level 1

I checked the following:

1. All XML files had correct external (parsed) parameter entity declarations in the DOCTYPE declaration [1]. Serna needs parameter entities declared in each file in the book, so it has access to the entity catalog file (saved as .ent) for the book.
2. The book was well-formed and valid.
3. The book built using a documentation build chain (in this case Publican).

All these items checked out.

Level 2

I opened the document in "Collapsed Mode" and manually expanded each Chapter and Section from the beginning until I got up to about page 65. Serna started to overwrite some graphics over the text in the WYSIWYG view. Serna then proceeded to crash at about (serna page) 70.

Level 3

I then removed Serna using the Fedora Package Manager, and then reinstalled Serna using the RPM provided on the Syntext website. I tried to open the same book again and saw the same results. This did not resolve the issue.

Resolution

I deduced that the problem only occurred after adding the Entities in bulk to the file. So I opened each file in a plain text editor (gedit) and searched for all the $FILEPATH; entities backtracked through the file and found that some of the entities were nested in &lt;literal> or other semantic XML tags.

<literal>

  $FILEPATH;

</literal>

So when Serna attempted to parse the XML combination, the Entity was expanded to:

<literal>
 &lt;filename><replaceable>VERY</replaceable>/long/<replaceable>path&</replaceable>/to/the/config-file.xml</filename>
</literal>

Serna seemed to have some difficulty rendering the WYSIWYG XSL for this element combination and therefore couldn't successfully paginate past this point. The structure is valid according to the DocBook Guide.

Summary

Ensure all files in your book contain the parameter entity for each file, and ensure entities containing XML markup as part of the entity *do not* get nested in semantic XML markup tags


[1] Parameter entities are declared in the DOCTYPE declaration of XML files to specify a local file that contains entity declarations. Refer to this page (scroll to bottom) for more info.

You have read this article Bug / Documentation / Serna / Syntext / XML with the title BUG: Serna Free and "Serna: Critical Error" fo controller error. You can bookmark this page URL http://azaquery.blogspot.com/2011/07/bug-serna-free-and-critical-error-fo.html. Thanks!