summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/ltximg/ltximg-doc.tex
blob: cfe90a9d0576ee07c428222b81b0ccbae1234c96 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
\documentclass[10pt]{article}
\usepackage[T1]{fontenc}%
\usepackage{hologo}%
\usepackage{fetamont}%
\usepackage{libertine}%
\usepackage{booktabs}%
\usepackage{tabularx}%
\usepackage{tcolorbox}%
\tcbuselibrary{documentation}%
\usepackage[margin=1.0in,letterpaper]{geometry}%
\usepackage[scaled=0.9]{inconsolata}%
\usepackage{listings}%
% colors
\definecolor{lightgrey}{rgb}{0.9,0.9,0.9}
\definecolor{darkgreen}{rgb}{0,0.6,0}
\definecolor{darkred}{rgb}{0.6,0,0}
\definecolor{myblue}{RGB}{20,105,176}
\definecolor{darkgreen}{rgb}{0,0.6,0}
% languaje
\lstdefinelanguage{mytex}[LaTeX]{TeX}{
columns=flexible,
frame=single,
framerule=0pt,%
backgroundcolor=\color{gray!10},%
xleftmargin=\fboxsep,%
xrightmargin=\fboxsep,
alsoletter={\\,*,\&},
morekeywords={\\AtBeginDocument,
              \\RequirePackage,
              \\PreviewEnvironment,
              \&},  
morekeywords=[2]{pspicture,
               verbatim,
               table,
               other,
               tikzpicture,
               postscript,
               preview,
               TRICKS,
               POSTRICKS,
               TIKZPICTURE,
               OTHER,
               nopreview},
morekeywords=[3]{\\begin,
                \\pspicture,
                \\TRICKS,
                \\ENDTRICKS,
                \\endpspicture,
                \\end},  
literate=*{\{}{{\textcolor{myblue}{\{}}}{1}
        {\}}{{\textcolor{myblue}{\}}}}{1}
        {[}{{\textcolor{myblue}{[}}}{1}
        {]}{{\textcolor{myblue}{]}}}{1},
    }
\lstset{language=mytex}

\lstdefinestyle{mystyle1}{
    basicstyle=\small\ttfamily,
    keywordstyle=\bfseries\color{red},
    keywordstyle=[2]{\color{magenta}},
    keywordstyle=[3]{\color{blue}},
    commentstyle=\color{darkgreen}, 
    stringstyle=\color{orange},
    identifierstyle=\ttfamily,
    showstringspaces=true,
    breaklines=true,
    tabsize=4,
    columns=fullflexible,
    keepspaces=true,
    }
% style
\lstset{style=mystyle1}
\begin{document}
\title{{\Huge\textffm{LTX}\textffmw{img} \normalsize \Large\textffmw{v1.1}}\\\small\textffm{tikz|pgf|pstricks \\to image format}}
\author{Pablo Gonz\'{a}lez Luengo\\ \small \ttfamily pablgonz at yahoo dot com}
\date{\today}
\maketitle
\begin{abstract}
\noindent

\textsf{ltximg} is a \textsf{Perl} script that automates the process to extract and convert all PGF|TiKZ|Pstricks environments from input file  to image formats (pdf,png,jpg,eps,ppm,svg) and source code for environments in individual files using \textsf{Ghostscript} and other software. By default search and extract environments using \hologo{pdfLaTeX}.
\end{abstract}
\tableofcontents
\section{Required Software}

For the full operation of the \textsf{ltximg} script you need the following opensource programs
(available for windows and linux).

\begin{itemize}
\item \textsf{Perl} (version 5.18 or higer).

\item \textsf{Ghostscript} (version 9.16).

\item \textsf{pdftops} (optional, for images in \textsf{EPS} format).

\item \textsf{pdftoppm} (optional, for images in \textsf{PPM} format).

\item \textsf{pdf2svg} (optional, for images in \textsf{SVG} format).
\end{itemize}
\newpage
\section{Run and options}
the syntax for \textsf{ltximg} script is simple:
\noindent
For \TeX Live users: 
\begin{lstlisting}
ltximg file.tex --options
\end{lstlisting}
For Mik\TeX\ users:
\begin{lstlisting}
perl ltximg file.tex --miktex --options
\end{lstlisting}

\begin{table}[htp]
\caption{Options for \textsf{ltximg}}
\begin{tabularx}{\linewidth}{@{}>{\ttfamily} l>{\ttfamily} l >{\ttfamily}l X @{}}\\\toprule
\emph{short} & \emph{long} & \emph{default} & \emph{description}\\\midrule
  -h	&--help         &      	& Display help from command line and exit.\\
  -l	&--license      &      	& Display license information and exit.\\
  -v	&--version 	& 1.1  	& Display version of script and exit.\\
  -d	&--dpi=<int>    & 150  	& The dots per inch for images.\\
  -j	&--jpg          &      	& Create \textsf{.jpg} files (need \textsf{Ghostscript}).\\
  -p	&--png          &   	& Create \textsf{.png}files (need \textsf{Ghostscript}).\\
  -e	&--eps	     	&    	& Create \textsf{.eps} files (need \textsf{pdftops}).\\
  -s	&--svg	     	&    	& Create \textsf{.svg} files (need \textsf{pdf2svg}).\\
  -P	&--ppm	     	&    	& Create \textsf{.ppm} files (need \textsf{pdftoppm}).\\
  -a	&--all	     	&    	& Create \textsf{.(pdf,eps,jpg,png)} images.\\
  -c	&--clear     	&    	& Delete all temp and aux files.\\
  -o	&--output    	&    	& Create a \textsf{file-out.tex} whitout \textsf{PGF|TiKZ|PST} code.\\
  -m	&--margins=<int>& 0 	& Margins in bp for \textsf{pdfcrop}.\\
  -np	&--nopreview   	& off 	& Create images files whitout \textsf{preview} package.\\
  -ns	&--nosource    	& off	& Delete all source for images files\\
	&--miktex       &-shell-escape & Use \textsf{--enable-write18} for \hologo{MiKTeX} users.\\
	&--xetex        & off 	& Using \hologo{XeLaTeX} for create images.\\
	&--latex        & off	& Using \hologo{LaTeX} for create images.\\
	&--luatex       & off 	& Using \hologo{LuaLaTeX} for create images.\\
	&--nopdf        & off 	& Don't create a PDF image files.\\
	&--other=<string> & other & Search \textsf{other} environment for export.\\
	&--ignore=<string> & ignore& Skip verbatim environment.\\
	&--imgdir=<string> & images & The folder for images.\\
 \bottomrule
\end{tabularx}
\end{table}



\section{How it works}

The script works in two steps for create image, source code and output file \emph{without PGF/TIKZ/PST} environments.


\subsection{Environment Suports}

\textsf{ltximg} export and convert this environment:

\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{pspicture}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{pspicture*}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{postscript}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{circuitikz}%
{}
\end{docEnvironment}
\end{minipage}

\vspace{0.5cm}

\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{tikzpicture}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{pgfpicture}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{ganttchart}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{forest}%
{}
\end{docEnvironment}
\end{minipage}
\vspace{0.5cm}

\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{tikzcd}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{circuitikz}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{dependency}%
{}
\end{docEnvironment}
\end{minipage}
\begin{minipage}[c]{0.25\columnwidth}
\begin{docEnvironment}%
{other}%
{}
\end{docEnvironment}
\end{minipage}



\subsection{Comment and ignore}

The first step \textsf{ltximg } script create a image dir (\textsf{images/})
and read all input file in memory, processing is as follows, being assumed that our file is \texttt{test.tex}:

\begin{enumerate}
\item  Create a copy file in memory and change problematic environments (verbatim, verbatim\*, lstlisting,
 LTXexample, Verbatim, comment, alltt, minted, tcblisting, xcomment and ignore) 

\item  Change problematic inline verbatim from varius package (lstlisting,LTXexample, Verbatim, comment, alltt, minted, tcblisting, etc) include line whit \%. 
\end{enumerate}



\subsection{Create source and images}
\begin{enumerate}

\item If script is call whitout \textsf{--nopreview} option (default), adds the following lines to the beginning of the test.tex in memory and save file test-fig.tex in images dir :

\begin{lstlisting}
\AtBeginDocument{
\RequirePackage[active,tightpage]{preview}
\renewcommand\PreviewBbAdjust{-60pt -60pt 60pt 60pt}%
\newenvironment{postscript}{}{}%
\PreviewEnvironment{postscript}}%
\end{lstlisting}

\item If script is call whit \textsf{--nopreview} option, all environment code its put inside the :

\begin{lstlisting}
\begin{postscript}
...
\end{postscript}
\end{lstlisting}

and separate in individual files (test-fig-1.tex, test-fig-2.tex, etc) in image dir and join in test-fig.tex. The postscript environment  can be used to place any material to be exported if that is not supported or fails the \textsf{--other} option.


\item Now, the script call (pdf/lua/xe)latex in \texttt{test-fig.tex} and \textsf{pdfcrop} in 
\texttt{test-fig.pdf} and create image files.
\end{enumerate}

\section{Example}
\begin{lstlisting}
ltximg test.tex -e -p -j -c -o --imgdir=pics
\end{lstlisting}
produce test-out.tex whitout PGF|TiKZ|PST environments and create "pics" dir whit all images (pdf,eps,png,jpg) and source (.tex) for all related parts using \hologo{pdfLaTeX} whit preview package and cleaning all tmp files. 

\noindent
Suport bundling for short options: 
\begin{lstlisting}
ltximg test.tex -epjco --imgdir=pics
\end{lstlisting}
\end{document}



LTXimg extract and convert all PGF|TiKZ|Pstricks environments from TeX 
  source into single images files (pdf/png/eps/jpg/svg) using Ghostscript. 
  By default search and extract environments using (pdf)LaTeX.

Environments suports by LTXimg:

    pspicture	tikzpicture	pgfpicture	forest	ganttchart
    tikzcd	circuitikz	dependency	other	postscript

Options:
\begin{tabularx}{\linewidth}{@{}>{\ttfamily} l>{\ttfamily} l >{\ttfamily}l X @{}}\\\toprule
\emph{short} & \emph{name} & \emph{default} & \emph{description}\\\midrule
  -h&--help          &      &display this help and exit
  -l&--license       &      &- display license information and exit
  -v&--version 	     &      & - display version (current 1.2) and exit
  -d&--dpi=<int>     & 150 & - the dots per inch for images
  -j&--jpg           &    &- create .jpg files (need Ghostscript)
  -p&--png           &   &- create .png files (need Ghostscript)
  -e&--eps	     &    &- create .eps files (need pdftops)
  -s&--svg	     &    &- create .svg files (need pdf2svg)
  -P&--ppm	     &    &- create .ppm files (need pdftoppm)
  -a&--all	     &    &- create .(pdf,eps,jpg,png) images
  -c&--clear     &    &- delete all temp and aux files
  -o&--output    &    &- create a file-out.tex whitout PGF|TiKZ|PST code
  -m&--margins=<int>& &- margins in bp for pdfcrop (default 0)
  -np&--nopreview   & &- create images files whitout preview package
  -ns&--nosource    & &- delete all source for images files
  &--miktex         &  &- use --enable-write18 for MikTeX users
  &--xetex          &  &- using (Xe)LaTeX for create images
  &--latex          &  &- using LaTeX for create images
  &--luatex         &  &- using (Lua)LaTeX for create images
  &--nopdf          &  &- don't create a PDF image files (default off)
  &--other=<string> &  &- search other environment (default other)
  &--ignore=<string> & &- skip verbatim environment (default ignore)
  &--imgdir=<string> & &- the folder for images (default images)
 \bottomrule
\end{tabularx}
  
  
Example:
* ltximg test.tex -e -p -j -c -o --imgdir=pics
* produce test-out.tex whitout PGF|TiKZ|PST environments and create "pics"
* dir whit all images (pdf,eps,png,jpg) and source (.tex) for all related 
* parts using (pdf)LaTeX whit preview package and cleaning all tmp files. 
* Suport bundling for short options: ltximg test.tex -epjco --imgdir=pics
END_OF_USAGE