summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Master/texmf-dist/doc/context/third/filter/filter.txt148
-rw-r--r--Master/texmf-dist/tex/context/third/filter/t-filter.tex99
2 files changed, 187 insertions, 60 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt
index 6487c818d89..62243a553ca 100644
--- a/Master/texmf-dist/doc/context/third/filter/filter.txt
+++ b/Master/texmf-dist/doc/context/third/filter/filter.txt
@@ -37,9 +37,9 @@ Installation
------------
Writing installation instructions is always boring. If you are using ConTeXt
-minimals, you can install the module using
+standalone, you can install the module using
- first-setup.sh --extras="t-filter"
+ first-setup.sh --modules="t-filter"
Depending on your TeX distribution, you may already have the module.
To verify, check if
@@ -158,6 +158,20 @@ definition:
continue=yes,
...]
+Sometimes you want to force a rerun of all filters, even when `continue=yes` is
+set. This could be because the filters depend on an external script that might
+have changed. To force a rerun of all filters, enable the
+[mode](http://wiki.contextgarden.net/Modes) `force` either by adding
+`mode=force` to the compiler:
+
+ context --mode=force filename
+
+or adding
+
+ \enablemode[force]
+
+somewhere near the top of your file.
+
Reading the input
----------------
@@ -254,29 +268,36 @@ do not work. If you try to use a absolute path like
you will get an error message
- t-filter : Fatal Error: Cannot use absolute path /tmp/ as directory
+ t-filter > Fatal Error: Cannot use absolute path /tmp/ as directory
and compilation will stop.
-Deleting temporary files
-------------------------
+Disabling filters
+----------------
-If you want to delete the temporary files generated by the module, pass
-`--purge` option while calling `context`:
+Adding `state=stop` option disables the filters. The
+`\externalfilterinputfile` is still written, but the filter is not run.
- context --purge filename
+When used in conjunction with `continue=yes` and `directory=...`, this
+is useful for sharing your files with others who do not have the
+external program that you are using.
-This will delete the temporary files at the end of the compilation. When using
-`continue=yes`, deleting the files after each compilation defeats the purpose of
-caching the results. In that case, it is better to simply use
+Enabling the `reuse` mode (before the `filter` module is loaded) sets
+`state=stop` as the default value.
- context filename
+Deleting temporary files
+------------------------
-Once you are finished with your project and want to clean up the working
-directory, call:
+To delete the temporary files generated by the module, call
+
+ context --purgeall --pattern=filename
+
+Do **not** use the file extension. To delete all temporary files in the
+current directory, use
context --purgeall
+
Standard options
---------------
@@ -420,6 +441,71 @@ options:
The options in the `[...]` are the same as those for `\defineexternalfilter`.
+Prepend and append text
+-----------------------
+
+**NOTE** Only works in MkIV
+
+Some external programs require boilerplate text at the beginning and end of each
+file. Including this boilerplate code in each snippet can get verbose. The
+filter module provides two options `bufferbefore` and `bufferafter` to shorten
+such snippets. Define the boilerplate code in ConTeXt buffers and then use
+
+ \defineexternalfilter
+ [...]
+ [...
+ bufferbefore={...list of buffers...},
+ bufferafter={...list of buffers...},
+ ]
+
+For example, suppose you want to generate images using a latex package that does
+not work well with ConTeXt, say shak. One way to use this is as follows: first
+define a file that processes its content using `latex`.
+
+ \defineexternalfilter
+ [chess]
+ [filter=pdflatex,
+ output=\externalfilterbasefile.pdf,
+ readcommand=\readPDFfile,
+ ]
+
+ \def\readPDFfile#1{\externalfigure[#1]}
+
+
+Next create buffers containing boilerplate code needed to run latex:
+
+ \startbuffer[chess::before]
+ \documentclass{minimal}
+ \usepackage{skak}
+ \usepackage[active,tightpage]{preview}
+
+ \begin{document}
+ \begin{preview}
+ \newgame
+ \hidemoves{
+ \stopbuffer
+
+ \startbuffer[chess::after]
+ }
+ \showboard
+ \end{preview}
+ \end{document}
+ \stopbuffer
+
+and tell the filter to prepend and append these buffers
+
+ \setupexternalfilter
+ [chess]
+ [bufferbefore={chess::before},
+ bufferafter={chess::after}]
+
+Then you can use
+
+ \inlinechess{1.e4 e5 2. Nf3 Nc6 3.Bb5}
+
+to get a chess board.
+
+
Limitations
------------
@@ -447,32 +533,28 @@ indicate what is happening. Loading of the module is indicated by:
Whenever a filter is executed, the expanded name of the command is displayed.
For example, for the markdown filter we get:
- t-filter : command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp
+ t-filter > command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp
If, for some reason, the output file is not generated, or not found, a message
similar to
- t-filter : file markdown-temp-markdown.tex cannot be found
+ t-filter > file markdown-temp-markdown.tex cannot be found
+ t-filter > current filter : markdown
+ t-filter > base file : markdown-temp-markdown
+ t-filter > input file : markdown-temp-markdown.tmp
+ t-filter > output file : markdown-temp-markdown.tex
is displayed on the console. At the same time, the string
[[output file missing]]
-is displayed in the PDF output. To debug what went wrong, add
+is displayed in the PDF output. This data, along with the name of the filter
+command, is useful for debugging what went wrong. To get more debugging
+information add
\traceexternalfilters
-in your tex file. This shows the name of all input and output files on the
-console:
-
- t-filter : current filter : markdown
- t-filter : base file : markdown-temp-markdown
- t-filter : input file : markdown-temp-markdown.tmp
- t-filter : output file : markdown-temp-markdown.tex
-
-This data, along with the name of the filter command, is useful for debugging
-what went wrong.
-
+in your tex file. This shows the name of the filters when they are defined.
Version History
@@ -502,8 +584,16 @@ Version History
- **2011.02.27**
- The external files are called `\jobname-temp-<filter>*` instead of
`\jobname-externalfilter-<filter>*`. As a result, these files are deleted
- by `context --purge`.
+ by `context --purgeall`.
- **2011.03.06**
- Complete rewrite of internal macro names. The internal macros are now
named `\modulename::command_name`. This is an experiment to see if this
style works better than the traditional naming convention in TeX.
+- **2011.06.16**
+ - Added `force` mode to force recompilation of all filters that have
+ `continue=yes`.
+ - Added `reuse` mode to skip running all filters that have
+ `continue=yes`.
+ - Added `state=stop` option to skip running external filter.
+- **2011.08.23**
+ - Added `bufferbefore` and `bufferafter` options
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 6f95644953f..2d89f168ef4 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=2011.06.12,
+%D version=2011.08.23,
%D title=\CONTEXT\ User Module,
%D subtitle=Filter,
%D author=Aditya Mahajan,
@@ -36,15 +36,6 @@
\setinterfaceconstant {readcommand} {readcommand}
\stopinterface
-\def\m!externalfilter{t-filter}
-
-%D \subsubject {Messages}
-
-\setinterfacemessage{externalfilter}{title} {\m!externalfilter}
-\setinterfacemessage{externalfilter}{notfound} {file -- cannot be found}
-\setinterfacemessage{externalfilter}{missing} {output file missing}
-\setinterfacemessage{externalfilter}{forbidden} {Fatal Error: Cannot use absolute path -- as directory}
-\setinterfacemessage{externalfilter}{slash} {Appending / to directory -- }
%D \subsubject {Name space}
@@ -62,6 +53,17 @@
\doifmode\s!mkiv
{\installattributehandler \externalfilter::namespace \externalfilter::id}
+\def\m!externalfilter{t-filter}
+
+%D \subsubject {Messages}
+
+\setinterfacemessage\m!externalfilter{title} {\m!externalfilter}
+\setinterfacemessage\m!externalfilter{notfound} {file -- cannot be found}
+\setinterfacemessage\m!externalfilter{missing} {output file missing}
+\setinterfacemessage\m!externalfilter{forbidden} {Fatal Error: Cannot use absolute path -- as directory}
+\setinterfacemessage\m!externalfilter{slash} {Appending / to directory -- }
+\setinterfacemessage\m!externalfilter{reuse} {\c!state=\v!stop : Not running filter on file --}
+
% For backward compatibility
\let\setupexternalfilters \setupexternalfilter
@@ -72,12 +74,10 @@
\let\traceexternalfilters\traceexternalfilterstrue
\starttexdefinition externalfilter::show_filenames
- \iftraceexternalfilters
- \writestatus\m!externalfilter{current filter : \externalfilter::name}
- \writestatus\m!externalfilter{base file : \externalfilter::base_file}
- \writestatus\m!externalfilter{input file : \externalfilter::input_file}
- \writestatus\m!externalfilter{output file : \externalfilter::output_file}
- \fi
+ \writestatus\m!externalfilter{current filter : \externalfilter::name}
+ \writestatus\m!externalfilter{base file : \externalfilter::base_file}
+ \writestatus\m!externalfilter{input file : \externalfilter::input_file}
+ \writestatus\m!externalfilter{output file : \externalfilter::output_file}
\stoptexdefinition
\starttexdefinition externalfilter::show_status #1
@@ -100,8 +100,8 @@
\starttexdefinition externalfilter::define [#1][#2]
\externalfilter::show_status{defining filter : #1}
+ \setupexternalfilter[#1][\s!parent=\externalfilter::namespace,#2]
\edef\externalfilter::name{#1}
- \getparameters[\externalfilter::namespace#1][\s!parent=\externalfilter::namespace,#2]
\doif{\externalfilterparameter\c!continue}\v!yes
{\expandafter\newcounter\csname\externalfilter::count\endcsname}
@@ -111,6 +111,7 @@
\setvalue{process#1file}{\dodoubleargument\externalfilter::process_file[#1]}
\setvalue{inline#1}{\externalfilter::inline[#1]}
+
\stoptexdefinition
\starttexdefinition externalfilter::start [#1][#2]
@@ -121,7 +122,7 @@
\edef\externalfilter::name{#1}
\begingroup % to keep assignments local
- \getparameters[\externalfilter::namespace#1][\c!name=,#2]
+ \setupexternalfilter[#1][\c!name=,#2]
\externalfilter::set_filenames
@@ -133,7 +134,7 @@
\begingroup
\edef\externalfilter::name{#1}
- \getparameters[\externalfilter::namespace#1][\c!name=,#2]
+ \setupexternalfilter[#1][\c!name=,#2]
\externalfilter::set_directory
@@ -146,7 +147,7 @@
% \c!directory; even if the input is from some other directory
\def\externalfilter::output_file{\externalfilter::get_directory\externalfilterparameter\c!output}
- \externalfilter::show_filenames
+ \iftraceexternalfilters \externalfilter::show_filenames \fi
\externalfilter::execute_filter
\externalfilter::read_processed_file
@@ -157,7 +158,7 @@
\edef\externalfilter::name{#1}
\begingroup % to keep assignments local
- \getparameters[\externalfilter::namespace#1][\c!name=]
+ \setupexternalfilter[#1][\c!name=]
\externalfilter::set_filenames
@@ -165,6 +166,7 @@
\futurelet\next\externalfilter::inline_aux
\stoptexdefinition
+
%D \subsubject {Catcode tables}
%D
%D Just to be sure, I define all catcode tables that are needed within the
@@ -272,13 +274,13 @@
\starttexdefinition externalfilter::set_directory_aux
\doif{\externalfilter::get_first_character\externalfilter::get_directory}{/}
{\writeline
- \showmessage\externalfilter::id{forbidden}\externalfilter::get_directory
+ \showmessage\m!externalfilter{forbidden}\externalfilter::get_directory
\batchmode
\errmessage{}
\normalend}
\doifnot{\externalfilter::get_last_character\externalfilter::get_directory}{/}
- {\showmessage\externalfilter::id{slash}\externalfilter::get_directory
+ {\showmessage\m!externalfilter{slash}\externalfilter::get_directory
\edef\externalfilter::get_directory{\externalfilter::get_directory/}}
\stoptexdefinition
@@ -320,7 +322,7 @@
% Append directory name to the name of the output file
\edef\externalfilter::output_file{\externalfilter::get_directory\externalfilterparameter\c!output}
- \externalfilter::show_filenames
+ \iftraceexternalfilters \externalfilter::show_filenames \fi
\stoptexdefinition
@@ -330,7 +332,25 @@
\starttexdefinition externalfilter::process_filter
% By defualt, buffers are in memory in MkIV. So, we save them to disk
- \doifmode\s!mkiv{\savebuffer[\externalfilter::temp_file][\externalfilter::input_file]}
+ % To imitate the behavior of MkII, we need
+ %
+ % \doifmode\s!mkiv{\savebuffer[\externalfilter::temp_file][\externalfilter::input_file]}
+ %
+ % However, in MkIV, we can save a list of buffers to a file. The empty
+ % elements of the list are ignored. So, instead we use the following
+ %\doifmode\s!mkiv
+ %{\savebuffer[\externalfilterparameter{\c!buffer\c!before},\externalfilter::temp_file,\externalfilterparameter{\c!buffer\c!after}]
+ % [\externalfilter::input_file]}
+ \startmode[\s!mkiv]
+ \savebuffer[\externalfilterparameter{\c!buffer\c!before},
+ \externalfilter::temp_file,
+ \externalfilterparameter{\c!buffer\c!after}]
+ [\externalfilter::id]
+ \startluacode
+ os.rename("\jobname-\externalfilter::id.\f!temporaryextension", "\externalfilter::input_file")
+ \stopluacode
+ \stopmode
+
\externalfilter::execute_filter
\externalfilter::read_processed_file
@@ -351,10 +371,16 @@
\externalfilter::show_filtercommand
\doifelse{\externalfilterparameter\c!continue}\v!yes
- {\doifmode{*first}
- {\executesystemcommand
- {mtxrun --ifchanged=\externalfilter::input_file\space
- --direct \externalfilterparameter\c!filtercommand}}}
+ {\doifelse{\externalfilterparameter\c!state}\v!stop
+ {\showmessage\m!externalfilter{reuse}\externalfilter::input_file}
+ {\doifmode{*first}
+ {\doifmodeelse{force}
+ {\message{\externalfilterparameter\c!filtercommand}
+ \executesystemcommand
+ {\externalfilterparameter\c!filtercommand}}
+ {\executesystemcommand
+ {mtxrun --ifchanged=\externalfilter::input_file\space
+ --direct \externalfilterparameter\c!filtercommand}}}}}
{\executesystemcommand
{\externalfilterparameter\c!filtercommand}}
\stoptexdefinition
@@ -365,9 +391,10 @@
\doif{\externalfilterparameter\c!read}\v!yes
{\doiffileelse{\externalfilter::output_file}
{\externalfilter::read_processed_file_aux}
- {\showmessage\externalfilter::id{notfound}\externalfilter::output_file
+ {\showmessage\m!externalfilter{notfound}\externalfilter::output_file
+ \externalfilter::show_filenames
\blank
- {\tttf [[\getmessage\externalfilter::id{missing}]]}
+ {\tttf [[\getmessage\m!externalfilter{missing}]]}
\blank}}
\stoptexdefinition
@@ -402,12 +429,22 @@
\c!output=\externalfilterbasefile.tex,
\c!filter=,
\c!filtercommand={\externalfilterparameter\c!filter\space \externalfilter::input_file},
+ \c!buffer\c!before=,
+ \c!buffer\c!after=,
]
+\doifmodeelse{reuse}
+ {\setupexternalfilters[state=stop]}
+ {\setupexternalfilters[state=start]}
+
\def\externalfilterbasefile {\externalfilter::base_file}
\def\externalfilterinputfile {\externalfilter::input_file}
\def\externalfilteroutputfile{\externalfilter::output_file}
\def\currentexternalfilter {\externalfilter::name}
+
+% Default value
+\def\externalfilter::input_file {}
+\def\externalfilter::output_file{}
\protectmodulecatcodes
\stopmodule