README
1Converting tpic \special's into \pdfliteral's by awk
2====================================================
3
4The experimental awk-script tpic2pdftex builds one bridge between the
5"pic" graphics language and pdfTeX.
6
7What tpic2pdftex does:
8
9We start from one or more graphics described by the venerable pic language
10(see e. g., file example.pic), embedded inline within pdfTeX or pdfLaTeX
11code, and limited by classical .PS and .PE markers as known from groff.
12The pic graphics might be annotated by TeX or LaTeX text. This pic/TeX
13language-mix file is piped through the (groff-)pic preprocessor and the
14tpic2pdftex script. The result is a TeX file with inline \pdfliteral{}
15sections, for further processing by pdftex or pdflatex.
16
17
18Usage
19-----
20
21 $ export LANG="C"
22 $ pic -t somefile.pic | tpic2pdftex > somefile.tex
23
24Process somefile.tex by pdftex or pdflatex.
25
26
27Files
28-----
29
30tpic2pdftex
31 The executable awk-script for converting tpic specials into pdfliterals
32 for further processing by pdftex. For usage see head of this file.
33
34tpic2pdftex.1
35 The man-page for tpic2pdftex.
36
37example.pic
38 A small pic sample file (plain-TeX), as input.
39
40example.pdf
41 The resulting example PDF file (the dotted and dashed ellipses are
42 part of gpic from version 1.19.1 on).
43
44beamerexample.pic
45 Another small pic sample file (pdfLaTeX), which shows that images
46 created by pic can be incrementally built up in the beamer class.
47
48beamerexample.pdf
49 The resulting PDF file from beamerexample.pic.
50
51Makefile
52 The Makefile used to produce file example.pdf and beamerexample.pdf
53 from the input files.
54
55README
56 This file.
57
58
59Portability
60-----------
61
62This awk-script should be useable on all systems on which a working awk
63program (e. g., awk, gawk, mawk) is installed.
64
65The script has been tested with GNU pic (groff), versions 1.18.1 and
661.19.3, and pdftex, versions 1.40.9 and 1.50.0 on a debian lenny (5.0)
67x86_64 PC.
68
69
70Remarks
71-------
72
731. If more than a single .pic file provide the source for the .tex file,
74there are two options: Either separately run all .pic files through the
75pic -t | tpic2pdftex pipe and combine them by TeX's \input statements
76as usual. Or make one big .pic file by using the soelim program from
77groff (with option -t), and then run the resulting .pic file through pic,
78tpic2pdftex, and TeX. File embedding by soelim is done by the request:
79
80 .so somefile.pic
81
82The process call then could look like e. g.:
83
84 $ soelim -t somefile.pic | pic -t | tpic2pdftex > somefile.tex
85
862. Depending on the awk version, "locale" settings might have influence
87on the separator in floating point numbers. PDF requires decimal _dots_
88(e. g., 3.14 rather than 3,14) which is checked by tpic2pdftex at the
89begin of the run. If you get an ERROR message, set LANG="C", so that
90decimal dots are used as float separators.
91
92
93Literature
94----------
95
96Brian W. Kernighan: PIC -- A Graphics Language for Typesetting, User
97Manual, Revised, May, 1991. File cstr116.ps.
98
99Eric S. Raymond: Making Pictures With GNU PIC. File gpic.raymond.ps.
100
101Both files are available online from various places.
102
103
104Comments welcome. Have fun!
105
106Hartmut
107
108$Id: README,v 1.11 2010/01/16 12:38:21 hahe Exp hahe $
109