summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-10-11 00:24:56 +0000
committerKarl Berry <karl@freefriends.org>2010-10-11 00:24:56 +0000
commitdf4c7d3e395c9b22ace64dbbf61191ac43beea3f (patch)
tree15d4350ce1147556781eabb0d8b436754816efb0
parent6d35fc8476c39b632c9dd7bb53b2bb979c93f8d2 (diff)
context-filter update (10oct10)
git-svn-id: svn://tug.org/texlive/trunk@20050 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt104
-rw-r--r--Master/texmf-dist/tex/context/third/filter/t-filter.tex80
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
[