context-filter (24aug11)

git-svn-id: svn://tug.org/texlive/trunk@23712 c570f23f-e606-0410-a88d-b1316a301751

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