DocmaServer

What is it

Docma is a Python application developed by Infrae for the processing and generation of Silva XML. Note that Docma is not a Zope product; it is an independent application that can be accessed remotely by Silva using XML-RPC.

Docma is able to convert Silva XML documents to Word documents and vice versa.

Target platform

The target conversion application is Word 2000. Other versions may have different output or may not work at all.

Silva Integration

If Docma is running and Silva is configured properly you have additional options on both export and import. You'll find more information in the Silva Documentation.

Silva markup and Word styles

The best way to get started is to export a fairly complex publication out of Silva to see how everything works. The resulting Word document has a detailed structure of styles. These styles map to Silva elements. Some paragraphs have a comment attached, holding additional information for Docma, such as document ids. Additionally you will find information about the exported document in the File/Properties menu. These are the three instruments for preparing a Word document for converting to Silva with all the markup: Silva Word styles, comments and the information in the File/Properties dialog.

To get an existing Word document converted into Silva XML it is necessary to use Silva Word styles. For all Silva Word styles see the all styles document in the package. There is also a Word template (.dot) available containing all styles.

Without using any Silva Word styles you can expect the following results from a conversion:

Bulleted lists become a “disc bullet” list in Silva.
Lists of any numbering become a “1, 2, 3...” list in Silva.
Other text becomes a Silva paragraph.
All tables will get the “grid” style.
One folder containing one, potentially large, document will be created.

Style Names

Docma uses some styles that are built into Word. Thus their names are language dependent. For instance the English style names “Heading 1 to “Heading 9' are called “Kop 1” to “Kop 9” in Dutch or “Überschrift 1” to “Überschrift 9” in German.

Folders and Documents

The overall publication structure is created by heading styles, namely “Heading 1” to “Heading 9”.

Basically everytime text with a heading style is encountered a new folder is created. But if this would lead to a folder containing only one document a Silva document is created instead.

Paragraphs

Paragraphs are created out of any Word paragraph of style Body Text.

Preformatted

Preformatted paragraphs are created out of any Word paragraph of style Plain Text. Adjacent paragraphs are joined to one preformatted element.

Lists

Docma uses different styles for every list type or level. This means two bulleted list items on different levels (a nested list) result in two different styles being used.

To add an additional paragraph to the same list item the paragraph has to be indented the same amount as the list item.

To be more exact, Docma needs lists to match the following rules:

Every list entry has to start with a paragraph with a list style of any kind or level.
If the paragraph contains text, a paragraph will be created by Docma. If the paragraph does not contain text, no paragraph will be created.
All elements belonging to a particular list entry in a list of level n must be left aligned between the left alignment of the List style of level n and List style of level n+1.

Definition Lists

An entry in a definition list always consists of a definition term, indicated by Definition Term style and a definition description, indicated by the Definition Description style. If no corresponding Term or Description is found the element will be empty. There is currently no way of creating a ‘compact’ definition list.

Tables

Silva tables must contain the same amount of cells in every row. Row headings become a single cell with style Row Heading if converting Silva to Word.

If converting Word to Silva the following rules apply per table:

‘max_cells’ is the maximum amount of cells per row.
If the current row consists of only one cell and max_cells is greater than one, the cell is considered a row heading.
If the current cell's first paragraph has the style Row Heading and max_cells is one, the cell is considered a row heading.
If a cell is considered a row heading, only the first paragraph is conveted, other paragraphs are dropped.
If a cell is not considered a row heading, all paragraphs are converted.
If there are less than max_cells in a row emtpy cells will be created at the end until there are exactly max_cells in the row.

Stand alone Silva2Word

From Docma 0.2.1 on it is possible to have Silva2Word running stand alone. To set this up you associate .slv files (Silva XML exports) with C:\Python22\Python.exe c:\the_path_to_docma\silva2word.py. You then can double click on .slv files to get them converted. Word just stays open while you select the next file.

Meta:

    Valid for:  Docma CVS 
    Author:     Christian Zagrodnick 
    Email:      cz@gocept.com 
    CVS:        $Id: README.txt,v 1.13 2003/03/27 09:56:13 zagy Exp $