README.txt

Meta:

  Valid for:  Docma 0.2.2 
  Author:     Christian Zagrodnick 
  Email:      [email protected] 
  CVS:        $Id: README.txt,v 1.13.2.1 2003/03/27 11:17:18 zagy Exp $

What is this about

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 access remotely by Silva using XML-RPC.

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

Target platform

Target platform 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 find more information in the Silva Documentation.

Markup

To get a Word document converted into Silva XML it is necessary to use Silva Word styles. For all Silva Word styles see the all styles document. There is also a template available containing all styles.

The best way to get started is to export a fairly complex publication out of Silva to see how everything works. You will see the document has a rather detailed structure of styles. Some paragraph have a comment attached, giving additional information to Docma, like document IDs. Finally 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 menu.

Without using any Silva word-styles you can expect the following result:

Lists of any numbering become a “1, 2, 3...” list in Silva.
Bulleted lists become a “disc bullet” list in Silva.
Other text become 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 structure is created by heading styles, namely “Heading 1” to “Heading 9” .

Basicly everytime a paragraph with heading style is encountered a new folder is created. But if this would lead to a folder containing only one document a 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. Meaning for two bulleted list items on differend levels (a nested list) two different styles are 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 w2s. If the paragraph does not contain text, no paragraph will be created.
All elements belonging to this 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 always 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:

Let max_cells be 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 concidered a row heading.
If the current cell's first paragraph has the style Row Heading and max_cells is one, the cell is concidered a row heading.
If a cell is concidered a row heading, only the first paragraph is conveted, other paragraphs are dropped.
If a cell is not concidered a row heading, all paragraphs are converted.
If there are less than max_cells in a row emtpy cells will be ended at the end until there are exactly max_cells in the row.

Stand alone Silva2Word

From 0.2.1 on it is possible to have Silva2Word running stand alone. To set this up you associate slv files 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 for you to grab the file.