From 7118801c6c53b01dfad47da9c5498b08338c336e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 2 May 2018 18:32:35 +0000 Subject: ltximg (12apr18) git-svn-id: svn://tug.org/texlive/trunk@47568 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/support/ltximg/ltximg-doc.dtx | 1594 ++++++++++++++++++++ 1 file changed, 1594 insertions(+) create mode 100644 Master/texmf-dist/source/support/ltximg/ltximg-doc.dtx (limited to 'Master/texmf-dist/source/support') diff --git a/Master/texmf-dist/source/support/ltximg/ltximg-doc.dtx b/Master/texmf-dist/source/support/ltximg/ltximg-doc.dtx new file mode 100644 index 00000000000..75e550b2baf --- /dev/null +++ b/Master/texmf-dist/source/support/ltximg/ltximg-doc.dtx @@ -0,0 +1,1594 @@ +% arara: lualatex: {draft: yes} +% arara: makeindex: {style: gind} +% arara: lualatex: {draft: yes} +% arara: lualatex +% arara: clean: { files:[ltximg-doc.ilg, ltximg-doc.out, ltximg-doc.ind, ltximg-doc.aux, ltximg-doc.idx, ltximg-doc.log, ltximg-doc.toc] } +% \iffalse meta-comment +%<*internal> +\iffalse +% +%<*readme> +## LTXimg – LaTeX environments to image format + +## Description + +**ltximg** is a perl *script* that automates the process of extracting and converting +environments provided by **tikz**, **pstricks** and other packages from input file +to image formats in individual files using `ghostscript` and `poppler-utils`. Generates a file +with only extracted environments and other with environments converted to `\includegraphics`. + +## Syntax +``` +$ ltximg [] [] [--] . +``` +## Usage +``` +$ ltximg --latex [] +$ ltximg --arara [] +$ ltximg [] +$ ltximg +``` +If used without `[]` and `[]` the extracted environments are converted to `pdf` image format +and saved in the `/images` directory using `pdflatex` and `preview` package. Relative or absolute `paths` for files +and directories is not supported and if the last `[]` take a list separated by commas you need `--` at the end. + +## Default environments extract +``` + pspicture tikzpicture pgfpicture psgraph postscript PSTexample +``` +## Options + +``` + [default] +-h, --help Display command line help and exit [off] +-l, --license Display GPL license and exit [off] +-v, --version Display current version (v1.5) and exit [off] +-t, --tif Create .tif files using ghostscript [gs] +-b, --bmp Create .bmp files using ghostscript [gs] +-j, --jpg Create .jpg files using ghostscript [gs] +-p, --png Create .png files using ghostscript [gs] +-e, --eps Create .eps files using poppler-utils [pdftops] +-s, --svg Create .svg files using poppler-utils [pdftocairo] +-P, --ppm Create .ppm files using poppler-utils [pdftoppm] +-g, --gray Gray scale for images using ghostscript [off] +-f, --force Capture "\psset" and "\tikzset" to extract [off] +-n, --noprew Create images files whitout "preview" package [off] +-d , --dpi + Dots per inch resolution for images [150] +-m , --margin + Set margins for pdfcrop [0] +--imgdir Set name of directory to save images [images] +-o , --output + Create output file [off] +--verbose Verbose printing [off] +--srcenv Create files whit only code environment [off] +--subenv Create files whit preamble and code [off] +--latex Using latex>dvips>ps2pdf for compiler input + and pdflatex for compiler output [off] +--dvips Using latex>dvips>ps2pdf for compiler input + and latex>dvips>ps2pdf for compiler output [off] +--arara Use arara for compiler input and output [off] +--xetex Using xelatex for compiler input and output [off] +--dvipdf Using dvipdfmx for compiler input and output [off] +--luatex Using lualatex for compiler input and output [off] +--prefix Set prefix append to each image file [off] +--norun Run script, but no create images files [off] +--nopdf Don't create a ".pdf" image files [off] +--nocrop Don't run pdfcrop [off] +--verbcmd Set "\cmdname" verbatim command [myverb] +--clean (doc|pst|tkz|all|off) + Removes specific text in output file [doc] +--extrenv Add new environments to extract [empty] +--skipenv Skip environments to extract [empty] +--verbenv Add verbatim environments [empty] +--writenv Add verbatim write environments [empty] +--deltenv Delete environments in output file [empty] +``` +## Example +``` +$ ltximg --latex -e -p --srcenv --imgdir=mypics -o test-out test-in.ltx +``` +``` +$ ltximg --latex -ep --srcenv --imgdir mypics -o test-out test-in.ltx +``` + Create a `/mypics` directory whit all extracted environments converted to + image formats(`.pdf`, `.eps`, `.png`), individual files whit source code (`.tex`) + for all extracted environments, a file `test-out.ltx` whit all environments converted to `\includegraphics` + and file `test-in-fig-all.tex` with only the extracted environments using + `latex>dvips>ps2pdf` and `preview` package for `` and `pdflatex` + for ``. + +## Documentation + For full documentation use: +``` +$ texdoc ltximg +``` + +## Licence +This program is free software; you can redistribute it and/or modify it under the terms of the GNU +General Public License as published by the Free Software Foundation; either version 3 of the License, +or (at your option) any later version. + +This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even +the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public +License for more details. + +## Author + +Written by Pablo González L , last update 2018-04-12. + +## Copyright + +Copyright 2013 - 2018 by Pablo González L +% +%<*changues> +## Changues +``` + v1.5. (d) 2018-04-12 - Use GitHub to control version + - Rewrite and optimize most part of code and options + - Changue pdf2svg for pdftocairo + - Complete support for pst-exa packpage + - Clean take and optional + v1.4. (d) 2016-11-29 - Remove and rewrite code for regex and system call + - Append arara compiler, clean and comment code + - Append dvips and dvipdfm for creation images + - Append bmp, tif image format + v1.3. (d) 2016-10-16 - All options its read from cmd line and input file + - Rewrite some part of code (norun, nocrop, clean) + - Suport minted and tcolorbox packpage for verbatim + - Use /tmp dir for work process + - Escape some characters in regex according to v5.2xx + v1.2 (p) 2015-04-22 - Remove unused modules + v1.1 (p) 2015-04-21 - Change mogrify to gs for image formats + - Create output file + - Rewrite source code and fix regex + - Add more image format + - Change date to iso format + v1.0 (p) 2013-12-01 - First public release +``` +Copyright 2013 - 2018 by Pablo González L . +% +%<*internal> +\fi +\def\nameofplainTeX{plain} +\ifx\fmtname\nameofplainTeX\else + \expandafter\begingroup +\fi +% +%<*internal> +\input docstrip.tex +\keepsilent +\askforoverwritefalse +\nopreamble\nopostamble +\generate{ + \file{README.md}{\from{\jobname.dtx}{readme}} + \file{CHANGUES.md}{\from{\jobname.dtx}{changues}} +} +\ifx\fmtname\nameofplainTeX + \expandafter\endbatchfile +\else + \expandafter\endgroup +\fi +% +%<*documentation> +\documentclass{ltxdoc} +\usepackage[top=0.5in, bottom=0.5in, left=2in, right=1in,footskip=0.2in,% + headsep=10pt]{geometry} % page dimension +\usepackage[totoc,columns=2]{idxlayout} % index +\EnableCrossrefs +\CodelineIndex +\usepackage[mono=false]{libertine} % default roman/serif fonts +\setmonofont[ + Ligatures = TeX , + Scale = 0.84, + Extension = .otf, + UprightFont = *-Regular , + ItalicFont = *-RegularIt, + BoldFont = *-Medium , + BoldItalicFont = *-MediumIt + ]{SourceCodePro} % srccode font +\usepackage{microtype,fetamont,hologo} % LaTeX logo and LTXimg logo +\usepackage{xspace,tocloft,enumitem,fancyhdr,lastpage} % custom +\usepackage[svgnames]{xcolor} % colors :) +\usepackage[sf,bf,compact,medium]{titlesec} % sections +\usepackage{adjustbox,multicol,hyperref,xparse,listings,accsupp} +\usepackage{interfaces,graphicx} + +% don't copy numbers in code example +\newcommand*{\noaccsupp}[1]{\BeginAccSupp{ActualText={}}#1\EndAccSupp{}} + +% parindent +\setlength{\parindent}{0pt} + +% Colors for options +\definecolor{optcolor}{rgb}{0.281,0.275,0.485} + +% Logo whit libertine font for title +\newsavebox{\logobox} +\savebox{\logobox}{% + \normalsize% + {\libertineInitial% + \textcolor{red}{L}\hspace{-3.0pt}% + \raisebox{-0.2em}{\small \textcolor{green}{T}}% + \hspace{-2.9pt}\textcolor{blue}{X}}% + \hspace{-1pt}\textffmw{\textcolor{gray}{img}}% +}% close box + +\makeatletter % changes the catcode of @ to 11 +\newcommand{\LTXimg}{% + \settoheight{\@tempdima}{L}% + \resizebox{!}{\@tempdima}{\usebox{\logobox}}% +} +\makeatother % changes the catcode of @ back to 12 + +% oldstyle for libertine, need after \LTXimg +\useosf + +% logo for body docuement +\newcommand*{\ltximg}{% + \normalsize\texttt{\bfseries + \textcolor{NavyBlue}{ltximg}}\xspace% +}% close ltximg + +% Identification +\def\myscript{ltximg} +\def\fileversion{1.5} +\def\filedate{2018-04-12} +% Config hyperref +\hypersetup{ + linkcolor = blue!50, + citecolor = red!50,% + urlcolor = magenta,% + colorlinks = true,% + pdftitle ={.::ltximg v1.5 (2018-04-12) --- LaTeX environments to image formats::.},% + pdfauthor= {Pablo Gonz\'{a}lez Luengo},% á fails + pdfsubject={Documentation for version 1.5},% + pdfstartview={FitH},% + bookmarksopenlevel=2,% +} + +% Configuration fancyhdr +\fancypagestyle{plain}{% +\fancyhf{}% +\fancyfoot[R]{\small\textsf{\thepage{} /\pageref{LastPage}}} +\renewcommand{\headrulewidth}{0pt}% +\renewcommand{\footrulewidth}{0pt}% +}% close plain style + +\renewcommand{\sectionmark}[1]{ + \markboth{\textsf{\scshape\small\S\thesection. #1}}{} + }% + +\fancypagestyle{myheader}{% +\fancyhf{}% +\fancyhead[L]{\raisebox{-0.75\baselineskip}[0pt][0pt]{% +\textsf{\small \textcolor{gray}{Documentation for version \fileversion{} [\filedate]}}% + }% + }% +\fancyhead[R]{\raisebox{-0.75\baselineskip}[0pt][0pt]{% + \small\nouppercase{\leftmark}% + }% + }% +\fancyfoot[R]{\small\textsf{\thepage{} /\pageref{LastPage}}} +\fancyfoot[L]{% + \small\sffamily% + \LTXimg{} + \textcolor{gray}{% + \raisebox{-1pt}{\textcopyright}{}2013--2018 by Pablo González L% + }% +}% +\renewcommand{\headrulewidth}{0.5pt}% +\renewcommand{\footrulewidth}{0pt}% +\renewcommand{\headrule}{% + \hbox to\headwidth{% + \color{NavyBlue}\leaders\hrule height \headrulewidth\hfill}% + }% +} % close myheader + +% add headheight +\setlength{\headheight}{21pt}% + +% Custom \meta[...]{...}, \marg[...]{...} and \oarg[...]{...} for color +\ExplSyntaxOn +%^^A user level commands +\RenewDocumentCommand{\meta}{O{}m} +{ + \ltximg_meta_generic:Nnn \ltximg_meta:n { #1 } { #2 } +} +\RenewDocumentCommand{\marg}{O{}m} +{ + \ltximg_meta_generic:Nnn \ltximg_marg:n { #1 } { #2 } +} +\RenewDocumentCommand{\oarg}{O{}m} +{ + \ltximg_meta_generic:Nnn \ltximg_oarg:n { #1 } { #2 } +} +%^^A variables and keys +\tl_new:N \l_ltximg_meta_font_tl + +\keys_define:nn { ltximg/meta } +{ + type .choice:, + type / tt .code:n = \tl_set:Nn \l_ltximg_meta_font_tl { \ttfamily }, + type / rm .code:n = \tl_set:Nn \l_ltximg_meta_font_tl { \rmfamily }, + type .initial:n = tt, + cf .tl_set:N = \l_ltximg_meta_color_tl, + cf .initial:n = black, + ac .tl_set:N = \l_ltximg_meta_anglecolor_tl, + ac .initial:n = black, + sbc .tl_set:N = \l_ltximg_meta_brackcolor_tl, + sbc .initial:n = black, + cbc .tl_set:N = \l_ltximg_meta_bracecolor_tl, + cbc .initial:n = black, +} +%^^A internal commands +\cs_new_protected:Npn \ltximg_meta_generic:Nnn #1 #2 #3 +{ + \group_begin: + \keys_set:nn { ltximg/meta } { #2 } + \color{ \l_ltximg_meta_color_tl } + \l_ltximg_meta_font_tl + #1 { #3 } % #1 is \ltximg_meta:n, \ltximg_marg:n or \ltximg_oarg:n + \group_end: +} +\cs_new_protected:Npn \ltximg_meta:n #1 +{ + \ltximg_meta_angle:n { \textlangle } + \ltximg_meta_meta:n { #1 } + \ltximg_meta_angle:n { \textrangle } +} +\cs_new_protected:Npn \ltximg_marg:n #1 +{ + \ltximg_meta_brace:n { \textbraceleft } + \ltximg_meta:n { #1 } + \ltximg_meta_brace:n { \textbraceright } +} +\cs_new_protected:Npn \ltximg_oarg:n #1 +{ + \ltximg_meta_brack:n { [ } + \ltximg_meta:n { #1 } + \ltximg_meta_brack:n { ] } +} +\cs_new_protected:Npn \ltximg_meta_meta:n #1 +{ + \textnormal{\textit{#1}} +} +\cs_new_protected:Npn \ltximg_meta_angle:n #1 +{ + \group_begin: + \fontfamily{cmr}\selectfont + \textcolor{\l_ltximg_meta_anglecolor_tl}{#1} + \group_end: +} +\cs_new_protected:Npn \ltximg_meta_brace:n #1 +{ + \group_begin: + \color{\l_ltximg_meta_bracecolor_tl} + #1 + \group_end: +} +\cs_new_protected:Npn \ltximg_meta_brack:n #1 +{ + \textcolor{\l_ltximg_meta_brackcolor_tl}{#1} +} +\ExplSyntaxOff + +% \prgname{sm} : #1 index compiler, #2 index programs: +\DeclareDocumentCommand\prgname{sm}{% + \IfBooleanTF{#1} + { + \textcolor{ForestGreen}{\ttfamily\bfseries{#2}}\xspace% + \SortIndex{compiler}{Compiler>\small\textsf{#2}}% + } + { + \textcolor{ForestGreen}{\ttfamily\bfseries{#2}}\xspace% + \SortIndex{programs}{Programs>\small\textsf{#2}}% + } +}% + +% \prgopt{sm} : #1 compiler opt, #2 program opt: +\DeclareDocumentCommand\prgopt{sm}{% + \IfBooleanTF{#1} + { + \textcolor{gray}{\ttfamily\bfseries{-{}#2}}%\xspace% + \SortIndex{compiler options}{Compiler options>\small\texttt{-{}#2}}% + } + { + \mbox{\texttt{-{}#2}}% + \SortIndex{#2}{\texttt{-{}#2} (program option)}% + } +} + +% \scriptname*{m} +\DeclareDocumentCommand\scriptname{m}{% + \textcolor{ForestGreen}{\ttfamily\bfseries{#1}}\xspace + \SortIndex{scripts}{Scripts>\textsf{#1}}% +}% + +% \scriptopt{m} +\DeclareDocumentCommand\scriptopt{m}{% + \mbox{\texttt{#1}}\xspace% + \SortIndex{script option}{Script options>\small\textsf{#1}}% +} + +% \pkgname{m} +\DeclareDocumentCommand\pkgname{m}{% + \textsf{\textcolor{SlateBlue}{#1}}% + \SortIndex{packages}{Packages>\textsf{#1}}% + %\SortIndex{#1}{\textsf{#1} (package)}% +}% + +% \pkgopt{m} +\DeclareDocumentCommand\pkgopt{m}{% + \textsf{\textcolor{Orange}{#1}}% + \SortIndex{package options}{Package options>\textsf{#1}}% + \SortIndex{#1}{\textsf{#1} (package option)}% +}% + +% \env{sm}, #1 not used now +\DeclareDocumentCommand\env{sm}{ + \textcolor{optcolor}{\sffamily{#2}}% + \SortIndex{environment}{Environments>\small\textsf{#2}}% +} + +% \ics{sm}, #1 not used now +\DeclareDocumentCommand\ics{sm}{ + \textcolor{optcolor}{\ttfamily{\textbackslash#2}}% + \SortIndex{#2}{\textsf{\small\textbackslash#2}} +} + +% file extention +\DeclareDocumentCommand\fext{m}{% + \mbox{\textcolor{optcolor}{\ttfamily\bfseries{.#1}}\xspace}% + \SortIndex{files extention}{File extentions (input)>\small\textsf{.#1}}% +} + +% image format/extention +\DeclareDocumentCommand\iext{m}{% + \textcolor{optcolor}{\ttfamily\bfseries{#1}}% + \SortIndex{Image format}{Image formats>\small\textsf{#1}}% +} + +% \DescribeIF{m}, #1 image format +\newsavebox{\marginIF} +\NewDocumentCommand\DescribeIF{m}{% +\begin{lrbox}{\marginIF}% + \begin{minipage}[t]{\marginparwidth}% + \raggedleft + \iext{#1} + \end{minipage}% +\end{lrbox}% + \leavevmode% + \marginpar{\usebox{\marginIF}}% + \ignorespaces% +}% + +% \sysydir{m} +\DeclareDocumentCommand\sysdir{m}{% + \mbox{\textcolor{NavyBlue}{\ttfamily{/#1}}}% +} + +% \sysfile{m} ...only for color in some examples +\DeclareDocumentCommand\sysfile{m}{% + \mbox{\textcolor{gray}{\ttfamily{#1}}}\xspace% +} + +% \OSsystem{m} ...only for color in some examples +\DeclareDocumentCommand\OSsystem{m}{% + \mbox{\textcolor{NavyBlue}{\ttfamily\bfseries{#1}}}% + \SortIndex{Operating system}{Operating system>\small\textsf{#1}}% +} + +% \cmdopt[short]{long} +\NewDocumentCommand\cmdopt{om}{% + \IfNoValueTF{#1}% + {\textcolor{optcolor}{\ttfamily\bfseries{-\/-#2}}\xspace}% + {\textcolor{optcolor}{\ttfamily\bfseries{-{}#1}}, \textcolor{optcolor}{\ttfamily\bfseries{-\/-#2}}\xspace}% +\SortIndex{options}{\textsf{\myscript}\ options in command line>\small\texttt{-\/-#2}}% +} + +% \myenv{environ} +\DeclareDocumentCommand\myenv{m}{% +\moveright 0.0pt \hbox{% + \begin{minipage}[t]{\marginparwidth}% + \raggedleft\ttfamily%\small% + {\textcolor{gray}{\textbackslash begin\{}}{\bfseries\textcolor{optcolor}{#1}}\textcolor{gray}{\}}\par% + \meta[ac=gray,cf=gray]{env content}\par% + {\textcolor{gray}{\textbackslash end\{}}{\bfseries\textcolor{optcolor}{#1}}\textcolor{gray}{\}}% + \end{minipage}% + } % close hbox +\SortIndex{Environment}{Environments suport by default>\small\textsf{#1}}% +}% + +% \mytag{dtxtag} +\DeclareDocumentCommand\mytag{m}{% +\moveright 0.0pt \hbox{% + \begin{minipage}[t]{\marginparwidth}% + \raggedleft\ttfamily%\small% + \textcolor{gray}{\%<*}{\bfseries\textcolor{optcolor}{#1}}\textcolor{gray}{>}\par% + \meta[ac=gray,cf=gray]{content}\par% + \textcolor{gray}{\%}% + \end{minipage}% + } % close hbox +\SortIndex{docstrip}{Docstrip tag>\textsf{#1}}% +}% + +% \DescribeTE{sm}, #1 tag, #2 env +\newsavebox{\marginenvtag} +\NewDocumentCommand\DescribeTE{sm}{% +\begin{lrbox}{\marginenvtag}% + \begin{minipage}[t]{\marginparwidth}% + \raggedleft + \IfBooleanTF{#1}{\mytag{#2}}{\myenv{#2}} + \end{minipage}% +\end{lrbox}% + \leavevmode% + \marginpar{\usebox{\marginenvtag}}% + \ignorespaces% +}% + +% DescribeOptFile*{options}{example}[!] +\newsavebox{\optinfile} +\NewDocumentCommand\DescribeOptFile{s m m O{\hphantom{!}}}{ +\begin{lrbox}{\optinfile}% + \begin{minipage}[t]{\marginparwidth}% + \raggedleft\ttfamily\bfseries% + \textcolor{optcolor}{\%{#4}\myscript\hspace*{1.5pt}}% + \end{minipage}% +\end{lrbox}% +\leavevmode% +\marginpar{\usebox{\optinfile}}% +\lapbox[0pt]{-0.85\marginparsep}{\textcolor{red}{\texttt{:}}}% +\textcolor{optcolor}{\bfseries\texttt{{#2}}}% +\textcolor{red}{\hspace*{2.5pt}\texttt{:}} +\hspace*{-1pt}\marg[cbc=optcolor,ac=gray,cf=gray]{#3} +\vspace*{2pt}\par% +\IfNoValueTF{#1} +{}%% +{% +\SortIndex{options}{\textsf{\myscript}\ options in input file>\small\texttt{#2}}% +}% +} + +% \DescribeCmd[...]{...}{...}{...}, need changue to \DescribeOptCmd +\newsavebox{\optcmdline} +\NewDocumentCommand\DescribeCmd{ommm}{ +\begin{lrbox}{\optcmdline}% + \begin{minipage}[t]{\marginparwidth}% + \ttfamily\bfseries\raggedleft% + \IfNoValueTF{#1} + {\textcolor{optcolor}{-\/-#2}} + {\textcolor{optcolor}{-{#1}}\textcolor{gray}{,} \textcolor{optcolor}{-\/-#2}}% + \end{minipage}% +\SortIndex{options}{\textsf{\myscript}\ options in command line>\small\texttt{-\/-#2}}% +\end{lrbox}% + \leavevmode% + \marginpar{\usebox{\optcmdline}}% + \ignorespaces + \meta[ac=gray,cf=gray]{\textnormal{\sffamily{#3}}} + \hfill\textcolor{gray}{\textsf{(default: {#4})}}% + \vspace*{2pt}\par% +} + +% Create a language for documentation +\lstdefinelanguage{ltximg-doc}{ + texcsstyle=*,% + escapechar=`,% + showstringspaces=false,% + extendedchars=true, % + stringstyle = {\color{red}},% +% comments + morecomment=[l]{\%},% + commentstyle=\itshape\color{lightgray},% +% Important words 1 + keywordstyle=[1]{\bfseries\color{NavyBlue}},% + keywords=[1]{AtBeginDocument,begin,end,documentclass,BEGIN,END},% +% Other words 2 + keywordstyle=[2]{\color{blue!75}},% + keywords=[2]{usepackage,graphicspath,RequirePackage,renewcommand,% + PreviewBbAdjust,usetikzlibrary,tikzexternalize,psset,tikzset,PrependGraphicsExtensions,% + DefineShortVerb,lstMakeShortInline,MakeSpecialShortVerb,UndefineShortVerb},% +% Other words 3 + keywordstyle=[3]{\color{optcolor!85}},% + keywords=[3]{document,graphicx,preview,active,tightpage,article,grfext,description,filecontents,% + external,tikz,clean,pst,tkz,eps,pdf,xetex,latex,luatex,dvips,png,srcenv,noprew,imgdir,prefix,output},% +% Reserved words 4(inputfile options) + keywordstyle=[4]{\bfseries\color{optcolor}},% + keywords=[4]{ltximg,noltximg,remove,options,pspicture,endpspicture,% + PSTexample,pgfpicture, endpgfpicture, tikzpicture, endtikzpicture, % + psgraph, endpsgraph,nopreview,postscript, arara,extrenv,deltenv,skipenv},% +% Reserved in orange + keywordstyle=[5]{\color{OrangeRed}},% + keywords=[5]{images,includegraphics,env,file-out,pics,doc},% +% Reserved in orange + keywordstyle=[6]{\color{red}},% + keywords=[6]{verb},% +}[keywords,tex,comments,strings]% end languaje + +% \begin{examplecode}[optlst]...\end{examplecode} +\lstnewenvironment{examplecode}[1][]{% +\lstset{ + language=ltximg-doc,% + stringstyle = {\color{red}},% + basicstyle=\ttfamily\small,% + numbersep=1em,% + numberstyle=\tiny\color{lightgray}\noaccsupp,% +% literateee +literate=*{\{}{{\bfseries\textcolor{gray}{\{}}}{1} + {\}}{{\bfseries\textcolor{gray}{\}}}}{1} + {[}{{\bfseries\textcolor{optcolor}{[}}}{1} + {]}{{\bfseries\textcolor{optcolor}{]}}}{1} + {*}{{\bfseries\textcolor{red}{*}}}{1} + {:}{{\textcolor{red}{:}}}{1} + {,}{{\textcolor{gray}{,}}}{1} + {=}{{\textcolor{gray}{=}}}{1} + {/}{{\textcolor{gray}{/}}}{1} + {\%\ ltximg}{{\textcolor{gray}{\%}\space\bfseries\textcolor{optcolor}{ltximg}}}{8} + {\%\ arara}{{\textcolor{gray}{\%}\space\bfseries\textcolor{optcolor}{arara}}}{7} + {\{arara}{{\textcolor{gray}{\{arara}}}{6} + {\%<*remove>}{{\bfseries\textcolor{gray}{\%<*remove>}}}{10} + {\%}{{\bfseries\textcolor{gray}{\%}}}{10} + {\%<*ltximg>}{{\bfseries\textcolor{gray}{\%<*ltximg>}}}{10} + {\%}{{\bfseries\textcolor{gray}{\%}}}{10} + {\%<*noltximg>}{{\bfseries\textcolor{gray}{\%<*noltximg>}}}{12} + {\%}{{\bfseries\textcolor{gray}{\%}}}{12},% + #1,% + }% close lstset +}% +{}% close examplecode + +% \begin{examplecmd}...\end{examplecmd} +\lstnewenvironment{examplecmd}{% +\lstset{ + language=ltximg-doc,% + basicstyle=\ttfamily\small,% + frame=single,% + rulecolor=\color{gray!50},% + framesep=\fboxsep,% + framerule=\fboxrule,% + xleftmargin=\dimexpr\fboxsep+\fboxrule\relax,% + xrightmargin=\dimexpr\fboxsep+\fboxrule\relax,% +% Reserved words (cmd line options) + classoffset=7,% + keywordstyle=\bfseries\color{optcolor},% + morekeywords={ltximg},% +% % Reserved words (cmd line options) + classoffset=8,% + keywordstyle={\bfseries\color{ForestGreen}},% + morekeywords={gs,pdftoppm,pdftocairo,pdftops},% +% Only for command line options + classoffset=5,% + keywordstyle=\color{blue},% + keywords={user,machine},% +% literateee +literate=*{[}{{\textcolor{darkgray}{[}}}{1} + {]}{{\textcolor{darkgray}{]}}}{1} + {@}{{\textcolor{blue}{@}}}{1} + {\$}{{\textcolor{blue}{\$}}}{1} + {:}{{\textcolor{blue}{:}}}{1} + {§}{{\textcolor{red}{\$}}}{1} + {"}{{\textcolor{red}{\textquotedbl}}}{1} + {~}{{\textcolor{blue}{\bfseries\textasciitilde}}}{1}% + }% close lstset {~} +}% +{}% close examplecmd + +% \lstinline[style=inline]|...| +\lstdefinestyle{inline} +{ + language=ltximg-doc,% + basicstyle=\ttfamily\color{gray},% +% literateee +literate=*{\%}{{\bfseries\textcolor{gray}{\%}}}{1} +} + +% set default style +\lstset{style=inline} + +% email https://tex.stackexchange.com/a/663 +\catcode`\_=11\relax% +\newcommand\email[1]{\_email #1\q_nil}% +\def\_email#1@#2\q_nil{% + \href{mailto:#1@#2}{{\emailfont #1\emailampersat #2}}% +}% +\newcommand\emailfont{\sffamily}% +\newcommand\emailampersat{{\color{NavyBlue}\footnotesize@}}% +\catcode`\_=8\relax% % + +% Table of contents, need change font style +\def\rulecolor{\color{NavyBlue}} +\tocsetup{% + title=Contents\quad{\rulecolor\leaders\vrule height3.4pt depth-3pt\hfill\null}, + title/after= \vspace{3pt}, + title/font= \sffamily\bfseries\Large,% + title/top=10pt,% + title/bottom=0pt,% + twocolumns, + section/skip=4pt plus2pt minus2pt,% + subsection/skip=0pt plus2pt minus2pt, + section/leaders,section/dotsep,% + after=\vspace{-3pt}\noindent{\rulecolor\hrule height3.4pt depth-3pt\relax}, +} + +\begin{document} + + +\title{% + \textffm{latex environments}\\[3pt]% + \scalebox{3.4}{\LTXimg}\\[2pt]% + \textls[150]{\textffm{to image format}}\\% + \Large + v\fileversion{} --- \filedate\thanks{% + This file describes a documentation for version \fileversion, last revised \filedate.}\\[25pt]% + \author{% + \large% + \raisebox{-1pt}{\textcopyright}{}2013--2018 by Pablo González L% + \thanks{E-mail:<\email{pablgonz@yahoo.com}>}% + }% +\small +\textsc{ctan}: \url{http://www.ctan.org/pkg/ltximg}\\ +\textsc{git}: \url{https://github.com/pablgonz/ltximg} +\vspace*{-2cm} +}% +\date{} +\maketitle + +\begin{abstract} +\ltximg is a \prgname{perl} \emph{script} that automates the process of extracting and +converting environments provided by \pkgname{tikz}, \pkgname{pstricks} and +other packages from input file to image formats in individual files using \prgname{ghostscript} +and \prgname{poppler-utils}. Generates a file with only extracted environments and another with environments +converted to \ics{includegraphics}. +\end{abstract} + +\tableofcontents +\setlength{\parskip}{3pt} + +\section{Motivation} +The original idea was to extend the functionality of the \scriptname{pst2pdf} +script (only for \env{pspicture} and \env{postscript}) to work with \env{tikzpicture} +and other environments. + +The \pkgname{tikz} package allows to externalize the environments, but, the idea was to be +able to extend this to any type of environment covering three central points: + +\begin{enumerate}[font=\small, noitemsep,leftmargin=*] +\item Generate separate files for environments and converted into images. +\item Generate a file with only the extracted environments. +\item Generate a file replacing the environments by \ics{includegraphics}. +\end{enumerate} + +From the side of \TeX{} there are some packages that cover several of these +points such as the \pkgname{preview}, \pkgname{xcomment}, \pkgname{external} and \pkgname{cachepic} packages among others, +but none covered all points. + +In the network there are some solutions in \texttt{bash} that were able to +extract and convert environments, but in general they presented problems when the document +contained \emph{verbatim style} code or were only available for \OSsystem{Linux}. + +Analysed the situation the best thing was to create a new \emph{script} that was able +to cover the three points and was multi platform, the union of all these ideas is +born \ltximg. Finding the correct \emph{regular expressions} and writing \emph{documentation} +would be the great mission (which does not end yet). + +\thispagestyle{plain} +\newpage +\pagestyle{myheader} +\section{Required Software}\label{sec:software} + +For the complete operation of \ltximg{} you need to have a modern \hologo{TeX} +distribution such as \hologo{TeX}Live 2017 or \hologo{MiKTeX} 2.9, have a version equal to or +greater than \liningnums{5.22} of \prgname{perl}, a version equal to or greater than \liningnums{9.19} of +\prgname{ghostscript} and have a version equal to or greater than \liningnums{0.52} of \prgname{poppler-utils}. + +The distribution of \hologo{TeX}Live 2017 for \OSsystem{Windows} includes \ltximg{} and all +requirements, \hologo{MiKTeX} users must install the appropriate software for full operation. + +The script has been tested on \OSsystem{Windows} (version 10) and \OSsystem{Linux} (fedora 27) in x64 architecture using +\prgname{ghostscript} \liningnums{v9.20}, \prgname{poppler-utils} \liningnums{v0.52} to \liningnums{v0.60} and +\prgname{perl} from \liningnums{v5.22} to \liningnums{v5.26}. + +\section{How it works}\label{sec:howtowork} + +It is important to have a general idea of how the \emph{extraction and conversion} +process works and the requirements that must be fulfilled so that everything +works correctly, for this we must be clear about some concepts related to how to +work with the \meta{verbatim content}, the \meta{input file}, the \meta{output file} and the +\meta{steps process}. + +\subsection{The input file}\label{sec:inputfile} + +The \meta{input file} must comply with certain characteristics in +order to be processed, the content at the beginning and at the end of the \meta{input file} +is treated in a special way, before \lstinline|\documentclass| can only be commented lines and +after \lstinline|\end{document}| can go any type of content, internally +will split the \meta{input file} at this points. + +If the \meta{input file} contains files using \ics{input} or \ics{include} these +will not be processed, from the side of the \emph{script} they only represent +lines within the file, if you want them to be processed it is better to use the +\scriptname{latexpand} first and then process the file. + +Like \ics{input} or \ics{include}, blank lines, vertical spaces and tab +characters are treated literally, for the \emph{script} the \meta{input file} is just a set of +characters, as if it was a simple text file. It is advisable to format the source code \meta{input file} +using utilities such as lines such as \prgname{chktex} and \scriptname{latexindent}, especially if you want to +extract the source code of the environments. + +An example of the \meta{input file}: + +\begin{examplecode} +% some commented lines at begin document +\documentclass{article} +\usepackage{tikz} +\begin{document} +Some text +\begin{tikzpicture} +Some code +\end{tikzpicture} +Always use \verb|\begin{tikzpicture}| +and \verb|\end{tikzpicture}| to open +and close environment +\begin{tikzpicture} +Some code +\end{tikzpicture} +Some text +\end{document} +% some lines after end document +\end{examplecode} + +\subsection{Verbatim contents}\label{sec:verbatim} + +One of the greatest capabilities of \ltximg{} script is to skip the complications +that \emph{verbatim style} content produces with the extraction of environments. +In order to skip the complications, the verbatim content is classified into +three types: + +\begin{itemize} + \item Verbatim in line + \item Verbatim standard + \item Verbatim write +\end{itemize} + +Each of these classifications works differently within the creation and +extraction process using different regular expressions for it. +\newpage + +\subsubsection{Verbatim in line}\label{sec:verbatim:inline} + +The small pieces of code written in the same line using a verbatim command are +considered \meta{verbatim in line}, such as \lstinline+\verb||+. Most verbatim commands +provide by packages \pkgname{minted}, \pkgname{fancyvrb} and \pkgname{listings} have +been tested and are fully supported. They are automatically detected the verbatim command generates +by \ics{newmint} and \ics{newmintinline} and the following command list: + +\begin{multicols}{3} +\begin{itemize}[font=\sffamily\small, noitemsep,leftmargin=*] +\small +\item \ics{mint} +\item \ics{spverb} +\item \ics{qverb} +\item \ics{fverb} +\item \ics{verb} +\item \ics{Verb} +\item \ics{lstinline} +\item \ics{pyginline} +\item \ics{pygment} +\item \ics{tcboxverb} +\item \ics{mintinline} +\end{itemize} +\end{multicols} + +Some packages define abbreviated versions for verbatim commands as \ics{DefineShortVerb}, \ics{lstMakeShortInline} +and \ics{MakeSpecialShortVerb}, will be detected automatically if are declared explicitly in \meta{input file}. + +The following consideration should be kept in mind for some packages that use +abbreviations for verbatim commands, such as \pkgname{shortvrb} or \pkgname{doc} +for example in which there is no explicit command in the document by means of +which the abbreviated form can be detected, for automatic detection need to find +\ics{DefineShortVerb} explicitly to process it correctly. +The solution is quite simple, just add in \meta{input file}: + +\begin{examplecode} +\UndefineShortVerb{\|} +\DefineShortVerb{\|} +\end{examplecode} + +depending on the package you are using. If your verbatim command is not supported +by default or can not detect, use the options described in \ref{sec:optline} and \ref{sec:optfile}. + +\subsubsection{Verbatim standard}\label{sec:verbatim:std} + +These are the classic environments for writing code are considered \meta{verbatim standard}, +such as \env{verbatim} and \env{lstlisting} environments. The following list is considered +as \meta{verbatim standard} environments: + +\begin{multicols}{4} +\begin{itemize}[font=\sffamily\small, noitemsep,leftmargin=*] +\sffamily\small +\item Example +\item CenterExample +\item SideBySideExample +\item PCenterExample +\item PSideBySideExample +\item verbatim +\item Verbatim +\item BVerbatim +\item LVerbatim +\item SaveVerbatim +\item PSTcode +\item LTXexample +\item tcblisting +\item spverbatim +\item minted +\item listing +\item lstlisting +\item alltt +\item comment +\item chklisting +\item verbatimtab +\item listingcont +\item boxedverbatim +\item demo +\item sourcecode +\item xcomment +\item pygmented +\item pyglist +\item program +\item programl +\item programL +\item programs +\item programf +\item programsc +\item programt +\end{itemize} +\end{multicols} + +They are automatically detected \meta{verbatim standard} environments generates by commands: + +\begin{multicols}{2} +\begin{itemize}[font=\sffamily\small, noitemsep,leftmargin=*] +\small +\item \ics{DefineVerbatimEnvironment} +\item \ics{NewListingEnvironment} +\item \ics{DeclareTCBListing} +\item \ics{ProvideTCBListing} +\item \ics{lstnewenvironment} +\item \ics{newtabverbatim} +\item \ics{specialcomment} +\item \ics{includecomment} +\item \ics{newtcblisting} +\item \ics{NewTCBListing} +\item \ics{newverbatim} +\item \ics{NewProgram} +\item \ics{newminted} +\end{itemize} +\end{multicols} + +If any of the \meta{verbatim standard} environments is not supported by default or can +not detected, you can use the options described in \ref{sec:optline} and \ref{sec:optfile}. + +\subsubsection{Verbatim write}\label{sec:verbatim:write} + +Some environments have the ability to write external files directly, these environments are considered +\meta{verbatim write}, such as \env{filecontents} or \env{VerbatimOut} environments. The following list +is considered as \meta{verbatim write} environments: + +\begin{multicols}{3} +\begin{itemize}[font=\sffamily\small, noitemsep,leftmargin=*] +\small +\item filecontents +\item tcboutputlisting +\item tcbexternal +\item extcolorbox +\item extikzpicture +\item VerbatimOut +\item verbatimwrite +\item filecontentsdef +\item filecontentshere +\end{itemize} +\end{multicols} + +They are automatically detected \meta{verbatim write} environments generates by commands: + +\begin{multicols}{2} +\begin{itemize}[font=\sffamily\small, noitemsep,leftmargin=*] +\small +\item \ics{renewtcbexternalizetcolorbox} +\item \ics{renewtcbexternalizeenvironment} +\item \ics{newtcbexternalizeenvironment} +\item \ics{newtcbexternalizetcolorbox} +\end{itemize} +\end{multicols} + +If any of the \meta{verbatim write} environments is not supported by default or can +not detected, you can use the options described in \ref{sec:optline} and \ref{sec:optfile}. + +\subsection{Steps process}\label{sec:steps:process} + +For creation of the image formats, extraction of code and creation of an +output file, \ltximg{} need a various steps. Let's assume that the \meta{input file} is \sysfile{test.tex}, +\meta{output file} is \sysfile{test-out}, the working directory are \sysdir{workdir}, the directory +for images are \sysdir{workdir/images} and the user's temporary directory is \sysdir{tmp} and we +want to generate images in \iext{pdf} format together with the source codes of the environments. + +\begin{description}[font=\sffamily\small, leftmargin=0em,style=nextline] +\item[Comment and ignore] +The first step is read and validated \oarg[type=rm,cf=gray,sbc=optcolor,ac=gray]{options} from the command +line and \sysfile{test.tex}, verifying that \sysfile{test.tex}, \sysfile{test-out} and the +directory \sysdir{images} are in \sysdir{workdir}, create the directory \sysdir{workdir/images} if it does +not exist and a temporary directory \sysdir{tmp/hG45uVklv9}. The entire file \sysfile{test.tex} is loaded +in memory and proceeds (in general terms) as follows: + +\begin{quotation} +Search the words \lstinline|\begin{| and \lstinline|\end{| in verbatim standard, verbatim write, verbatim in line and +commented lines, if it finds them, converts to \lstinline|\BEGIN{| and \lstinline|\END{|, then places all code to +extract inside the \lstinline|\begin{preview}| \ldots \lstinline|\end{preview}|. +\end{quotation} + +At this point all the code you want to extract is inside \lstinline|\begin{preview}| \ldots \lstinline|\end{preview}| +and the files \sysfile{test-fig-1.tex}, \sysfile{test-fig-2.tex}, \ldots{} are generated and saved in \sysdir{images}. + +\item[Create random file] +In the second step, with the file already loaded in memory, creating a temporary file with a +random number (1981 for example) and proceed in two ways according to the \oarg[type=rm,cf=gray,sbc=optcolor,ac=gray]{options} +passed to the script: + +\begin{enumerate} +\item If script is call \emph{whitout} \cmdopt[n]{noprew} options, adds the +following lines to the beginning of the \sysfile{test.tex} (in memory): + +\begin{examplecode} +\AtBeginDocument{% +\RequirePackage[active,tightpage]{preview} +\renewcommand\PreviewBbAdjust{-60pt -60pt 60pt 60pt}}% +% rest of input file +\end{examplecode} +And save in a temporary file \sysfile{test-fig-1981.tex} in \sysdir{workdir}. + +\item If script is call \emph{whit} \cmdopt[n]{noprew} options, all code to extract +its put inside the \env{preview} environment. The \lstinline|\begin{preview}|\ldots \lstinline|\end{preview}| +lines are only used as delimiters for extracting the content \emph{without} using the package \pkgname{preview}. + +Creating a temporary file \sysfile{test-fig-1981.tex} in \sysdir{workdir} +whit the same preamble of \sysfile{test.tex} but the body only contains code that you want to extract. +\end{enumerate} + +\item[Generate image formats] +In the third step the script run: +\begin{examplecmd} +[user@machine ~:]§`\small\meta[type=tt,cf=ForestGreen,ac=ForestGreen]{compiler}` -recorder -shell-escape `\small\sysfile{test-fig-1981.tex}` +\end{examplecmd} +generating the file \sysfile{test-fig-1981.pdf} whit all code extracted, move \sysfile{test-fig-1981.pdf} +to \sysdir{tmp/hG45uVklv9}, separate in individual files \sysfile{test-fig-1.pdf}, \sysfile{test-fig-2.pdf}, \ldots{} +and copy to \sysdir{workdir/images/}. The file \sysfile{test-fig-1981.tex} is moved to the \sysdir{workdir/images/} +and rename to \sysfile{test-fig-all.tex}. + +Note the options passed to \meta[type=tt,cf=ForestGreen,ac=ForestGreen]{compiler} does not include \prgopt*{output-directory} +(it is not supported) and always use \prgopt*{recorder} \prgopt*{shell-escape} you must keep this in mind if you use \prgname{arara}. + +\item[Create output file] +In the fourth step the script creates the output file \sysfile{test-out.tex} converting all extracted code to +\ics{includegraphics} and adding the following lines at end of preamble: + +\begin{examplecode} +\usepackage{graphicx} +\graphicspath{{images/}} +\usepackage{grfext} +\PrependGraphicsExtensions*{.pdf} +\end{examplecode} + +If the packages \pkgname{graphicx} and \pkgname{grfext} are already loaded and the command \ics{graphicspath} +is found in the input file were detected automatically and only the changes will be added then proceed to run: +\begin{examplecmd} +[user@machine ~:]§`\small\meta[type=tt,cf=ForestGreen,ac=ForestGreen]{compiler}` -recorder -shell-escape `\small\sysfile{test-out.tex}` +\end{examplecmd} +generating the file \sysfile{test-out.pdf}. +\end{description} +Now the script read the files \sysfile{test-fig-1981.fls} and \sysfile{test-out.fls}, extract the information from the +temporary files generated in the process and then delete them together with the directory \sysdir{tmp/hG45uVklv9}. +An example for input and output file: + +\begin{minipage}[c]{0.5\textwidth} +\begin{examplecode} +\documentclass{article} +\usepackage{tikz} +\begin{document} +Some text +\begin{tikzpicture} +Some code +\end{tikzpicture} +Always use \verb|\begin{tikzpicture}| +and \verb|\end{tikzpicture}| to open +and close environment +\begin{tikzpicture} +some code +\end{tikzpicture} +Some text +\end{document} +\end{examplecode} +\begin{flushleft} +\sysfile{test.tex} +\end{flushleft} +\end{minipage} +\begin{minipage}[c]{0.5\textwidth} +\begin{examplecode} +\documentclass{article} +\usepackage{tikz} +\usepackage{graphicx} +\graphicspath{{images/}} +\usepackage{grfext} +\PrependGraphicsExtensions*{.pdf} +\begin{document} +Some text +\includegraphics[scale=1]{test-fig-1} +Always use \verb|\begin{tikzpicture}| +and \verb|\end{tikzpicture}| to open +and close environment +\includegraphics[scale=1]{test-fig-2} +Some text +\end{document} +\end{examplecode} +\begin{flushleft} +\sysfile{test-out.tex} +\end{flushleft} +\end{minipage} +\newpage + +\section{Extract content}\label{sec:extract} +The script provides two ways to extract content from \meta{input file}, using \meta[type=rm,cf=optcolor,ac=gray]{environments} +and \meta[type=rm,cf=optcolor,ac=gray]{docstrip tags}. Some environment (including a starred \texttt{\small\bfseries\textcolor{red}{*}} version) +are supported by default and if the environments are nested, the outermost will be extracted. + +\subsection{Default environments} +\label{sec:extract:env} +\DescribeTE{preview} +Environment provide by \pkgname{preview} package. If \env{preview} environments +found in the input file will be extracted and converted these. Internally +converts all environments to extract in \env{preview} environments. +Is better comment this package in preamble unless the option \cmdopt[n]{noprew}{} is +used. + +\vspace{\baselineskip} + +\DescribeTE{pspicture} +Environment provide by \pkgname{pstricks} package. The plain +syntax \lstinline|\pspicture ... \endpspicture| its converted to +\lstinline|\begin{pspicture} ... \end{pspicture}|. +\vspace{\baselineskip} + +\DescribeTE{psgraph} +Environment provide by \pkgname{pst-plot} package. The plain syntax \lstinline|\psgraph ... \endpsgraph| +its converted to \lstinline|\begin{psgraph} ... \end{psgraph}|. + +\vspace{\baselineskip} + +\DescribeTE{postscript} +Environment provide by \pkgname{pst-pdf} and \pkgname{auto-pst-pdf} packages. +Since the \pkgname{pst-pdf} and \pkgname{auto-pst-pdf} packages internally use +the \pkgname{preview} package, is better comment this in preamble. + +\vspace{\baselineskip} + +\DescribeTE{tikzpicture} +Environment provide by \pkgname{tikz} package. The plain syntax \lstinline|\tikzpicture ... \tikzpicture| +its converted to \lstinline|\begin{tikzpicture} ... \end{tikzpicture}| +but no a short \lstinline|\tikz...;|. +\vspace{\baselineskip} + +\DescribeTE{pgfpicture} +Environment provide by \pkgname{pgf} package. Since the script uses a +\emph{recursive regular expression} to extract environments, no presents problems +if present \lstinline|pgfinterruptpicture|. +\vspace{\baselineskip} + +\DescribeTE{PSTexample} +Environment provide by \pkgname{pst-exa} packages. The script automatically detects the +\lstinline|\begin{PSTexample}| \lstinline|...\end{PSTexample}| +environments and processes them as separately compiled files. The user should have loaded the +package with the [\pkgopt{swpl}] or [\pkgopt{tcb}] option and run the script +using \cmdopt{latex}{} or \cmdopt{xetex}. + +If you need to extract more environments you can use one of the options described in \ref{sec:optline} or \ref{sec:optfile}. +\subsection{Extract whit docstrip tags} +\label{sec:extract:tag} +\DescribeTE*{ltximg} +All content included between \lstinline|%<*ltximg> ... %| is extracted. +The tags can not be nested and should be at the beginning of the line and in separate lines. + +\begin{examplecode} +% no space before open tag %<* +%<*ltximg> +code to extract +% +% no space before close tag % ... %| are ignored and no +extract. The start and closing of the tag must be at the beginning of the line. + +\begin{examplecode} +% no space before open tag %<* +%<*noltximg> +no extract this +% +% no space before close tag % ... %| are deleted in the \meta{output file}. The start and closing +of the tag must be at the beginning of the line. + +\begin{examplecode} +% no space before open tag %<* +%<*remove> +lines removed in output file +% +% no space before close tag % : {options: "-recorder"}| + +\DescribeCmd{xetex}{bolean}{off} +Using \prgname*{xelatex} compiler \meta{input file} and \meta{output file}. + +\DescribeCmd{latex}{bolean}{off} +Using \prgname*{latex}\texttt{\bfseries\guillemotright}\prgname*{dvips}\texttt{\bfseries\guillemotright}\scriptname{ps2pdf} +compiler in \meta{input file} and \prgname*{pdflatex} for \meta{output file}. + +\DescribeCmd{dvips}{bolean}{off} +Using \prgname*{latex}\texttt{\bfseries\guillemotright}\prgname*{dvips}\texttt{\bfseries\guillemotright}\scriptname{ps2pdf} +for compiler \meta{input file} and \meta{output file}. + +\DescribeCmd{dvipdf}{bolean}{off} +Using \prgname*{latex}\texttt{\bfseries\guillemotright}\prgname*{dvipdfmx} for compiler \meta{input file} and \meta{output file}. + +\DescribeCmd{luatex}{bolean}{off} +Using \prgname*{lualatex} for compiler \meta{input file} and \meta{output file}. + +\DescribeCmd{prefix}{string}{fig} +Add prefix append to each files created. + +\DescribeCmd{norun}{bolean}{off} +Run script, but no create images. This option is designed to debug the file and +when you only need to extract the code + +\DescribeCmd{nopdf}{bolean}{off} +Don't create a .\iext{pdf} image files. + +\DescribeCmd{nocrop}{bolean}{off} +Don't run \scriptname{pdfcrop} in image files. + +\DescribeCmd{clean}{doc\textbar pst\textbar tkz\textbar all\textbar off}{doc} +Removes specific content in \meta{output file}. Valid values for this option are: + +\begin{description}[font=\small\sffamily, nosep, noitemsep, leftmargin=*] +\item[doc] All content after \lstinline+\end{document}+ is removed. +\item[pst] All \lstinline|\psset{...}| and \pkgname{pstricks} package is removed. +\item[tkz] All \lstinline|\tikzset{...}| is removed. +\item[all] Activates doc, pst and tkz. +\item[off] Deactivate all. +\end{description} + +\newpage +\DescribeCmd{verbcmd}{command name}{myverb} +Set custom verbatim command \lstinline+\myverb||+. + +\DescribeCmd{extrenv}{list separate by comma}{empty} +List of environments to extract, need \texttt{-\/-} at end.\par + +\DescribeCmd{skipenv}{list separate by comma}{empty} + +List of environments that should not be extracted and that the script supports +by default, need \texttt{-\/-} at end.\par + +\DescribeCmd{verbenv}{list separate by comma}{empty} + +List of \meta{verbatim standard} environment support, need \texttt{-\/-} at end.\par + +\DescribeCmd{writenv}{list separate by comma}{empty} + +List of \meta{verbatim write} environment support, need \texttt{-\/-} at end.\par + +\DescribeCmd{deltenv}{list separate by comma}{empty} +List of environment deleted in \meta{output file}, need \texttt{-\/-} at end. + +\subsection{Options in input file}\label{sec:optfile} + +Many of the ideas in this section are inspired by the \prgname{arara} program (I adore it). +A very useful way to pass options to the script is to place them in commented +lines at the beginning of the file, very much in the style of \prgname{arara}. + +\DescribeOptFile*{\meta[ac=gray,cf=gray]{argument}}{option one, option two, option three, \ldots} +\DescribeOptFile*{\meta[ac=gray,cf=gray]{argument}}{option one, option two, option three, \ldots}[!] + +The vast majority of the options can be passed into the \meta{input file}. These +should be put at the beginning of the file in commented lines and everything must +be on the same line, the exclamation mark deactivates the option. Valid values for +\meta[ac=gray,cf=gray]{argument} are the following: + +\DescribeOptFile{options}{option one = value, option two = value, option three = value, \ldots} +This line is to indicate to the script which options need to process. + +\DescribeOptFile{extrenv}{environment one, environment two, environment three, \ldots} +This line is to indicate to the script which environments, not supported by +default, are extracted. + +\DescribeOptFile{skipenv}{environment one, environment two, environment three, \ldots} +This line is to indicate to the script which environments, of the ones +supported by default, should not be extracted. + +\DescribeOptFile{verbenv}{environment one, environment two, environment three, \ldots} +This line is to indicate to the script which environments, its considerate a \meta{verbatim standard}. + +\DescribeOptFile{writenv}{environment one, environment two, environment three, \ldots} +This line is to indicate to the script which environments its consider \meta{verbatim write}. + +\DescribeOptFile{deltenv}{environment one, environment two, environment three, \ldots} +This line is to indicate to the script which environments are deleted. + +If you are going to create an \meta{output file} and you do not want these lines to remain, it is better to +place them inside the \lstinline|%<*remove> ... %|. Like this: + +\begin{examplecode} +%<*remove> +% ltximg : options : {png,srcenv,xetex} +% ltximg : extrenv : {description} +% +\end{examplecode} +\newpage + +\section{Examples} \label{sec:examples} +\begin{examplecmd} +[user@machine ~:]§ ltximg --latex -s -o test-out test-in.ltx +\end{examplecmd} +Create a \sysdir{images} directory whit all extracted environments converted to image +formats (\iext{pdf}, \iext{svg}) in individual files, an \meta{output file} \sysfile{test-out.ltx} whit all supported environments +converted to \ics{includegraphics} and a single file \sysfile{test-in-fig-all.ltx} with only the extracted environments +using \prgname*{latex}\texttt{\bfseries\guillemotright}\prgname*{dvips}\texttt{\bfseries\guillemotright}\scriptname{ps2pdf} +and \pkgname{preview} package for \meta{input file} and \prgname*{pdflatex} for \meta{output file}. + +Adding the following lines to the beginning of the file \sysfile{file-in.tex}: +\begin{examplecode} +%<*remove> +% ltximg : options : {output = file-out, noprew, imgdir = pics, prefix = env, clean = doc} +% ltximg : skipenv : {tikzpicture} +% ltximg : deltenv : {filecontents} +% +\end{examplecode} +and run: +\begin{examplecmd} +[user@machine~:]§ ltximg file-in.tex +\end{examplecmd} +Create a \sysdir{pics} directory whit all extracted environments, except \env{tikzpicture}, converted to image +formats (\iext{pdf}) in individual files, an \meta{output file} \sysfile{file-out.tex} whit all extracted environments +converted to \ics{includegraphics} and environment \env{filecontents} removed, a single file \sysfile{test-in-env-all.ltx} +with only the extracted environments using \prgname*{pdflatex} and \pkgname{preview} package for \meta{input file} and \meta{output file}. + +\section{Change history}\label{sec:change:history} + +Some of the notable changes in the history of the \ltximg{} along with the +versions, both development (devp) and public (ctan). + +\setlist[itemize, 1]{label=\textendash, wide=0.5em, nosep, noitemsep, leftmargin=10pt} +% length for change history +\newlength\descrwidth +\settowidth{\descrwidth}{\textsf{v1.4.5, (ctan), 2013-01-23}} +\begin{description}[font=\small\sffamily, wide=0pt, style=multiline, leftmargin=\descrwidth, nosep, noitemsep] +\item [v1.5 (ctan), 2017-04-12] + \begin{itemize} + \item Use \texttt{GitHub} to control version + \item Rewrite and optimize most part of code and options + \item Change \texttt{pdf2svg} for \texttt{pdftocairo} + \item Complete support for \texttt{pst-exa} package + \item Escape characters in regex according to v5.4x.x + \end{itemize} +\item [v1.4 (devp), 2016-11-29] + \begin{itemize} + \item Remove and rewrite code for regex and system call + \item Append \texttt{arara} compiler, clean and comment code + \item Append \texttt{dvips} and \texttt{dvipdfm(x)} for creation images + \item Append \texttt{bmp}, \texttt{tiff} image format + \end{itemize} +\item [v1.3 (devp), 2016-08-14] + \begin{itemize} + \item Rewrite some part of code (norun, nocrop, clean) + \item Suport \texttt{minted} and \texttt{tcolorbox} package for verbatim + \item Escape some characters in regex according to v5.2x.x + \item All options read from command line and input file + \item Use \texttt{/tmp} dir for work process + \end{itemize} +\item [v1.2 (ctan), 2015-04-22] + \begin{itemize} + \item Remove unused modules + \item Add more image format + \item Fix regex + \end{itemize} +\item [v1.1 (ctan), 2015-04-21] + \begin{itemize} + \item Change \texttt{mogrify} to \texttt{gs} for image formats + \item Create output file + \item Rewrite source code and fix regex + \item Change format date to iso format + \end{itemize} +\item [v1.0 (ctan), 2013-12-01] + \begin{itemize} + \item First public release + \end{itemize} +\end{description} + +\newpage +\clearpage +\PrintIndex +\end{document} +% -- cgit v1.2.3