diff options
Diffstat (limited to 'Master')
-rw-r--r-- | Master/texmf-dist/doc/context/third/filter/filter.txt | 104 | ||||
-rw-r--r-- | Master/texmf-dist/tex/context/third/filter/t-filter.tex | 80 |
2 files changed, 147 insertions, 37 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. diff --git a/Master/texmf-dist/tex/context/third/filter/t-filter.tex b/Master/texmf-dist/tex/context/third/filter/t-filter.tex index 9ae777aa3b7..1d31bbf16f7 100644 --- a/Master/texmf-dist/tex/context/third/filter/t-filter.tex +++ b/Master/texmf-dist/tex/context/third/filter/t-filter.tex @@ -1,6 +1,6 @@ %D \module %D [ file=t-filter, -%D version=2010.09.26, +%D version=2010.10.09 %D title=\CONTEXT\ User Module, %D subtitle=Filter, %D author=Aditya Mahajan, @@ -27,6 +27,8 @@ \def\currentexternalfilter{} \def\externalfiltercountername{\??externalfilter??-\currentexternalfilter-counter} +\newwrite\externalfilterwrite + \def\externalfilterparameter#1% {\csname \docheckparentparameter{\??externalfilter??\currentexternalfilter}{#1}% @@ -67,9 +69,8 @@ {\expandafter\newcounter\csname\externalfiltercountername\endcsname}% \setvalue{\e!start#1}{\bgroup\obeylines\dodoubleargument\dostartexternalfilter[#1]}% \setvalue{\e!stop#1}{\doprocessexternalfilter}% - \setvalue{process#1file}{\dodoubleargument\doprocessexternalfile[#1]}% - %TODO: Inline. - %\setvalue{#1}##1{\save ##1 to file} + \setvalue{process#1file}{\dodoubleargument\doprocessexternalfiler[#1]}% + \setvalue{inline#1}{\doinlineexternalfilter[#1]} } @@ -79,10 +80,15 @@ \begingroup % to keep assignments local \edef\currentexternalfilter {#1}% \getparameters[\??externalfilter??#1][\c!name=,#2]% - % Set the name of temp file for os filter + \setexternalfilterfilenames + % Capture the contents of the buffer + \dostartbuffer[\externalfiltertmpfile][\e!start#1][\e!stop#1]} + +\def\setexternalfilterfilenames + {% Set the name of temp file for os filter \doifelse{\externalfilterparameter\c!continue}\v!yes - {\edef\externalfiltertmpfile{\??externalfilter??-#1-\csname\externalfiltercountername\endcsname}} - {\edef\externalfiltertmpfile{\??externalfilter??-#1}} + {\edef\externalfiltertmpfile{\??externalfilter??-\currentexternalfilter-\csname\externalfiltercountername\endcsname}} + {\edef\externalfiltertmpfile{\??externalfilter??-\currentexternalfilter}} \doifsomething{\externalfilterparameter\c!name} {\edef\externalfiltertmpfile{\externalfilterparameter\c!name}} % The following macros are useful for filter= and filtercommand= options @@ -92,10 +98,9 @@ \edef\externalfilterinputfile {\externalfilterbasefile.tmp}% % The name of the file to which the output is written \edef\externalfilteroutputfile{\externalfilterparameter\c!output}% - % Capture the contents of the buffer - \dostartbuffer[\externalfiltertmpfile][\e!start#1][\e!stop#1]} + } -\def\doprocessexternalfilter% +\def\doprocessexternalfilter {% By defualt, buffers are in memory in MkIV \doifmode\s!mkiv{\savebuffer[\externalfiltertmpfile]}% % Run external command @@ -112,7 +117,7 @@ {\doifmode{*first} {\executesystemcommand {mtxrun --ifchanged=\externalfilterinputfile\space - bin:\externalfilterparameter\c!filtercommand}}} + --direct \externalfilterparameter\c!filtercommand}}} {\executesystemcommand {\externalfilterparameter\c!filtercommand}}} @@ -120,7 +125,8 @@ {\doif{\externalfilterparameter\c!read}\v!yes {\doiffileelse{\externalfilteroutputfile} {\dodoreadprocessedfile} - {{\tttf TODO: File \externalfilteroutputfile\ not found! Check your definition}}}} + %TODO: Proper error message + {{\tttf File \externalfilteroutputfile\ not found! Check your definition}}}} \def\dodoreadprocessedfile {\begingroup @@ -130,16 +136,54 @@ \externalfilterparameter\c!after \endgroup} -\def\doprocessexternalfile[#1][#2]% - {\edef\currentexternalfilter {#1}% - \edef\externalfilterinputfile {#2}% - \splitfiletype {#2}% +\def\doprocessexternalfiler[#1][#2]#3% + {\begingroup + \edef\currentexternalfilter {#1}% + \getparameters[\??externalfilter??#1][\c!name=,#2]% TODO: Add continue=yes + % Currently filters with a pipe (|) fail with continue=yes + \edef\externalfilterinputfile {#3}% + \splitfiletype {#3}% %BEWARE. \edef doesn not work - \def\externalfilterbasefile {\splitoffname} + \def\externalfilterbasefile {\splitoffname}% \def\externalfilteroutputfile{\externalfilterparameter\c!output}% \doexecuteexternalfilter - \doreadprocessedfile} + \doreadprocessedfile + \endgroup} +\def\doinlineexternalfilter[#1]% + {\begingroup % to keep assignments local + \edef\currentexternalfilter {#1}% + \getparameters[\??externalfilter??#1][\c!name=,\c!continue=\v!no]% + \setexternalfilterfilenames + \pushcatcodetable + \futurelet\next\dodoinlineexternalfilter} + +\def\dodoinlineexternalfilter + {\ifx\next\bgroup + \expandafter\dodoinlineexternalfilterA + \else + \expandafter\dodoinlineexternalfilterB + \fi} + +\def\dodoinlineexternalfilterA + {\setcatcodetable \typcatcodesa + \redoinlineexternalfilter} + +\def\dodoinlineexternalfilterB#1% + {\setcatcodetable \vrbcatcodes + \def\dododoinlineexternalfilterB##1#1{\redoinlineexternalfilter{##1}}% + \dododoinlineexternalfilterB} + +\def\redoinlineexternalfilter#1% + {\immediate\openout \externalfilterwrite\externalfilterinputfile + \immediate\write \externalfilterwrite{\detokenize{#1}}% + \immediate\closeout\externalfilterwrite + \popcatcodetable + \doexecuteexternalfilter + \doreadprocessedfile + \endgroup} + + \setupexternalfilters [ |