Syntext Serna Visual XML Editor

Introduction

Since the time when the XML markup language was invented , it managed to penetrate into all areas of our everyday computer life. We practically do not notice him; 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 it has become the basis for XHTML.

These three letters that changed the world can be loved or hated. But there is at least one area of ​​IT in which XML has not only revolutionized comparable in scale to the revolution, but has also become its unshakable foundation. I am talking about creating and maintaining documentation.

You heard about DocBook or fb2, right?

Attention: the article contains graphic material.

XML documentation. Why?

The storage and subsequent support of documentation in XML provides several advantages over traditional tools (for example, MS Word). Let's briefly go over them.

Open format

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

• What if there was a need for a quick (!) Study 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 available text editor. Be it advanced Emacs, or Notepad ascetic to the core.
• 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 either with its tuning, or with the search for a more perfect model of an “iron horse”. In the case of documents in XML, our hands are almost always untied for its subsequent (and multiple) extension.

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

Structured

XML was born to bring at least a bit of order to this world of chaos. The concepts of “structure” and “sequence” are some of the fundamental foundations of the format. Thanks to a set of rather strict rules for the formation of the document, the structuredness of the data represented using XML is ensured.

Separation of content from design

This is really convenient when the same document can be printed both in the style of a dull academic book and as a merry glossy magazine. When creating a document in XML, you do not have to worry about left or right indentation. Let a higher level take care of this, and the writer will take care of forming the structure of the document and filling it with contents.

Re-use features of content

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

Joint document development

The ability to assemble the final version of a document from several files (either from self-sufficient documents or simply from scattered pieces of text) allows each team member to work exclusively with his own “brick” at the moment of time, without interfering with the others: without creating collisions in the edited document .

It’s also great to be able to write a document in any language. XML supports Unicode out of the box. XML will not be a hassle for a multinational company, but rather will help 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 the document for compliance ( note: “validate” slang ) with 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 just useful to make a selection of the most interesting and important parts of the document using XPath.

And that’s all, already here and now, available to almost everyone ^* . And simply because for almost any task related to XML, you can find a tool or technology ready for use.

^* For each user versed in this topic.

---

Thanks to these qualities, the technology for creating and supporting XML documentation has found such widespread use to store our knowledge.

The most famous formats

DocBook is one of the very first widely used formats for technical documentation. With a known constancy is used in the Linux environment. Used, for example, to generate API documentation for the GTK + and GNOME libraries.

S1000D is the standard for storing technical knowledge in the field of aircraft and shipbuilding. Found application in both NATO and civilian airlines (including Russian).

fb2 ( FictionBook ) is a popular presentation format for e-books. Owners of electronic readers that support fb2, for sure, have more than once managed to assess the benefits of its use.

DITA- A whole expandable (with fantastic backward compatibility!) Architecture developed by the “Blue Giant” (IBM), covering the entire cycle of development, production and delivery of technical documentation. Easily adapted for use in various fields of activity, not just IT.

Syntext serna

With all this, it is worth noting that the documentation is not written by hackers and programmers; they just do it much less often than all. And it is written by relatively ordinary computer users who own relevant linguistic knowledge and experience. Why would 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 elements?

That is why there was a sense in the tool, hiding all the difficulties of working with XML and at the same time clearly emphasizing all its advantages. One of these editors was Syntext Serna, a visual ( WYSIWYG ) XML processor for creating and supporting XML technical documentation .

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

^* So, for example, I am quite actively using DocBook to formulate 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

Designed using the Nokia library (Trolltech) Qt. Thanks to this, it works quite successfully on the following platforms:

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

Note: hereinafter the 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 it looks like, for example, in Linux: And practically nothing can prevent it from being like this in Mac OS X:

Free and Open Source

I am more committed than just the idea that the 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, accordingly, costs a certain amount of green paper notes and is closed. The source code of the Free version is quite available on the developer's site.

The business version is practically no different from the Open version, with the exception of the presence of some goodies that are more interesting to corporate users. Details can be found on the official website.

What You See Is What You Get (WYSIWYG)

A writer who creates documentation in Serna, theoretically, does not even need to know about XML. And even more so, deal with 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 to the writer as a boring continuous footcloth of letters and phrases. Depending on the type of document being edited, each element of the text is visually formatted according to its essence. If the writer decides that the piece of text he has typed has the purpose of attracting the reader’s attention (in other words, “wrapped” in aka “bold font”), then he [text] will be highlighted in bold. And if it refers to a certain resource on the Internet (for DITA), then it will not only be displayed as a link, but will also be clickable (both from the editor itself and from a PDF generated from it).

Important: documents are displayed in the editor using on-the-fly XSLT / XSL (-FO) styles. 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 turn, preserves practically inexhaustible potential for the subsequent expansion of the editor’s functionality ^* . ^* And all this is configured in all possible directions (see. Functional expansion ).

Support for major formats

By default, Syntext Serna supports out of the box formats DocBook, DITA, XHTML, TEI P4, NITF. Important: However, the “core” does not mean at all that this is all and limited. Serna provides great tools to add support for any custom XML format.

Contextual help on the elements

The developer of the documentation is not required to fully remember the structure of the document. Then the built-in contextual help of elements comes to his aid.
Depending on the current cursor position, Serna will not only show which elements are available for insertion, but will also provide them with help information with their description (with the possibility of going to the corresponding section of the help documentation).

Validation of the document on the fly

Serna supports DTD and XML Schema. With the help of them, Serna will not only not allow you to add the wrong element and even to the wrong place, but will also report, if necessary, a violation of the structure of the document when working with it.

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

XML Entity and XInclude Support

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

HTML and PDF creation

Using external utilities (supplied with Syntext Serna, or custom ones), there is no problem to convert the edited document into PDF, HTML or literally “one-click” directly from the editor itself. This “conversion” is done using XSLT ^* . ^* Without the XSLT-style for the document, of course, nothing will come of it. For DocBook and DITA, such freely available XSLT styles are already included.

Functionality Extension

Those familiar with object-oriented design will probably be aware of the existence of such a beautiful principle as OCP (Open-Closed Principle: “open for expansion, closed for modification”). For Syntext Serna, he became one of her cornerstones.

Support for new formats

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

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

Creating Macros

Syntext Serna provides the functionality of a “context-sensitive” insert, essentially similar to the so-called “macros”: the ability to easily create buttons that insert frequently used tags and fragments of content into an edited document.

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

User interface

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

This can be useful when you want to change the ergonomics of the user interface or make commonly used functions available as buttons.

API

Perhaps this is the very tidbit of Syntext Serna, which provides the most unthinkable opportunities for expanding the functionality of the editor.

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

Using the API, Serna can be integrated with almost any content management system (CMS). Even quite complicated; e.g. c EMC Documentum. Which is actually being successfully done. Also, thanks to the library integrated in the editorPyQt , there is no apparent difficulty in developing new functional dialogs.

---

For each of the extension points of the editor’s functionality, self-sufficient documentation with examples is available. If you need more “vital” examples, you can always look into 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 possible not to note briefly also the following Syntext Serna features:

• Support directly in the document of simple input forms;
• Spell check;
• “Profiles” of documents: the same document in Serna can be displayed in different ways;
• The editor interface localized for many languages;
• Great support for tables in XML documents (using CALS Tables);
• Serna построена на использовании исключительно открытых форматов: XSLT, XSL-FO, XML Catalog, XML Schema, DTD etc.

Интересные факты

• Syntext Serna является разработкой преимущественно российских разработчиков;
• Когда-то Syntext Serna была закрытым и платным продуктом;
• Автор данного текста принимал самое непосредственное участие в жизни и разработке Syntext Serna на протяжении нескольких лет; а также проповедовал идеи Open Source в компании Syntext;
• Некоторые крупнейшие игроки российского Интернет-рынка не без видимого удовольствия используют Syntext Serna в своих рабочих окружениях;
• Syntext Serna не предназначена для редактирования конфигурационных файлов в XML, хотя вполне себе способна на это;
• Syntext Serna написана на C++ и в ее исходниках можно найти реализации многих интересных алгоритмов;
• The website of the development company was created using Syntext Serna and a plug-in for it called DITA WebKit.

Foreword

1. XML documentation is not a panacea, and Syntext Serna is not a universal (although striving for this) means of solving problems associated with the creation and support of technical documentation;

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

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

2. Syntext Serna comes with examples of ready-made documents demonstrating its capabilities. Use the appropriate 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. Feel free 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 using ready-made 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" analogues;
• At the moment, the process of building Serna from source is somewhat nontrivial; despite the presence of fairly detailed instructions;
• Distribution builds go through the company's QA.

Resources

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