context-filter (7mar11)

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

1 files changed, 50 insertions, 28 deletions

diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index f4a52eebb6c..0b62538cd2d 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -182,11 +182,11 @@ Sometimes, it is desirable to ignore the output, which is done by
 Names of temporary files
 ------------------------
 
-By default, `\externalfilterinputfile` is set to `\jobname-<filter>.tmp`, where
+By default, `\externalfilterinputfile` is set to `\jobname-temp-<filter>.tmp`, where
 `<filter>` is the first argument of `\defineexternalfilter`. When `continue=yes`
-is set, `\externalfilterinputfile` equals `\jobname-<filter>-<n>.tmp`, where
+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-<filter>-<n>.tmp.md5` file, which stores the `md5` sum of the
+case,  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
@@ -253,32 +253,46 @@ you will get an error message
 
 and compilation will stop.
 
+Deleting temporary files
+------------------------
+
+If you want to delete the temporary files generated by the module, pass
+`--purge` option while calling `context`:
+
+    context --purge filename
+
+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
+
+    context filename
+
+Once you are finished with your project and want to clean up the working
+directory, call:
+
+    context --purgeall
+
 Standard options
 ---------------
 
-Like most commands in ConTeXt, `\defineexternalfilter` also accepts the `before`
-and `after` options. These are executed before and after the output file is read
-using `readcommand`. Typically, these options are used to set the spacing around
-the environment or enclose the output in a frame, etc.
-
-`style` and `color` options set the style and color of the processed
-content. Currently, these options only work with MkIV.
+`\defineexternalfilter` accepts the following standard options:
 
-`\defineexternalfilter` also accepts a `setups` option to specify a list of 
-setups (defined using `\startsetup`). These setups may be used to define
-commands that are needed inside the environment.
+- `before` and `after`: to set the spacing of the environment or enclose the
+  output in a frame, etc. 
+- `style` and `color` (these currently only work in MkIV): to set the color and
+  style of the output.
+- `indentnext`: Should the next line be indented?
+- `setups`: specify a list of setups (defined using `\startsetups`). These
+  setups may be used to define commands that are needed inside the environment.
 
-The order in which these options are executed is:
+The order in which these options are executed are:
 
-    \def\dodoreadprocessedfile
-      {\externalfilterparameter\c!before
-       \begingroup
-       \doifmode\s!mkiv
-          {\dosetexternalfilterattributes\c!style\c!color}
-       \processcommacommand[\externalfilterparameter\c!setups]\directsetup
-       \externalfilterparameter\c!readcommand\externalfilteroutputfile
-       \endgroup
-       \externalfilterparameter\c!after}
+1. `before`
+2. `style` and `color`
+3. `setups`
+4. `readcommand`
+5. `after`
+6. check `indentnext`
 
 Options to a specific environment
 ---------------------------------
@@ -428,12 +442,12 @@ 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-externalfilter-markdown.tex markdown-externalfilter-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-externalfilter-markdown.tex cannot be found
+    t-filter        : file markdown-temp-markdown.tex cannot be found
 
 is displayed on the console. At the same time, the string 
 
@@ -447,9 +461,9 @@ 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-externalfilter-markdown
-    t-filter        : input file : markdown-externalfilter-markdown.tmp
-    t-filter        : output file : markdown-externalfilter-markdown.tex
+    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.
@@ -480,3 +494,11 @@ Version History
       increment global.
 - **2011.02.21**
     - Added `style` and `color` options.
+- **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`.
+- **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.