summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt104
1 files changed, 85 insertions, 19 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index 4609d606eb3..e6654c83c15 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -31,20 +31,21 @@ the blanks with the appropriate values. And so, the filter module was born.
Installation
------------
-Writing installation instructions is always boring. Hopefully, by the time this
-article is published, the filter module will be available from ConTeXt garden.
-If so, and if you are using ConTeXt minimals, you already have the module. To
-verify, check if
+Writing installation instructions is always boring. If you are using ConTeXt
+minimals, you can install the module using
+
+ first-setup.sh --extras="t-filter"
+
+Depending on your TeX distribution, you may already have the module.
+To verify, check if
kpsewhich t-filter.tex
returns a meaningful path. If not, you have to manually install the module.
-Create a directory `tex/context/third/filter` in your `$TEXMFHOME` or
-`$TEXMFLOCAL` directory. Copy `t-filter.tex` and `t-filter.lua` from
-this git repository
-[http://github.com/adityam/filter](http://github.com/adityam/filter) to the
-directory that you just created. Run
+Download the latest version of the module from
+[http://github.com/adityam/filter/downloads](http://github.com/adityam/filter/downloads)
+and unzip it either `$TEXMFHOME` or `$TEXMFLOCAL`. Run
mktexlsr
@@ -100,21 +101,30 @@ 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 an environment
+This defines three things:
- \startmarkdown
- ...
- \stopmarkdown
+1. An environment
+
+ \startmarkdown
+ ...
+ \stopmarkdown
+
+ The contents of the environment are processed by `pandoc` and the output is
+ included back in ConTeXt.
+
+2. A macro
-and a macro
+ \inlinemarkdown{...}
- \processmarkdownfile[...]
+ The argument of the macro is processed by `pandoc` and the output is included
+ back in ConTeXt.
-The contents of the environment are processed by `pandoc` and the output is
-included back in ConTeXt.
+3. A macro
-The argument to the macro is a filename, which is processed by `pandoc` and the
-output is included back in ConTeXt.
+ \processmarkdownfile{...}
+
+ The argument to the macro is a filename, which is processed by `pandoc` and
+ the output is included back in ConTeXt.
Dealing with slow filters
-------------------------
@@ -313,4 +323,60 @@ Thus, the pandoc environment may be defined as
format=markdown]
+Macro variant
+-------------
+
+For some cases, a macro `\inline<filter>{...}` is more natural to use rather
+than the environment `\start<filter>` ... `\stop<filter>`. The `\inline...`
+variant is meant for simple cases, so it does not accept any options in square
+brackets.
+
+
+
+Processing Existing Files
+-------------------------
+
+A big advantage of a lightweight markup language like markdown is that it is
+easy to convert it into other markups--html, rtf, epub, etc. For that reason, I
+key in markdown in a separate file rather in a start-stop environment of a TeX
+file. To use such markdown files in ConTeXt, I can just use
+
+ \processmarkdownfile{filename.md}
+
+The general macro is `\process<filter>file{...}`, which takes the name of a file
+as an argument and uses that file as the input file for the filter. The rest of
+the processing is the same as with `\start<filter>` ... `\stop<filter>`
+environment.
+
+The `\process<filter>file` macro also takes an optional argument for setup
+options:
+
+ \process<filter>file[...]{...}
+
+The options in the `[...]` are the same as those for `\defineexternalfilter`.
+
+Limitations
+------------
+
+- The option `continue=yes` does not work correctly with filters that have a
+ pipe `|` in their definition. This is because internally `continue=yes` calls
+
+ mtxrun --ifchanged=filename --direct filtercommand
+
+ and this produces
+
+ MTXrun |
+ MTXrun | executing: filtercommand
+ MTXrun |
+ MTXrun |
+
+
+Version History
+--------------
+- **2010.09.26**:
+ - First release
+- **2010.10.09**:
+ - Added `\inline<filter>{...}` macro
+ - Changed the syntax of `\process<filter>file`. The filename is now
+ specified in curly brackets rather than square brackets.