Texml/processor.py

   1 """
   2 Using TeXML in Python
   3 ---------------------
   4
   5 The module Texml.process converts a TeXML file to a TeX file.
   6
   7 Basic use requires the following:
   8
   9 1. Import the needed libraries
  10 2. Set up the input and output streams
  11 3. Call on the function process
  12 4. Use a try-except block around the call to process
  13 5. Clean up resources
  14
  15 Parameters for the function process
  16 -----------------------------------
  17
  18 in_stream
  19        An input TeXML document as a file object or the path to a file.
  20        Mandatory.
  21
  22 out_stream
  23        An output TeX document as a file object. Mandatory.
  24
  25 autonl_width
  26        Recommended   width  to  split  long  lines  on  smaller  ones.
  27        Optional, default is 62.
  28
  29 encoding
  30        Output   encoding.  Should  be  known  to  the  Python  codecs.
  31        Optional, default is ascii.
  32
  33 always_ascii
  34        Use  only ASCII symbols for output. Non-ASCII bytes are escaped
  35        using  the  ^^XX  form,  where  XX is a hexadecimal code of the
  36        character.  Optional,  default  is  0  (False, do not encode as
  37        ASCII).
  38
  39 use_context
  40        ConTeXt  is  an  alternative  to  LaTeX. In ConTeXt mode, TeXML
  41        translation  is slightly different. Set to 1 (True) to activate
  42        this mode. Optional, default is 0 (False, LaTeX mode).
  43
  44 If the input file doesn't conform to the TeXML specification, then the
  45 exception  TeXML.handler.InvalidXmlException  is  raised. If the input
  46 parameters  are  invalid,  then  the  exception  ValueError is raised.
  47 Expect that the underlying libraries might also raise exceptions, such
  48 as xml.sax.SAXException.
  49
  50 Simplest example
  51 ----------------
  52
  53 #!/usr/bin/python
  54
  55 # Import the needed libraries
  56 import sys
  57 import Texml.processor
  58
  59 # Use the standard input and output
  60 in_stream  = sys.stdin
  61 out_stream = sys.stdout
  62
  63 # Convert
  64 Texml.processor.process(in_stream, out_stream)
  65
  66 Full example
  67 ------------
  68
  69 #!/usr/bin/python
  70
  71 # Import the needed libraries
  72 import sys
  73 import Texml.processor
  74
  75 # Input can be given by a path, output should be a file object
  76 infile = 'document.xml'
  77 out    = file('out.tex', 'w')
  78 # Older versions of python need the following code:
  79 # out = open('out.tex', 'w')
  80
  81 # Parameters
  82 width        = 75
  83 encoding     = 'UTF-8'
  84 always_ascii = 1
  85 use_context  = 1
  86
  87 # Convert TeXML inside a try-except block
  88 try:
  89   Texml.processor.process(
  90       in_stream    = infile,
  91       out_stream   = out,
  92       autonl_width = width,
  93       encoding     = encoding,
  94       always_ascii = always_ascii,
  95       use_context  = use_context)
  96 except Exception as msg:
  97   print sys.stderr, 'texml: %s' % str(msg)
  98
  99 # Clean up resources
 100 out.close()
 101 """
 102 # $Id: processor.py,v 1.2 2006-06-06 03:37:18 olpa Exp $
 103
 104 import Texml.texmlwr
 105 import Texml.handler
 106
 107 def process(in_stream, out_stream, encoding='ascii', autonl_width=62, always_ascii=0, use_context=0):
 108   transform_obj = Texml.handler.ParseFile()
 109   texml_writer =  Texml.texmlwr.texmlwr(
 110       stream       = out_stream,
 111       encoding     = encoding,
 112       autonl_width = autonl_width,
 113       use_context  = use_context,
 114       always_ascii = always_ascii,
 115       )
 116   transform_obj.parse_file(
 117       read_obj     = in_stream,
 118       texml_writer = texml_writer,
 119       use_context  = use_context,
 120       )
 121