Debian Codegraph @

texmf-dist/doc/latex/cachepic/cachepic.tex

raw
1 % Copyright 2009 T.M. Trzeciak
2 %
3 % This work may be distributed and/or modified under the
4 % conditions of the LaTeX Project Public License, either version 1.3
5 % of this license or (at your option) any later version.
6 % The latest version of this license is in
7 % http://www.latex-project.org/lppl.txt
8 % and version 1.3 or later is part of all distributions of LaTeX
9 % version 2005/12/01 or later.
10 %
11 % This work has the LPPL maintenance status `maintained'.
12 %
13 % The Current Maintainer of this work is T.M. Trzeciak.
14 %
15 % This work consists of the files:
16 % README.TXT
17 % cachepic.tex
18 % cachepic.pdf (derived)
19 % cachepic.sty
20 % prcachepic.def
21 % cachepic.tlu
22 % cachepic.cmd
23
24
25 %\ProvidesFile{cachepic}[2009/09/23 v1.0 cachepic package]
26 \documentclass{ltxdoc}
27 \usepackage{booktabs}
28 \usepackage{verbatim}
29 \newcommand\mainfile{main file}
30 \newcommand\filename{file name}
31 \newcommand\texfrag{fragment}
32 \newcommand\option[1]{\textbf{#1}}
33 \newcommand{\figref}[2][\figurename~]{#1\ref{#2}}
34 \newcommand{\tabref}[2][\tablename~]{#1\ref{#2}}
35 \newcommand{\secref}[2][Section~]{#1\ref{#2}}
36 \newenvironment{displaytext}{\quote}{\endquote}
37 \setlength{\parindent}{0pt}
38 \setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
39
40 \begin{document}
41 %\GetFileInfo{cachepic}
42
43 \title{The \textsf{cachepic} package}
44 \author{Tomasz M. Trzeciak \\ \texttt{[email protected]}}
45 \date{September 23, 2009}
46 \maketitle
47
48 \section{Introduction}
49
50 It might be sometimes desirable to convert fragments of your document, e.g. drawings or diagrams, into external graphic files. Such a need may arise when you want to use some specialised package but your document have to compile on a system without said package.
51
52 The purpose of \textsf{cachepic} package is to simplify and automate conversion of document fragments into external \textsf{eps} or \textsf{pdf} file(s). The package consists of two parts: the \LaTeXe\ style implementing the document level interface and a command line tool (written in \textsf{Lua}) for generation of external graphics.
53
54 \section{Requirements}
55 \label{sec:Requirements}
56
57 The inclusion of already generated graphics requires only the |cachepic.sty| style file and two standard packages: \textsf{graphicx} (obviously) and \textsf{verbatim} (for its comment environment). Both should be present in every \LaTeX\ distribution.
58
59 The graphics generation step requires the full \textsf{cachepic} package, the \textsf{preview} package and a \textsf{Lua} interpreter to execute the conversion script. For Windows platform there is also a batch script wrapper provided for command line use.
60
61 \section{Document interface}
62 \label{sec:DocInterface}
63
64 The package is loaded with the usual |\usepackage{cachepic}|. Currently there are no package specific options available. There are two commands and one environment provided for marking-up document fragments intended for externalization as graphic files.
65
66 \DescribeMacro{\cachepic}
67 The main command of this package is |\cachepic|\marg{\filename}\marg{\texfrag}. It takes a balanced \LaTeX\ code \meta{\texfrag}, which is typeset and output to a file \meta{\filename} during the post-processing run as described in \secref{sec:CmdTool}.
68
69 \DescribeMacro{\cacheinput}
70 The second command, |\cacheinput|\marg{\filename}, is just a shorthand for |\cachepic|\marg{\filename}|{\input|\marg{\filename}|}|.
71
72 \DescribeEnv{cachepicture}
73 Finally, for longer stretches of code there is an environment analogue of the |\cachepic| command:
74
75 \begin{displaytext}
76 |\begin{cachepicture}|\marg{\filename}\\
77 \hspace*{1em}\meta{\texfrag}\\
78 |\end{cachepicture}|
79 \end{displaytext}
80
81 During normal document compilation each \meta{\texfrag} is typeset as usual unless there exists a file \mbox{\meta{\filename}|.eps|} (in \textsf{dvi} mode) or \mbox{\meta{\filename}|.pdf|} (in \textsf{pdf} mode). If such a file exists, it will be included (with the standard |\includegraphics| command) and it will be used in place of the corresponding \meta{\texfrag}.
82
83 \section{Graphics generation}
84 \label{sec:CmdTool}
85
86 \begin{table}
87 \centering
88 \caption[]{\label{tab:options}
89 Options of |cachepic| command line tool.}
90 \vspace{1ex}
91 \begin{tabular}{l p{0.6\linewidth}}
92 \toprule
93 \option{option} & description\\
94 \midrule
95 \option{pdf} & graphics will be output in
96 \textsc{(e)pdf} format; this is the
97 default option\\
98 \option{eps} & graphics will be output in
99 \textsc{eps} format\\
100 \option{all} & recreate all graphics, already
101 existing ones will be overwritten\\
102 \option{multi} & keep all graphics in a sigle file
103 \meta{\mainfile}|-cachepic.pdf|
104 rather then produce separate files
105 (but graphics in separate files take
106 precedence); this option cannot be
107 used together with |-eps|\\
108 \option{tight} & no 0.5\,bp margin around the
109 graphic\\
110 \option{notex} & don't do any typesetting, only
111 graphic postprocessing; the typesetting has
112 to be done separately and requires the
113 \textsf{preview} package with at least
114 the |active| and |cachepic| options\\
115 \option{nopic} & generate no graphics, only
116 \mbox{\meta{\mainfile}|.cachepic|} file\\
117 \option{help,h,?} & display help message\\
118 \bottomrule
119 \end{tabular}
120 \end{table}
121
122 Graphics files are produced by running a command line tool called (unsurprisingly) |cachepic|. This tool automates the whole process of graphic generation. It can be called from the command line (or through appropriately configured \TeX\ editor) as follows:
123
124 \begin{displaytext}
125 |cachepic [options] |\meta{\mainfile}
126 \end{displaytext}
127
128 \noindent All available options are gathered in \tabref{tab:options}. Options start with ``|-|'' or ``|--|'' and can be passed in any order.
129
130 Apart from graphic files there is also an auxiliary \mbox{\meta{\mainfile}|.cachepic|} file created. It contains additional information used for graphics inclusion such as the page number (used only in \textsc{pdf} mode with multi-graphics file), margins and the depth of the graphics box. This file is not strictly required but without it some features are not available as explained below.
131
132 As mentioned in \secref{sec:Requirements}, the \textsf{preview} package is required for graphics generation but it should not be specified with options in the document preamble or this will likely lead to option clash. To use this package together with \textsf{cachepic}, pass |cachepic| option to the \textsf{preview} package and compile the document separately. Then run the |cachepic| tool with |-notex| option.
133
134 Once all the graphics are generated, only the style file |cachepic.sty| is needed to compile the document. If you want to avoid using even this file, you can add the following definitions the document preamble:
135
136 \begin{displaytext}
137 \begin{verbatim}
138 \newcommand\cachepic[2]{\includegraphics{#1}}
139 \newcommand\cacheinput[1]{\includegraphics{#1}}
140 \newenvironment{cachepicture}[1]{%
141 \includegraphics{#1}\comment}{\endcomment}
142 \end{verbatim}
143 \end{displaytext}
144
145 However, since the above definitions don't use the additional information in the \mbox{\meta{\mainfile}|.cachepic|} file, this comes with some limitations. Firstly, information about the graphic's depth, i.e. how much it is lowered below the text baseline, is not preserved. Secondly, graphics stored in a single \textsc{pdf} file cannot be used, because the page number with the graphic is not known. Finally, the default small margin around the graphics is not corrected for, but you can generate the graphics without the margin (see the |-tight| option in \tabref{tab:options}) or use |\includegraphics[trim=0.5bp 0.5bp 0.5bp 0.5bp]{#1}| in the above definitions to correct for that.
146
147 \end{document}
148