Copyright (c) 2002 Infrae. All rights reserved.  
See also LICENSE

Meta::

  Valid for:  Docma 0.6 
  Authors:    Christian Zagrodnick and Guido Wesdorp
  Emails:     cz@gocept.com, guido@infrae.com
  CVS:        $Id: README.txt,v 1.15 2003/08/14 08:03:40 guido 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 can 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":http://infrae.com/products/docma/docma_server/allstyles.doc.
  There is also a
  "template":http://infrae.com/products/docma/docma_server/silva.dot 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:
  
  o Lists of any numbering become a '1, 2, 3...' list in Silva.

  o Bulleted lists become a 'disc bullet' list in Silva.
  
  o Other text become a Silva paragraph.

  o All tables will get the 'grid' style.

  o 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:

    o Every list entry has to start with a paragraph with a list style of
      any kind or level. 

    o If the paragraph contains text, a paragraph will be created by w2s.
      If the paragraph does not contain text, no paragraph will be created.

    o 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:

    o Let max_cells be the maximum amount of cells per row.

    o If the current row consists of only one cell and max_cells is greater
      than one, the cell is concidered a row heading.

    o If the current cell's first paragraph has the style *Row Heading* and 
      max_cells is one, the cell is concidered a row heading.

    o If a cell is concidered a row heading, only the first paragraph is
      conveted, other paragraphs are dropped.

    o If a cell is not concidered a row heading, all paragraphs are converted.

    o 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 conversion
  
  Note: the old tool for standalone conversion (silva2word.py) doesn't work
  anymore!

  For standalone conversion one can use the files 's2w_standalone.py' and 
  'w2s_standalone.py' for resp. Silva 2 Word and Word 2 Silva conversion 
  without using the XMLRPC server. These can both be ran from the 
  command-prompt, using a Python interpreter to run them and adding the
  path(s) to the document(s) to be converted as the only argument.
  For example: 'c:\python22\python s2w_standalone.py slvs\*.slv' will convert
  each '.slv' file in the 'slvs' directory using the Python interpreter in
  'c:\python22'. 

  After conversion the result will be placed in the same directory as the 
  source, with a replaced extension (.doc for s2w conversions, .slv for w2s).

  Also in the Docma package are files to convert using the XMLRPC server on
  the same machine (s2w_server_batch.py for Silva 2 Word and 
  w2s_server_batch.py for Word 2 Silva) and a file that does round-trip
  conversion (slv_roundtrip.py), also using the XMLRPC server locally.

