summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/third
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-01-30 00:35:07 +0000
committerKarl Berry <karl@freefriends.org>2012-01-30 00:35:07 +0000
commitf60c2c93c50a174b6f9fb879c7363038a97fa6fe (patch)
tree0c43c580591dd837a6a05bd395c3c0fb34d656d7 /Master/texmf-dist/doc/context/third
parentfb3894caf2806710304dbf85c1eeb3afda95d0f2 (diff)
context-filter (28jan12)
git-svn-id: svn://tug.org/texlive/trunk@25229 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context/third')
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt94
1 files changed, 40 insertions, 54 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index 396596cec36..13e1acc4898 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -49,7 +49,7 @@ To verify, check if
returns a meaningful path. If not, you have to manually install the module.
Download the latest version of the module from
-[http://github.com/adityam/filter/downloads](http://github.com/adityam/filter/downloads)
+[http://modules.contextgarden.net/filter](http://modules.contextgarden.net/filter)
and unzip it either `$TEXMFHOME` or `$TEXMFLOCAL`. Run
mktexlsr
@@ -67,8 +67,7 @@ will return the path where you stored the file.
Unfortunately, that is not enough. For the module to work, TeX must be able to
call an external program. This feature is a potential security risk and is
-disabled by default on most TeX distributions. To enable this feature, you must
-set
+disabled by default on most TeX distributions. To enable this feature, set
shell_escape=t
@@ -104,9 +103,9 @@ Using this filter from within ConTeXt is pretty simple:
[filtercommand={pandoc -t context -o \externalfilteroutputfile\space \externalfilterinputfile}]
Yes, its that easy! The only thing to note is that TeX macros gobble spaces, so
-we have to manually insert a space after `\externalfilteroutputfile`.
+I inserted a manual space after `\externalfilteroutputfile`.
-This defines four things:
+The above `\defineexternalfilter` macro defines:
1. An environment
@@ -148,11 +147,11 @@ Dealing with slow filters
The above definition of a markdown filter creates two additional files: an
"input" file and an "output" file, *irrespective of the
number of times the environment is called*. For each markdown environment,
-ConTeXt overwrites the input file and pandoc overwrites the output file. This
-behavior is the default as I do not want to clutter the current directory with
-temporary files. The trade off is that for each document run, the filter is
+ConTeXt overwrites the input file and pandoc overwrites the output
+file; as a result, the current directory is not cluttered with temporary files.
+The trade off is that for each document run, the filter is
invoked as many times as the number of markdown environments. Since getting
-cross-referencing right normally takes two or three runs, effectively the filter
+cross-referencing right normally takes two to three runs, effectively the filter
is run two or three times more than required. A filter like `pandoc` is fairly
fast, so these extra runs are not noticeable. But some filters, like the
R-programming language for which simply startup and exit takes about 0.3
@@ -160,28 +159,25 @@ seconds, are slow. In such cases, the additional runs start adding up. A better
trade off is to store the contents of each environment in a separate file and
invoke the filter only if a file *changes in between successive runes*.
-The second behavior is achieved by adding `continue=yes` option to the
+The second behavior is achieved by adding `cache=yes` option to the
definition:
\defineexternalfilter
[...]
[...
- continue=yes,
+ cache=yes,
...]
-Sometimes you want to force a rerun of all filters, even when `continue=yes` is
-set. This could be because the filters depend on an external script that might
-have changed. To force a rerun of all filters, enable the
-[mode](http://wiki.contextgarden.net/Modes) `force` either by adding
-`mode=force` to the compiler:
+Sometimes you want to force the rerun of a filter, even if the content of the
+environment has not changed. This could be because the filters depend on an
+external script that might have changed. To force a rerun of a filter use
- context --mode=force filename
-or adding
-
- \enablemode[force]
-
-somewhere near the top of your file.
+ \defineexternalfilter
+ [...]
+ [...
+ cache=force,
+ ...]
Reading the input
----------------
@@ -213,10 +209,10 @@ Names of temporary files
------------------------
By default, `\externalfilterinputfile` is set to `\jobname-temp-<filter>.tmp`, where
-`<filter>` is the first argument of `\defineexternalfilter`. When `continue=yes`
+`<filter>` is the first argument of `\defineexternalfilter`. When `cache=yes`
is set, `\externalfilterinputfile` equals `\jobname-temp-<filter>-<n>.tmp`, where
-`<n>` is the number of filter environments that have appeared so far. In this
-case, a `\jobname-temp-<filter>-<n>.tmp.md5` file, which stores the `md5` sum of the
+`<n>` is the number of filter environments that have appeared so far. In MkII,
+a `\jobname-temp-<filter>-<n>.tmp.md5` file, which stores the `md5` sum of the
input file is also created.
A macro `\externalfilterbasefile` stores the name of the input file without the
@@ -231,15 +227,7 @@ key. For example
[filtercommand={...},
output={\externalfilterbasefile.png}]
-changes the output extension to `.png`. We also need to either set
-
- \defineexternalfilter
- [...]
- [....
- read=no,
- ...]
-
-or set
+changes the output extension to `.png`. To read the generated PNG file, set:
\defineexternalfilter
[...]
@@ -255,7 +243,7 @@ Output Directory
----------------
This module creates a lot of temporary files that clutter the current directory.
-If you prefer the temporary files to be created in another directory, specify
+If you prefer the temporary files to be created in another directory, use
the `directory` option, e.g.,
\defineexternalfilter
@@ -289,13 +277,10 @@ Disabling filters
Adding `state=stop` option disables the filters. The
`\externalfilterinputfile` is still written, but the filter is not run.
-When used in conjunction with `continue=yes` and `directory=...`, this
+When used in conjunction with `cache=yes` and `directory=...`, this
is useful for sharing your files with others who do not have the
external program that you are using.
-Enabling the `reuse` mode (before the `filter` module is loaded) sets
-`state=stop` as the default value.
-
Deleting temporary files
------------------------
@@ -317,7 +302,7 @@ Standard options
- `before` and `after`: to set the spacing of the environment or enclose the
output in a frame, etc.
- `style` and `color`: to set the color and style of the output.
-- `indentnext`: Should the next line be indented?
+- `indentnext`: specify if the next line is indented
- `setups`: specify a list of setups (defined using `\startsetups`). These
setups may be used to define commands that are needed inside the environment.
@@ -342,7 +327,7 @@ R-code
[R]
[filtercommand={R CMD BATCH -q \externalfilterinputfile\space \externalfilteroutputfile},
output=\externalfilterbasefile.out,
- continue=yes]
+ cache=yes]
I can hide the output of a particular R-environment by
@@ -368,7 +353,7 @@ of all options. The current defaults are
[before=,
after=,
setups=,
- continue=no,
+ cache=no,
read=yes,
readcommand=\ReadFile,
output=\externalfilterbasefile.tex,
@@ -519,8 +504,8 @@ such snippets. Define the boilerplate code in ConTeXt buffers and then use
bufferafter={...list of buffers...},
]
-For example, suppose you want to generate images using a latex package that does
-not work well with ConTeXt, say shak. One way to use this is as follows: first
+For example, suppose you want to generate images using a LaTeX package that does
+not work well with ConTeXt, say `shak`. One way to use this is as follows: first
define a file that processes its content using `latex`.
\defineexternalfilter
@@ -578,7 +563,7 @@ GNU barcode to draw barcodes. One way to do this is
[barcode]
[encoding=code128,
output=\externalfilterbasefile.eps,
- continue=yes,
+ cache=yes,
filtercommand=\barcodefiltercommand,
readcommand=\barcodereadcommand]
@@ -643,8 +628,8 @@ for this. For example, in the above barcode example, use
Limitations
------------
-- In MkII, the option `continue=yes` does not work correctly with filters that have a
- pipe `|` in their definition. This is because internally `continue=yes` calls
+- In MkII, the option `cache=yes` does not work correctly with filters that have a
+ pipe `|` in their definition. This is because internally `cache=yes` calls
mtxrun --ifchanged=filename --direct filtercommand
@@ -655,7 +640,7 @@ Limitations
MTXrun |
MTXrun |
- In MkIV, `continue=yes` calls
+ In MkIV, `cache=yes` calls
\ctxlua{job.files.run("filename", "filtercommand")}
@@ -669,9 +654,9 @@ Messages and Tracing
The filter module outputs some diagnostic information on the console output to
indicate what is happening. Loading of the module is indicated by:
- loading : ConTeXt User Module / Filter
+ loading : ConTeXt User Module / Filter (ver: <date>)
-Whenever a filter is executed, the expanded name of the command is displayed.
+Whenever a filter is defined the expanded name of the command is displayed.
For example, for the markdown filter we get:
t-filter > command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp
@@ -697,15 +682,12 @@ information add
in your tex file. This shows the name of the filters when they are defined.
In MkIV, `\traceexternalfilters` also enables the trackers for `graphic.run`, so
-when `continue=yes` is used, message like
+when `cache=yes` is used, message like
graphics > run > processing file, no changes in '<filename>-temp-<filtername>-<n>.tmp', not processed
are shown.
-
-
-
Version History
--------------
@@ -760,3 +742,7 @@ Version History
- Use `job.files.run` instead of `mtxrun --ifchanged` in MkIV.
- **2011.12.17**
- Split into `.mkii` and `.mkiv` versions
+- **2012.01.26**
+ - Renamed `continue` to `cache`. Using `continue=yes` still works
+ - Removed `force` and `reuse` modes (too easy to clash with user modes).
+ - Functionality of force mode implemented using `cache=force`.