context-filter (24oct11)

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

1 files changed, 59 insertions, 1 deletions

diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index ab4e9c6f90c..1b03acaaac1 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -106,7 +106,7 @@ Using this filter from within ConTeXt is pretty simple:
 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`.
 
-This defines three things:
+This defines four things:
 
 1. An environment
 
@@ -131,6 +131,14 @@ This defines three things:
    The argument to the macro is a filename, which is processed by `pandoc` and
    the output is included back in ConTeXt.
 
+4. A macro
+    
+        \processmarkdownbuffer[...]
+
+   The argument to the macro is the name of a buffer, which is written to an
+   external file, processesd by `pandoc` and the output included back in
+   ConTeXt.
+
 Dealing with slow filters
 -------------------------
 
@@ -339,6 +347,12 @@ I can hide the output of a particular R-environment by
     ...
     \stopR
 
+The macros `\processmarkdownfile` and `\processmarkdownbuffer` also accept user
+options. The usage is
+
+    \processmarkdownfile  [.-.=.-.]{filename}
+    \processmarkdownbuffer[...=...][buffer]
+
 
 A setup to control them all
 ---------------------------
@@ -441,6 +455,50 @@ options:
 
 The options in the `[...]` are the same as those for `\defineexternalfilter`.
 
+Processing Existing Buffers
+---------------------------
+
+Like all macros built on top of buffers, the `\start<filter>` ...
+`\stop<filter>` environment does not work well inside the argument of another
+command. The `\process<filter>buffer` macro is handy for such macros.
+
+Suppose you want to write some markdown text in a footnote. Using
+
+    \footnote{ .... 
+       \startmarkdown
+          ...
+       \stopmarkdown}
+
+gives an error message:
+
+    ! File ended while scanning use of \dododowithbuffer.
+
+    system          > tex > error on line 0 in file : File ended while scanning use
+    of \dododowithbuffer ...
+
+    <empty file>
+
+    <inserted text> 
+                    \par 
+
+To avoid this, define a buffer at the outer level 
+
+    \startbuffer[footnote-markdown]
+       ...
+    \stopbuffer
+
+and then use
+
+    \footnote{... \processmarkdownbuffer[footnote-markdown]}
+
+The `\process<filter>buffer` macro also takes an optional argument for setup
+options:
+
+    \process<filter>buffer[...][...]
+
+The options in the first `[...]` are the same as those for `\defineexternalfilter`.
+
+
 Prepend and append text
 -----------------------