Serna User's FAQ


Serna User's FAQ

1. General Questions
Q: Can I edit an arbitrary XML file in Serna?
Q: Why Serna couldn't just use CSS for rendering?
Q: I open my perfectly valid XML file, but Serna gives errors and goes to expert mode.
Q: What is a Document Template?
Q: I created a custom content button with a hot-key in one document, but the button does not appear in another document!
Q: I have done something to Serna, so some errors occur (or the interface is weird) and even reinstallation does not help.
Q: What is the difference between the Free edition and Trial version of Serna?
Q: I have installed Serna and run it, but do not see "DITA usability tools"!
2. Editing Documents
Q: How can I select elements in Serna easily?
Q: How can I easily delete a list item with text?
Q: What hot-keys may make my editing fast and handy?
Q: How can I insert a graphic or table into my XML document?
Q: I inserted an element, and I can see that Serna set some attributes there. Where do they come from?
3. Opening and Creating New Documents
Q: How do I make Serna guess what stylesheet and schema to use for my document?
Q: How do I make a “Project”in Serna that associates stylesheet, schema, etc with my documents?
Q: I do not want to create a Document Template for my document, but still do not want to use Browse... buttons when opening documents, what do I do?
4. Document Validation, DTDs and Schemas
Q: Serna does not recognize DTD SYSID in my XML document.
Q: I open an XML file with my DTD, but Serna does not really validate my document.
Q: I have a DTD but no Schema for my documents. How do I make Serna validate my documents?
Q: I corrected my Schema, but the Revalidate button does not bring up changes.
5. Publishing in HTML, PDF and other Formats
Q: How can I enable PDF or HTML publishing from Serna?
Q: Why doesn't Publish work for my documentation or examples?
Q: When I try to Publish my document, Serna complains about a missing saxon.bat, xep.bat, or fop.bat.
Q: Why does Serna create a temporary file for publishing?
6. Editing Docbook
Q: Why are there “Draft area for "ELEMENT" metainfo” gray areas? How do I get rid of them?
Q: I want other fonts (and look-and-feel features) in Docbook. How do I change it?
Q: I click on ContentMap titles, but Serna scrolls to the TOC in the document. How do I get to the actual element location in the document?
7. ContentMap Pane
Q: Why doesn't ContentMap show the exact structure of my XML file?
Q: When I click on an element in ContentMap, Serna navigates to the first appearance of the element in document. How do I get to the others?
Q: Can I tailor ContentMap for my needs?
8. Spell-checking
Q: Does Serna support any other word-lists besides English?
Q: How do I add another language word-list?
Q: I added a wrong word to dictionary unintentionally. How do I remove this word from my dictionary?
9. XSL Support
Q: Will Serna work with arbitrary XSL stylesheets?
Q: I read that Serna may use some XSL extensions. Doesn't this actually make Serna XSL stylesheets proprietary?
Q: I use my XSL stylesheet, but the cursor behaviour is weird: I cannot insert text, etc.
Q: I use my XSL stylesheet and Serna seems to be working slowly.
10. Windows™ Platform Issues
Q: Serna won't start on my Windows NT 4.0 box.
Q: Open Dialog, Save As Dialog, etc do not show computers in my workgroup.
11. Mac OS X Platform Issues
Q: The fonts as rendered are ugly. The document is not always redrawn.
12. Linux Platform Issues
Q: I start Serna, but its first dialog is crippled or shows broken symbols.
Q: I try to execute serna.bin, but Serna doesn't start. What's wrong?
Q: I get errors when installing Serna from RPM: what's up?
Q: I can't install Serna RPM on Fedora Core 4. It requires additional libraries.

Note

If you do not find an answer to your question, please e-mail it to support @ syntext.com

1. General Questions

Q: Can I edit an arbitrary XML file in Serna?
Q: Why Serna couldn't just use CSS for rendering?
Q: I open my perfectly valid XML file, but Serna gives errors and goes to expert mode.
Q: What is a Document Template?
Q: I created a custom content button with a hot-key in one document, but the button does not appear in another document!
Q: I have done something to Serna, so some errors occur (or the interface is weird) and even reinstallation does not help.
Q: What is the difference between the Free edition and Trial version of Serna?
Q: I have installed Serna and run it, but do not see "DITA usability tools"!

Q:

Can I edit an arbitrary XML file in Serna?

A:

Yes. Simply open it with Open Dialog. Serna will use the simple default XSL template (note -Default Template- inscription in Open As combo).

Q:

Why Serna couldn't just use CSS for rendering?

A:

CSS does not provide the full benefits of true WYSIWYG power. For example, CSS does not allow you to see an automatic TOC in your document, proper numbering of sections and lists, localization for inscriptions, or any other structural transformations of the document, which are numerous in a complex stylesheets like Docbook.

Q:

I open my perfectly valid XML file, but Serna gives errors and goes to expert mode.

A:

Usually this happens because Serna cannot locate the DTD file mentioned in DOCTYPE PUBID or SYSID of your XML file. To make Serna find it, either add an XML catalog with the PUBID/SYSID mapping to ToolsPreferences+XML Catalogs or correctly set the SYSID to the absolute location.

In general, Serna opens a document in expert mode when it cannot parse the source document correctly.

Q:

What is a Document Template?

A:

Document Templates provide a convenient way to associate all necessary XML metadata with the document in order to open the document or create new documents of this type.

If you have a document template for your document, you can open it in Serna with a single click. If you do not have a document template, you will need to specify paths to the XSL stylesheet, XML schema, etc. manually.

Q:

I created a custom content button with a hot-key in one document, but the button does not appear in another document!

A:

Serna creates a separate GUI layout for every open document. Hence, if you make changes in a layout (including creating buttons or changing hot-keys), the changes do not automatically propagate to other documents.

To make the changes persistent, go to ViewSave View... and save the GUI layout for all documents of this type (either for a particular template or for documents without a template).

Q:

I have done something to Serna, so some errors occur (or the interface is weird) and even reinstallation does not help.

A:

Your personal settings for Serna are stored at C:\Documents and Settings\LOGIN\.serna-X.Y (for Windows) or at $HOME/.serna-X.Y (for Linux/Mac OS X), where X.Y is the current version of Serna. Rename or remove the directory and run Serna again. Note that all your preferences and GUI settings will be lost if you remove the directory.

Q:

What is the difference between the Free edition and Trial version of Serna?

A:

The trial version works as Serna Enterprise with all the functionality enabled for one month. Serna Free and unregistered version do not have enterprise (corporate) features like WebDAV and SSL support, redlining, etc. See details at http://www.syntext.com/products/serna/feature-matrix.htm.

A trial enterprise license can be requested at: http://cms.syntext.com/index/trial/input. Serna Free can be downloaded at: http://syntext.com/downloads/index.htm. A free license for Serna Free can be requested at: http://cms.syntext.com/index/free/input

Q:

I have installed Serna and run it, but do not see "DITA usability tools"!

A:

"DITA usability tools" (DITA menu and dialogs) are available in Serna Enterprise and the trial version of Serna Enterprise only. To enable DITA usability tools, run Serna and provide it with your trial license or purchased enterprise license.

2. Editing Documents

Q: How can I select elements in Serna easily?
Q: How can I easily delete a list item with text?
Q: What hot-keys may make my editing fast and handy?
Q: How can I insert a graphic or table into my XML document?
Q: I inserted an element, and I can see that Serna set some attributes there. Where do they come from?

Q:

How can I select elements in Serna easily?

A:

There are two handy ways to select elements:

  • Select/Deselect Parent command. Place the cursor inside the element you want to select, and apply Ctrl+Alt+UpArrow or Ctrl+Alt+DownArrow.

  • Balance Selection mode. If this mode is active (see EditBalance Selection) the selection is automatically adjusted to the element borders. If this mode is inactive the selection starts and ends exactly at the mouse position and splits elements as necessary. (Note that Balance selection mode always creates a well-formed content in the clipboard.)

Q:

How can I easily delete a list item with text?

A:

Put the cursor in the text of the item and press Ctrl+Alt+UpArrow once (for DITA) or twice (for Docbook) to select the item. Press the Delete key.

Q:

What hot-keys may make my editing fast and handy?

A:

There are a few, but they make editing extremely fast. (See also Quick Reference Card).

  • Insert Element. Ctrl+Enter

  • Split Element. Enter

  • Split Parents. Hit Enter immediately after Enter. This will split the current element parent. Convenient for editing lists.

  • Delete Element. Del if cursor position is before the element, Backspace if cursor position is after the element, or Ctrl+Del if cursor is within the document.

  • Element Attributes. Apply Alt+Enter within your element.

  • Tag Region/Untag Element. Use Ctrl-T and Ctrl-U to wrap a selected region into the element or unwrap it. The Insert Element command in presence of selection also works as Tag Region.

  • Navigation hot keys. Next/Previous Element: Ctrl+Arrow Up/Ctrl+Arrow Down. Start/End Element: Ctrl+Home/Ctrl+End.

  • Selection commands. Selection commands make it easier to manipulate portions of documents (Select/Deselect Parent, Balance Selection mode). See answer to the previous question.

Q:

How can I insert a graphic or table into my XML document?

A:

Graphics or tables are produced with XSL templates applied for specific elements. If your stylesheet contains such templates, insertion of those elements will produce graphic or table rendering. For instance, Docbook stylesheet support <graphic> and table-related elements.

Q:

I inserted an element, and I can see that Serna set some attributes there. Where do they come from?

A:

You are editing a document with a Schema that prescribes default values for attributes. These values will not be saved unless overridden, and shown only for authoring convenience and correct stylesheet processing.

3. Opening and Creating New Documents

Q: How do I make Serna guess what stylesheet and schema to use for my document?
Q: How do I make a “Project”in Serna that associates stylesheet, schema, etc with my documents?
Q: I do not want to create a Document Template for my document, but still do not want to use Browse... buttons when opening documents, what do I do?

Q:

How do I make Serna guess what stylesheet and schema to use for my document?

A:

You have two options:

  • Create a document template (see Developer's Guide, Document Template Development). This will help Serna automatically guess your document type and prescribe an appropriate stylesheet and Schema for opening or creating the document.

  • Alternatively, you can add special <?syntext-serna > PIs in the beginning of your document that prescribe what stylesheet, schema, etc, Serna is to use with the document (see Developer's Guide, Using Serna PIs for Associating Document Meta-data).

Q:

How do I make a Projectin Serna that associates stylesheet, schema, etc with my documents?

A:

We considered the Projectapproach too cumbersome. Instead Serna can guess (or deduce) what stylesheet and schema to use for your documents, from the Document Templates or special PIs. See answer to previous question.

Q:

I do not want to create a Document Template for my document, but still do not want to use Browse... buttons when opening documents, what do I do?

A:

Add special <?syntext-serna > PIs to the beginning of your document. See Developer's Guide, Using Serna PIs for Associating Document Meta-data.

4. Document Validation, DTDs and Schemas

Q: Serna does not recognize DTD SYSID in my XML document.
Q: I open an XML file with my DTD, but Serna does not really validate my document.
Q: I have a DTD but no Schema for my documents. How do I make Serna validate my documents?
Q: I corrected my Schema, but the Revalidate button does not bring up changes.

Q:

Serna does not recognize DTD SYSID in my XML document.

A:

To make Serna find your DTD, either add proper XML Catalog: ToolsPreferences+XML Catalogs, or correctly set the SYSID to the absolute location.

Q:

I open an XML file with my DTD, but Serna does not really validate my document.

A:

Serna uses DTD for parsing the document, but validates only against a Schema. You can easily get a Schema for your DTD with the Syntext DTD2XStool.

Q:

I have a DTD but no Schema for my documents. How do I make Serna validate my documents?

A:

Covert your XML DTD to a Schema. It's a snap with Syntext DTD2XS.

Q:

I corrected my Schema, but the Revalidate button does not bring up changes.

A:

Serna caches Schemas and stylesheets. When you push Revalidate, Serna does not re-read the Schema. To re-read the Schema, click ToolsReload Document. Note that Serna will only reload the Schema if it was changed.

5. Publishing in HTML, PDF and other Formats

Q: How can I enable PDF or HTML publishing from Serna?
Q: Why doesn't Publish work for my documentation or examples?
Q: When I try to Publish my document, Serna complains about a missing saxon.bat, xep.bat, or fop.bat.
Q: Why does Serna create a temporary file for publishing?

Q:

How can I enable PDF or HTML publishing from Serna?

A:

Serna has a hook that allows it to call external applications for converting your XML document to other format (DocumentPublish). To learn how to specify the script for your publishing, refer to Developer's Guide, Publishing.

Q:

Why doesn't Publish work for my documentation or examples?

A:

This probably happens because you don't have write permissions to the document location directory. Serna creates a temporary file for publishing.

Q:

When I try to Publish my document, Serna complains about a missing saxon.bat, xep.bat, or fop.bat.

A:

For better publishing, Serna provides the hooks to popular publishing applications that generate PDF or HTML, but it does not include them. To generate PDF you have to obtain either the XEP or FOP xsl formatter, and to generate HTML you should install an XSLT engine (e.g. Saxon). For an example saxon.bat/saxon.sh, refer to the Document Template Development section in Developer's Guide.

Q:

Why does Serna create a temporary file for publishing?

A:

This is a simple solution to overcome the DTD resolution problem. The publishing application needs to locate the document DTD, but may not be able to resolve the DTD SYSID. Serna creates a temporary file that has all the entities expanded and default attribute values instantiated. That is why this temporary file does not refer to the DTD and an external application does not face the SYSID problem.

6. Editing Docbook

Q: Why are there “Draft area for "ELEMENT" metainfo” gray areas? How do I get rid of them?
Q: I want other fonts (and look-and-feel features) in Docbook. How do I change it?
Q: I click on ContentMap titles, but Serna scrolls to the TOC in the document. How do I get to the actual element location in the document?

Q:

Why are there Draft area for "ELEMENT" metainfo gray areas? How do I get rid of them?

A:

These draft areas are necessary because Docbook stylesheet rules are intricate. For instance, title in section can be specified within <section> itself and within <sectioninfo>. If you specify both, one of them becomes hidden. To avoid this, all such meta-information is shown also in Draft Areas. They can be turned off by changing the value of the show-preamble-editing parameter to 0 in parameters.xsl file in Docbook stylesheet.

Q:

I want other fonts (and look-and-feel features) in Docbook. How do I change it?

A:

See the parameters.xsl file in the Docbook stylesheet. The parameters work a lot like those in original Norman Walsh Docbook stylesheet.

Q:

I click on ContentMap titles, but Serna scrolls to the TOC in the document. How do I get to the actual element location in the document?

A:

Keep clicking on the ContentMap element. This navigates you through all the appearances of the element in the document.

7. ContentMap Pane

Q: Why doesn't ContentMap show the exact structure of my XML file?
Q: When I click on an element in ContentMap, Serna navigates to the first appearance of the element in document. How do I get to the others?
Q: Can I tailor ContentMap for my needs?

Q:

Why doesn't ContentMap show the exact structure of my XML file?

A:

ContentMap pane serves first of all as a fast navigation tool and it is closer to a book Table of Contents where you usually see only the titles. ContentMap pane shows a document according to a ContentMap stylesheet that you can customize for your needs. See Developer's Guide, ContentMap Stylesheet Development.

Q:

When I click on an element in ContentMap, Serna navigates to the first appearance of the element in document. How do I get to the others?

A:

Keep clicking on the ContentMap element. The clicks navigate through all the appearances of the element in the document.

Q:

Can I tailor ContentMap for my needs?

A:

Yes. ContentMap is rendered according to a special ContentMap Stylesheet. See Developer's Guide, ContentMap Stylesheet Development.

8. Spell-checking

Q: Does Serna support any other word-lists besides English?
Q: How do I add another language word-list?
Q: I added a wrong word to dictionary unintentionally. How do I remove this word from my dictionary?

Q:

Does Serna support any other word-lists besides English?

A:

Yes. It supports the Aspell word-lists. Add your Aspell word list to your Serna installation.

Q:

How do I add another language word-list?

A:

Take an Aspell word-list from the Aspell ftp server, compile and install it (see User's Guide, Adding Dictionaries).

Q:

I added a wrong word to dictionary unintentionally. How do I remove this word from my dictionary?

A:

Your dictionary is located in file ~/.serna2/serna.LANG.pws under Linux, and C:\Documents and Settings\yourLoginName\.serna2\serna.LANG.pws. Close Serna and simply remove the occurrence of this word from the dictionary file.

9. XSL Support

Q: Will Serna work with arbitrary XSL stylesheets?
Q: I read that Serna may use some XSL extensions. Doesn't this actually make Serna XSL stylesheets proprietary?
Q: I use my XSL stylesheet, but the cursor behaviour is weird: I cannot insert text, etc.
Q: I use my XSL stylesheet and Serna seems to be working slowly.

Q:

Will Serna work with arbitrary XSL stylesheets?

A:

Serna supports a particular subset of XSLT/XSL-FO. This subset is constantly growing from version to version. Also, there are certain special rules for developing editing stylesheets (see Developer's Guide), so arbitrary XSL stylesheets probably will need some adjustment.

The opposite is usually true: you can use Serna XSL stylesheets with any other mature XSL-FO renderer.

Q:

I read that Serna may use some XSL extensions. Doesn't this actually make Serna XSL stylesheets proprietary?

A:

No. There are some extensions that enhance WYSIWYG document representation or performance. The extensions have no effect (and are not needed) for other XSL engines. Correctly designed Serna XSL stylesheets retain full out-of-the-box compatibility with other XSL engines.

Q:

I use my XSL stylesheet, but the cursor behaviour is weird: I cannot insert text, etc.

A:

There are some tips that make Serna recognize the element the XSL representation is mapped to, and they should be followed. Read Developer's Guide, XSL Stylesheet Development before you start implementing your stylesheets.

Q:

I use my XSL stylesheet and Serna seems to be working slowly.

A:

Serna uses dynamic XSLT implementation, therefore memory and CPU consumption aspects of stylesheet processing become important and may severely affect interactive response-time. Read Developer's Guide, XSLT Efficiency Guidelines for tips and tricks. Design your stylesheets carefully. With properly designed stylesheets, Serna is very fast.

10. Windows™ Platform Issues

Q: Serna won't start on my Windows NT 4.0 box.
Q: Open Dialog, Save As Dialog, etc do not show computers in my workgroup.

Q:

Serna won't start on my Windows NT 4.0 box.

A:

We do not ship for this platform currently. Let us know if you have a business need for a Windows NT 4.0 version of Serna.

Q:

Open Dialog, Save As Dialog, etc do not show computers in my workgroup.

A:

This is an unfortunate limitation of the current Qt version. To see your workgroup computers, type the path manually in Look in text box of the dialogs, e.g: \\FileServer1\myfiles

11. Mac OS X Platform Issues

Q: The fonts as rendered are ugly. The document is not always redrawn.

Q:

The fonts as rendered are ugly. The document is not always redrawn.

A:

Unfortunately this is due to a bug in the third party graphical library (Trolltech QT), and we cannot fix it in-house. These problems are expected to be fixed in QT version 4. Migration to this version is expected by the end of 2007. The alpha version of Serna 4 is already available for Premium Support customers.

12. Linux Platform Issues

Q: I start Serna, but its first dialog is crippled or shows broken symbols.
Q: I try to execute serna.bin, but Serna doesn't start. What's wrong?
Q: I get errors when installing Serna from RPM: what's up?
Q: I can't install Serna RPM on Fedora Core 4. It requires additional libraries.

Q:

I start Serna, but its first dialog is crippled or shows broken symbols.

A:

This usually happens if you have never run a QT application before, or if fonts for QT applications are mis-configured and Serna cannot find a system font.

To easily overcome this problem, specify system font explicitly when starting Serna, e.g:

serna2 -fn -sony-fixed-medium-r-normal--0-0-100-100-c-0-iso8859-1

To get the list of available X11 fonts, run either xfontsel or xlsfonts.

To configure the QT system font, use qtconfig application.

Q:

I try to execute serna.bin, but Serna doesn't start. What's wrong?

A:

To start Serna type serna2, but not serna.bin. The serna2 start script is usually located in /usr/local/bin.

Q:

I get errors when installing Serna from RPM: what's up?

A:

This is probably because you use 4.1.X RPM version (coming with RedHat 8.0). If so, uninstall the RPM, then set the RPM_INSTALL_PREFIX_VARIABLE:

export RPM_INSTALL_PREFIX=/usr/local # for bash

or:

setenv RPM_INSTALL_PREFIX /usr/local # for tcsh

And then try to run install RPM again.

Q:

I can't install Serna RPM on Fedora Core 4. It requires additional libraries.

A:

You need the install the following RPMs: compat-libstdc++-33-3.2.3-47.fc4.i386.rpm, compat-readline43-4.3-2.i386.rpm.