filled README, fixed a small bug

 PyTeX: a LaTeX package to call Python from LaTeX
 ================================================
 
-(C) 2017 Franck Pommereau <franck.pommereau@ibisc.univ-evry.fr>
-
+(C) 2017 Franck Pommereau <franck.pommereau@ibisc.univ-evry.fr>  
 https://forge.ibisc.univ-evry.fr/fpom/pytex
 
+PyTeX allows one to call Python code from a LaTeX file and to use the
+result directly as if computation has been done by LaTeX. To do so, it
+calls an external script named `pytex` that is responsible for
+executing the code and various other tasks.
+
 ## Installation
 
-TODO
+PyTeX depends on [psutil](https://github.com/giampaolo/psutil) and
+optionally on [Pygments](http://pygments.org) to perform syntax
+highlighting.
+
+Installation under Linux or MacOS is easy.
+
+1. Copy `pytex.py` as `pytex` somewhere in your `PATH`
+2. Make sure it is executable (`chmod +x pytex`)
+3. Copy `pytex.sty` somewhere in your `TEXINPUTS`
+
+PyTeX has not yet been tested under Windows, it should work in theory,
+but I don't know how to call a program `pytex` and have it execute the
+Python script.
 
 ## Usage
 
-TODO
+You may provide Python code as `\pyx{x = 5}` for a snippet that should
+be passed to Python `exec`, or as `\pyv{x+2}` for a snippet that
+should be passed to Python `eval` and the computed value integrated
+into the LaTeX document. You may sue also the corresponding
+environments `pyexec` and `pyeval`.
+
+A Python function `tex(s, *args)` may be called from Python snippets
+to generate some LaTeX code that will be inserted in the document
+instead of the snippet (and, in the case of `\pyv`, after its result).
+Similarly to `%` or `str.format`, it substitutes each occurrence of
+`@` in string `s` with a corresponding value in `args`, ensuring that
+this value is correctly escaped so that it does not contain LaTeX
+special characters. Having `@@` in `s` inserts a single `@` in the
+result without using `args`, option `char='*'` allows to use `*`
+instead of `@` (or any other character). For instance:
+
+    tex("hello")         => hello
+    tex("\foo{@}", "$")  => \foo{\$}
+    tex("@@")            => @
+    tex("@@@+@@@", "x")  => @@@x@@@
+
+Two more commands are available:
+
+ * `\pyc{pass}` inserts a pretty printed version of the Python snippet
+   without evaluating it, environment `pycode` is similar but for a
+   block of code that is not inserted inline
+ * `\pyd{name}{expression}` is similar to
+   `\newcommand{\name}{\pyv{expression}}` but avoids to evaluates
+   `expression` only once instead of each time `\name` is invoked.
+   (And if you ask the question: no, `\edef\name{\pyv{expression}}`
+   does not work.)
+
+When your source file is processed by LaTeX, the Python snippets are
+saved into auxiliary files that may be processed after the LaTeX pass
+or online if you've enabled `-shell-escape`. Note that the security
+issue of using `-shell-escape` exists in both methods because
+arbitrary Python code may be executed anyway.
+
+### Without shell escape
+
+Compile in three passes, like a bibTeX:
+
+1. `latex jobname` saves Python snippets
+2. `pytex jobname` executes Python snippets
+3. `latex jobname` inserts the result of executing Python snippets
+
+### With shell escape
+
+Just run `latex -shell-escape jobname`. Pros: you use just one command
+and the results are inserted on the fly so everything is immediately
+consistent. Cons: it's slower (a server version of PyTeX is launched
+and communication takes some time, this may be improved in the
+future).

@@ -75,7 +75,7 @@ class Interpreter (object) :
                   "^"  : "{\\textasciicircum}",
                   "~"  : "{\\textasciitilde}"}
         return "".join(c if c not in "{}$%#&_\\^~" else escape.get(c, "\\" + c)
-                       for c in text)
+                       for c in str(text))
     def _format (self, text, *args, **opt) :
         char = opt.pop("char", "@")
         if opt :