Showing
2 changed files
with
72 additions
and
4 deletions
... | @@ -2,13 +2,81 @@ PyTeX: a LaTeX package to call Python from LaTeX | ... | @@ -2,13 +2,81 @@ PyTeX: a LaTeX package to call Python from LaTeX |
2 | ================================================ | 2 | ================================================ |
3 | 3 | ||
4 | (C) 2017 Franck Pommereau <franck.pommereau@ibisc.univ-evry.fr> | 4 | (C) 2017 Franck Pommereau <franck.pommereau@ibisc.univ-evry.fr> |
5 | - | ||
6 | https://forge.ibisc.univ-evry.fr/fpom/pytex | 5 | https://forge.ibisc.univ-evry.fr/fpom/pytex |
7 | 6 | ||
7 | +PyTeX allows one to call Python code from a LaTeX file and to use the | ||
8 | +result directly as if computation has been done by LaTeX. To do so, it | ||
9 | +calls an external script named `pytex` that is responsible for | ||
10 | +executing the code and various other tasks. | ||
11 | + | ||
8 | ## Installation | 12 | ## Installation |
9 | 13 | ||
10 | -TODO | 14 | +PyTeX depends on [psutil](https://github.com/giampaolo/psutil) and |
15 | +optionally on [Pygments](http://pygments.org) to perform syntax | ||
16 | +highlighting. | ||
17 | + | ||
18 | +Installation under Linux or MacOS is easy. | ||
19 | + | ||
20 | +1. Copy `pytex.py` as `pytex` somewhere in your `PATH` | ||
21 | +2. Make sure it is executable (`chmod +x pytex`) | ||
22 | +3. Copy `pytex.sty` somewhere in your `TEXINPUTS` | ||
23 | + | ||
24 | +PyTeX has not yet been tested under Windows, it should work in theory, | ||
25 | +but I don't know how to call a program `pytex` and have it execute the | ||
26 | +Python script. | ||
11 | 27 | ||
12 | ## Usage | 28 | ## Usage |
13 | 29 | ||
14 | -TODO | 30 | +You may provide Python code as `\pyx{x = 5}` for a snippet that should |
31 | +be passed to Python `exec`, or as `\pyv{x+2}` for a snippet that | ||
32 | +should be passed to Python `eval` and the computed value integrated | ||
33 | +into the LaTeX document. You may sue also the corresponding | ||
34 | +environments `pyexec` and `pyeval`. | ||
35 | + | ||
36 | +A Python function `tex(s, *args)` may be called from Python snippets | ||
37 | +to generate some LaTeX code that will be inserted in the document | ||
38 | +instead of the snippet (and, in the case of `\pyv`, after its result). | ||
39 | +Similarly to `%` or `str.format`, it substitutes each occurrence of | ||
40 | +`@` in string `s` with a corresponding value in `args`, ensuring that | ||
41 | +this value is correctly escaped so that it does not contain LaTeX | ||
42 | +special characters. Having `@@` in `s` inserts a single `@` in the | ||
43 | +result without using `args`, option `char='*'` allows to use `*` | ||
44 | +instead of `@` (or any other character). For instance: | ||
45 | + | ||
46 | + tex("hello") => hello | ||
47 | + tex("\foo{@}", "$") => \foo{\$} | ||
48 | + tex("@@") => @ | ||
49 | + tex("@@@+@@@", "x") => @@@x@@@ | ||
50 | + | ||
51 | +Two more commands are available: | ||
52 | + | ||
53 | + * `\pyc{pass}` inserts a pretty printed version of the Python snippet | ||
54 | + without evaluating it, environment `pycode` is similar but for a | ||
55 | + block of code that is not inserted inline | ||
56 | + * `\pyd{name}{expression}` is similar to | ||
57 | + `\newcommand{\name}{\pyv{expression}}` but avoids to evaluates | ||
58 | + `expression` only once instead of each time `\name` is invoked. | ||
59 | + (And if you ask the question: no, `\edef\name{\pyv{expression}}` | ||
60 | + does not work.) | ||
61 | + | ||
62 | +When your source file is processed by LaTeX, the Python snippets are | ||
63 | +saved into auxiliary files that may be processed after the LaTeX pass | ||
64 | +or online if you've enabled `-shell-escape`. Note that the security | ||
65 | +issue of using `-shell-escape` exists in both methods because | ||
66 | +arbitrary Python code may be executed anyway. | ||
67 | + | ||
68 | +### Without shell escape | ||
69 | + | ||
70 | +Compile in three passes, like a bibTeX: | ||
71 | + | ||
72 | +1. `latex jobname` saves Python snippets | ||
73 | +2. `pytex jobname` executes Python snippets | ||
74 | +3. `latex jobname` inserts the result of executing Python snippets | ||
75 | + | ||
76 | +### With shell escape | ||
77 | + | ||
78 | +Just run `latex -shell-escape jobname`. Pros: you use just one command | ||
79 | +and the results are inserted on the fly so everything is immediately | ||
80 | +consistent. Cons: it's slower (a server version of PyTeX is launched | ||
81 | +and communication takes some time, this may be improved in the | ||
82 | +future). | ... | ... |
... | @@ -75,7 +75,7 @@ class Interpreter (object) : | ... | @@ -75,7 +75,7 @@ class Interpreter (object) : |
75 | "^" : "{\\textasciicircum}", | 75 | "^" : "{\\textasciicircum}", |
76 | "~" : "{\\textasciitilde}"} | 76 | "~" : "{\\textasciitilde}"} |
77 | return "".join(c if c not in "{}$%#&_\\^~" else escape.get(c, "\\" + c) | 77 | return "".join(c if c not in "{}$%#&_\\^~" else escape.get(c, "\\" + c) |
78 | - for c in text) | 78 | + for c in str(text)) |
79 | def _format (self, text, *args, **opt) : | 79 | def _format (self, text, *args, **opt) : |
80 | char = opt.pop("char", "@") | 80 | char = opt.pop("char", "@") |
81 | if opt : | 81 | if opt : | ... | ... |
-
Please register or login to post a comment