Syntext Serna Visual XML Editor

Introduction

Since those distant times, the XML markup language was invented, it has managed to penetrate into all areas of our everyday computer life. We already almost do not notice; or at least diligently pretend. Here it is used to store configuration data, and here it is used for remote procedure call (XML RPC). And here he has already become the basis for XHTML.

These three letters that changed the world, you can love or hate. But there is at least one area of ​​IT, in which XML produced not only a revolution comparable in scale to the revolution, but also became its unshakable foundation. I'm talking about creating and maintaining documentation.

You heard about DocBook or fb2, didn't you?
')
Attention: the article contains graphic material.

XML documentation. Why?

Storage and subsequent support of documentation in XML provides a number of advantages in comparison with traditional means (for example, MS Word). Let's take a quick look at them.

Open format

Any XML-based data format is one way or another open. Open in several ways.

• What if there was a need for a quick (!) Examination of the contents of an XML document? This is not a binary blob from Microsoft. Therefore, there is nothing easier than opening your document in the first text editor. Whether it is advanced Emacs, or Notepad ascetic to the depths of the soul.
• What about a little magic? Using existing tools you can always convert a document to XML in any other format. Say in PDF or other XML.
  
• Sometimes what already exists is not enough. If we were dealing with a car and we were no longer satisfied with its cargo qualities, we would have to deal with either tuning it or searching for a more advanced “iron horse” model. In the case of documents in XML, we almost always have a free hand for its subsequent (and repeated) extension.

The absence of restrictions on the XML dictionary allows you to create specific specialized XML-languages, and the syntax commonality - to process arbitrary data represented in XML, by the same programs.

Structuredness

XML was born to bring at least a little order to this world of chaos. The concepts of “structure” and “sequence” are among the fundamental foundations of the format. Thanks to a set of sufficiently strict rules for the formation of a document, the structured data presented using XML is ensured.

Separation of content from design

This is truly convenient when the same document can be printed both in the style of a dull academic book, and as a cheerful, glossy magazine. When creating a document in XML, you do not need to worry about left or right indents. Let the level above take care of this, and the writer take care of shaping the structure of the document and filling it with content.

Content reuse (re-use) options

If we compare XML with building blocks, the technologies associated with it can be safely called cement mortar. The cement here is XInclude or even the standard entity mechanism ( Entities ; both external and internal). For example, thanks to them, a document can be formed from a crazy number of other documents or their individual parts. A change in one of the constituent units will immediately be reflected in the final document. And no more copy & paste! Truly divide and conquer.

Joint development of the document

The ability to collect the final version of a document from several files (whether from self-contained documents or simply from separate pieces of text) allows each team member to work exclusively with his “brick” at a time without interfering with the other: without creating conflicts in an editable document .

It’s also great to have the opportunity to write a document in any language. XML supports Unicode out of the box. XML does not take the trouble of a multinational company, but rather helps solve them.

And in addition to this, XML documents are very well stored in version control systems.

Many ready-made tools and technologies

You can check a document for compliance ( note: slang “validate” ) to a given structure using DTD / XML Schema / RelaxNG. And if you want, then convert the document to XML with a different structure using XSLT. And in the end, sometimes it is simply useful to make a selection of the most interesting and important parts of the document using XPath.

And this is all, already here and now, accessible to almost everyone ^* . And simply because for almost any XML-related task, you can find a tool or technology already ready for use.

^* For each knowledgeable user.

---

Thanks to these qualities, the technology of creating and maintaining documentation in XML format has found such wide distribution for the storage of our knowledge.

The most famous formats

DocBook is one of the very first widely distributed formats for technical documentation. It is used with consistency in the Linux environment. Used, for example, to generate API documentation for GTK + and GNOME libraries.

S1000D - the standard for storing technical knowledge in the field of aircraft and shipbuilding. It has been used both in NATO and in civil airlines (including Russian airlines).

fb2 ( FictionBook ) is a popular format for presenting electronic books. Owners of electronic readers that support fb2, for sure, have already managed to appreciate the benefits of using it.

DITA is a whole extensible (with fantastic backward compatibility!) Architecture developed by the “Blue Giant” (IBM), covering the entire cycle of development, release and delivery of technical documentation. It is easily adapted for use in various fields of activity, and not just IT.

Syntext serna

With all this it is worth noting that the documentation is written not by hackers and programmers; they do it much less often than anyone else. And it is written by relatively ordinary computer users who possess the appropriate linguistic knowledge and experience. Why should they, in order to write a couple of sentences of the text, create some tags, check their correctness, and also constantly monitor the correct nesting of the elements?

That is why there was a sense in the tool that hides all the difficulties of working with XML and clearly emphasizes all its advantages. One of these editors was Syntext Serna - a visual ( WYSIWYG ) XML processor for creating and maintaining technical documentation in XML format .

Despite the decent prevalence of Syntext Serna in the neighboring hemisphere, little has been heard about this XML editor in Russia. For me, Serna was not only a discovery, but also a truly favorite editor ^* ; On top of that, I consider Syntext Serna to be an ingenious software product. And that's why.

^* So, for example, I actively use DocBook for the formation of technical tasks for software. And creating them in Serna is much more efficient, despite using my favorite Emacs for everything else.

General characteristics

Cross Platform

Developed using the Nokia Qt Library (Trolltech). Due to this, it works quite successfully on the following platforms:

• Windows;
• GNU / Linux;
• Mac OS X;
• and even Solaris / SPARC.

Note: hereinafter, graphic material is taken from the developer’s site; I guarantee that at the time of writing this material, it is fully true.

This is what Linux looks like:


And practically nothing can prevent it from being such in Mac OS X:

Free and Open Source

I am more of a supporter than just a supporter of the idea that software should be Free. Not without pleasure, I note that the developers of the editor have a similar opinion.

Syntext Serna exists in two editions: Open Source ( Serna Free ) and Enterprise ( Serna Enterprise ). Serna Free is available and distributed under the GNU GPL v3 license . Serna Enterprise, respectively, is worth some green paper bills and is closed. The source code of the Free version is quite accessible to the developer’s site.

The business version is practically the same as the Open version, except for the presence of some goodies, which are more interesting to corporate users. Details can be found on the official website.

What you see is what you get (wysiwyg)

Theoretically, the writer creating the documentation in Serna doesn't even need to know about XML. And even more so to engage in a set of tags manually. It is enough for him to simply understand that the document has a fixed structure consisting of elements. An element has not only a name, but also semantics.

Moreover, the created text is not displayed for the writer by a boring solid sheet of letters and phrases. Depending on the type of document being edited, each text element is visually formatted according to its essence. If the writer decides that the text he has typed has an appointment to attract the reader’s attention (simply, “wrapped” in the <b /> aka “bold font” element), then he [text] will be highlighted in bold color. And if he refers to a certain resource on the Internet (<a/> for DITA), then it will not only appear as a link, but it will also be clickable (both from the editor itself and from the PDF generated from it).



Important: the display of documents is performed in the editor using the XSLT / XSL (-FO) styles on the fly. Accordingly, having written once an XSLT / XSL (-FO) -style, it can be used both for display in the editor itself, and for generating from it, for example, PDF. And this in its very store almost inexhaustible potential for the subsequent expansion of the functionality of the editor ^* .

^* And this is all customizable in all possible directions (see. Extending functionality ).

Main formats support

By default, Syntext Serna supports out-of-box DocBook, DITA, XHTML, TEI P4, NITF formats.







Important: However, the "main" does not mean at all that this is all that is limited. Serna provides excellent tools to add support for any custom XML format.

Contextual help on elements

The documentation developer is not required to remember the full structure of the document. Here the built-in contextual help to elements comes to his aid.
Depending on the current cursor position, Serna will not only show which elements are available for insertion, but also provide reference information on them with a description of them (with the ability to go to the appropriate section of reference documentation).

Validation of the document “on the fly”

Serna supports DTD and XML Schema. Using them, Serna will not only not allow adding the wrong element, but also in the wrong place, but also, if necessary, will report a violation of the document structure when working with it.

Thanks to the support of XML Schema, Syntext Serna at any time “knows” which element is available for insertion into the current cursor position.

XML Entity and XInclude support

Remember the above about content reuse? This is it. It is enough to create a section of text that is supposed to be used in several places once and insert it into the places required in the document. A little later, by changing the contents of this insert, it will instantly be updated throughout the document!

HTML and PDF creation

Using external utilities (supplied with Syntext Serna, or custom), there is no problem to convert the edited document to PDF, HTML or something else literally “in one click” directly from the editor itself. This “conversion” is performed using XSLT ^* .





^* Without the presence of XSLT-style for the document, of course, nothing will come of it. For DocBook and DITA, these free XSLT styles are already included.

Expansion of functionality

Those familiar with object-oriented design are most likely aware of the existence of such a wonderful principle as OCP (Open-Closed Principle: “open for expansion, closed for modification”). For Syntext Serna, he became one of its cornerstones.

Support for new formats

There is nothing easier than adding support for a new (or modifying existing) XML format in Serna. To do this, simply create a profile of the new format, specifying:

• (optional-desirable) XML Schema format for which the document will be validated. Without this, for example, context help does not take off in the editor;
• (Required) XSLT / XSL (-FO) -style for display. Without it, the user will not only be able to view the document, but also edit it;
• (optional) Various options that change the behavior of pleasant to use editor editor.

Creating “macros”

Syntext Serna provides the functionality of a “context-sensitive” insert, which is close in essence to the so-called “macros”: the ability to simply create buttons that insert frequently used tags and content fragments into an editable document.

For example, using this extension point, you can implement a “standard” text selection panel ( bold , italic , underline ) in XML documents; what is actually done for the DITA and DocBook formats (you can always see how it is implemented in the editor itself and add the same for your document format).

User interface

The user interface of the editor is built from bricks. Bricks are configuration files that describe in a declarative language, from which widgets, in what order and with what properties the Syntext Serna interface will be formed. For each type of document may be its own set of widgets.

This is useful when you want to change the user interface ergonomics or make frequently used functions available in the form of buttons.

API

Perhaps this is the tidbit Syntext Serna, providing the most unimaginable possibilities for expanding the functionality of the editor.

Syntext Serna provides API for C ++ and Python languages . These extension interfaces cover approximately 95% of the functionality of the XML editor in question. If we draw a line of comparison, then the capabilities of the Serna API can even be tried to compare equally equally with the API of the Emacs operating system .

Using the API, you can integrate Serna with virtually any content management system (CMS). Even quite complicated; for example, with EMC Documentum. What actually is successfully done. Also, thanks to the PyQt library integrated into the editor, there are no visible difficulties in developing new functional dialogues.

---

Self-sufficient documentation with examples is available for each of the extension points of the editor's functionality. If you need more “vital” examples, you can always look at the sources of Syntext Serna - it consists of more than 80% of these bricks.

Other features in one line

You can talk about Serna for a long time. More information can be found on the developer’s website. However, it is not possible not to mention briefly the following features of Syntext Serna:

• Support directly in the document simple input forms;
• Spell checker;
• “Profiles” of documents: the same document in Serna may be displayed differently;
• Localized editor interface for many languages;
• Excellent support for tables in XML documents (using CALS Tables);
• Serna is built on the use of exclusively open formats: XSLT, XSL-FO, XML Catalog, XML Schema, DTD etc.

Interesting Facts

• Syntext Serna is a development of mainly Russian developers;
• Once Syntext Serna was a closed and paid product;
• The author of this text was directly involved in the life and development of Syntext Serna for several years; and also preached the ideas of Open Source at Syntext;
• Some of the largest players in the Russian Internet market, not without apparent pleasure, use Syntext Serna in their work environments;
• Syntext Serna is not designed to edit configuration files in XML, although it is quite capable of it;
• Syntext Serna is written in C ++ and in its source you can find implementations of many interesting algorithms;
• The website of the developer company was created using Syntext Serna and a plugin for it called DITA WebKit.

Foreword

1. Documentation in XML is not a panacea, and Syntext Serna is not a universal (although it seeks to do so) means of solving problems associated with the creation and maintenance of technical documentation;

In any case, just try XML together with Syntext Serna and make your choice.
And be sure to try out the alternatives:

• oXygen XML Editor, www.oxygenxml.com (Windows);
• XML Mind, www.xmlmind.com/xmleditor (Java).

2. Syntext Serna comes with examples of finished documents demonstrating its capabilities. Use the corresponding item in the Help menu to view them.

3. And if you take some free content management system like Alfresco and make friends with Syntext Serna, you can get a good solution for electronic document management.

4. Do not hesitate to inform the developers about the bugs found. It is very likely that they will even answer you in Russian.

5. (Linux users) . Despite the availability of source codes, I recommend to use ready assemblies for an initial acquaintance with the editor. The prerequisites for this are as follows:

• Experience shows that “branded” assemblies are sometimes more stable than their “self-assembled” analogs;
• At the moment, the Serna build process from source is somewhat non-trivial; despite the presence of quite detailed instructions;
• Distributive builds go through the QA of the developer.

Resources

1. Syntext Serna Free Official Information, http://www.syntext.com/products/serna-free/ ;
2. Syntext Serna Free download section, http://www.syntext.com/downloads/serna-free/ ;
3. Tutorial on working with Syntext Serna, http://downloads.syntext.com/serna-docs/serna-tutorial.pdf .