summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-08-26 22:28:27 +0000
committerKarl Berry <karl@freefriends.org>2011-08-26 22:28:27 +0000
commitc2b5d929f28df0fa1349a5515c6ca7475ea24388 (patch)
tree098bb0e00075333412ddaa2b257483c0d9f05739 /Master/texmf-dist/doc
parent5c3e7d14dc14232cab367595070b49c281524cad (diff)
context-filter (24aug11)
git-svn-id: svn://tug.org/texlive/trunk@23712 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt148
1 files changed, 119 insertions, 29 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index 6487c818d89..62243a553ca 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -37,9 +37,9 @@ Installation
------------
Writing installation instructions is always boring. If you are using ConTeXt
-minimals, you can install the module using
+standalone, you can install the module using
- first-setup.sh --extras="t-filter"
+ first-setup.sh --modules="t-filter"
Depending on your TeX distribution, you may already have the module.
To verify, check if
@@ -158,6 +158,20 @@ definition:
continue=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:
+
+ context --mode=force filename
+
+or adding
+
+ \enablemode[force]
+
+somewhere near the top of your file.
+
Reading the input
----------------
@@ -254,29 +268,36 @@ do not work. If you try to use a absolute path like
you will get an error message
- t-filter : Fatal Error: Cannot use absolute path /tmp/ as directory
+ t-filter > Fatal Error: Cannot use absolute path /tmp/ as directory
and compilation will stop.
-Deleting temporary files
-------------------------
+Disabling filters
+----------------
-If you want to delete the temporary files generated by the module, pass
-`--purge` option while calling `context`:
+Adding `state=stop` option disables the filters. The
+`\externalfilterinputfile` is still written, but the filter is not run.
- context --purge filename
+When used in conjunction with `continue=yes` and `directory=...`, this
+is useful for sharing your files with others who do not have the
+external program that you are using.
-This will delete the temporary files at the end of the compilation. When using
-`continue=yes`, deleting the files after each compilation defeats the purpose of
-caching the results. In that case, it is better to simply use
+Enabling the `reuse` mode (before the `filter` module is loaded) sets
+`state=stop` as the default value.
- context filename
+Deleting temporary files
+------------------------
-Once you are finished with your project and want to clean up the working
-directory, call:
+To delete the temporary files generated by the module, call
+
+ context --purgeall --pattern=filename
+
+Do **not** use the file extension. To delete all temporary files in the
+current directory, use
context --purgeall
+
Standard options
---------------
@@ -420,6 +441,71 @@ options:
The options in the `[...]` are the same as those for `\defineexternalfilter`.
+Prepend and append text
+-----------------------
+
+**NOTE** Only works in MkIV
+
+Some external programs require boilerplate text at the beginning and end of each
+file. Including this boilerplate code in each snippet can get verbose. The
+filter module provides two options `bufferbefore` and `bufferafter` to shorten
+such snippets. Define the boilerplate code in ConTeXt buffers and then use
+
+ \defineexternalfilter
+ [...]
+ [...
+ bufferbefore={...list of buffers...},
+ 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
+define a file that processes its content using `latex`.
+
+ \defineexternalfilter
+ [chess]
+ [filter=pdflatex,
+ output=\externalfilterbasefile.pdf,
+ readcommand=\readPDFfile,
+ ]
+
+ \def\readPDFfile#1{\externalfigure[#1]}
+
+
+Next create buffers containing boilerplate code needed to run latex:
+
+ \startbuffer[chess::before]
+ \documentclass{minimal}
+ \usepackage{skak}
+ \usepackage[active,tightpage]{preview}
+
+ \begin{document}
+ \begin{preview}
+ \newgame
+ \hidemoves{
+ \stopbuffer
+
+ \startbuffer[chess::after]
+ }
+ \showboard
+ \end{preview}
+ \end{document}
+ \stopbuffer
+
+and tell the filter to prepend and append these buffers
+
+ \setupexternalfilter
+ [chess]
+ [bufferbefore={chess::before},
+ bufferafter={chess::after}]
+
+Then you can use
+
+ \inlinechess{1.e4 e5 2. Nf3 Nc6 3.Bb5}
+
+to get a chess board.
+
+
Limitations
------------
@@ -447,32 +533,28 @@ indicate what is happening. Loading of the module is indicated by:
Whenever a filter is executed, 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
+ t-filter > command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp
If, for some reason, the output file is not generated, or not found, a message
similar to
- t-filter : file markdown-temp-markdown.tex cannot be found
+ t-filter > file markdown-temp-markdown.tex cannot be found
+ t-filter > current filter : markdown
+ t-filter > base file : markdown-temp-markdown
+ t-filter > input file : markdown-temp-markdown.tmp
+ t-filter > output file : markdown-temp-markdown.tex
is displayed on the console. At the same time, the string
[[output file missing]]
-is displayed in the PDF output. To debug what went wrong, add
+is displayed in the PDF output. This data, along with the name of the filter
+command, is useful for debugging what went wrong. To get more debugging
+information add
\traceexternalfilters
-in your tex file. This shows the name of all input and output files on the
-console:
-
- t-filter : current filter : markdown
- t-filter : base file : markdown-temp-markdown
- t-filter : input file : markdown-temp-markdown.tmp
- t-filter : output file : markdown-temp-markdown.tex
-
-This data, along with the name of the filter command, is useful for debugging
-what went wrong.
-
+in your tex file. This shows the name of the filters when they are defined.
Version History
@@ -502,8 +584,16 @@ Version History
- **2011.02.27**
- The external files are called `\jobname-temp-<filter>*` instead of
`\jobname-externalfilter-<filter>*`. As a result, these files are deleted
- by `context --purge`.
+ by `context --purgeall`.
- **2011.03.06**
- Complete rewrite of internal macro names. The internal macros are now
named `\modulename::command_name`. This is an experiment to see if this
style works better than the traditional naming convention in TeX.
+- **2011.06.16**
+ - Added `force` mode to force recompilation of all filters that have
+ `continue=yes`.
+ - Added `reuse` mode to skip running all filters that have
+ `continue=yes`.
+ - Added `state=stop` option to skip running external filter.
+- **2011.08.23**
+ - Added `bufferbefore` and `bufferafter` options