Bump version (incompatilibity: dropping old Pythons).
[texml.git] / 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