summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt68
1 files changed, 68 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index b98325b2fec..68deb3e2a34 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -683,6 +683,72 @@ Then you can use
to get a chess board.
+Special use case: `\write18` with caching
+------------------------------------------
+
+Although the raison d'ĂȘtre of the externalfilter module is to process the
+content of an evironment or a macro through an external program, it may also be
+used to simply exectute an external program without processing any content.
+
+For example, suppose we want to include an image with a swirl gradient in our
+document. ImageMagick can generate such an image using:
+
+ convert -size 100x100 gradient: -swirl 180 <output file>
+
+Notice that in this case, the external program does not need any input file. We
+just need to pass the size of the image to the external program.
+
+In such cases, we still want to cache the result, i.e., rerun the external
+program only when the `size` of the image has changed. The `write=no` option
+covers this use case. The basic usage is:
+
+ \defineexternalfilter
+ [...]
+ [
+ ...
+ write=no,
+ cacheoption=....,
+ ...
+ ]
+
+Out of the four macros (see [Basic Usage]) created by `\defineexternalfilter`,
+only `\inline<externalfilter>` makes sense with `write=no`. The usage of this
+macro is
+
+ \inline<externalfilter>[....]
+
+Unlike the default case, this version does not take an argument! (That is
+because, it does not write anything to a file).
+
+When `write=no` is set, `\externalfilterbasefile` is equal to
+`\jobname-temp-<filter>-<cacheoption>` where `<cacheoption>` is the value of the
+`cacheoption` key.
+
+For example, to generate swirl backgrounds described above, define:
+
+ \defineexternalfilter
+ [swirl]
+ [
+ write=no,
+ cacheoptions={\externalfilterparameter{size}},
+ cache=yes,
+ size={1000x1000},
+ output=\externalfilterbasefile.png,
+ filtercommand={convert -size \externalfilterparameter{size} gradient: -swirl 180 \externalfilteroutputfile},
+ readcommand=\ReadFigure,
+ ]
+
+ \def\ReadFigure#1%
+ {\externalfigure[#1]}
+
+
+This creates a macro `\inlineswirl` that uses ImageMagick to generate a file
+`\jobname-temp-swirl-1000x1000.png`.
+
+The result is cached and the external program is rerun only if the value of
+cacheoption changes, that is, only if the value of `size` key changes.
+
+
Dealing with expansion
----------------------
@@ -888,3 +954,5 @@ Version History
- Added `align` key.
- **2012.06.20**
- Support for `\usepath`
+- **2012.01.13**
+ - Support for `write=no` and `cacheoption=...`.