diff options
author | Karl Berry <karl@freefriends.org> | 2010-10-11 00:24:56 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-10-11 00:24:56 +0000 |
commit | df4c7d3e395c9b22ace64dbbf61191ac43beea3f (patch) | |
tree | 15d4350ce1147556781eabb0d8b436754816efb0 /Master/texmf-dist/doc/context | |
parent | 6d35fc8476c39b632c9dd7bb53b2bb979c93f8d2 (diff) |
context-filter update (10oct10)
git-svn-id: svn://tug.org/texlive/trunk@20050 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context')
-rw-r--r-- | Master/texmf-dist/doc/context/third/filter/filter.txt | 104 |
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. |